feat(docs): add KP:1 spec home page with CITATION-driven metadata#46
Conversation
A static, self-contained spec home served from /docs via GitHub Pages: - Typeset and accessible (WCAG AA); preserves the citation and Dublin Core metadata for Scholar/Crossref indexing, and adds an Open Graph image. - Self-hosted display/text/mono webfonts; no external runtime dependencies. - A self-demonstrating KP:1 fragment shows the format's own notation. scripts/build_docs.py projects version, date, DOIs, and licence from CITATION.cff into the page so they cannot drift: `make docs` writes them and `make docs-check` verifies. Enforced by a CI step and a pre-commit hook. Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a static KP:1 specification home page under /docs (for GitHub Pages) and introduces tooling/CI guards to keep its citation/release metadata automatically synchronized with CITATION.cff.
Changes:
- Add
docs/index.html(self-contained landing page) plus supporting static assets for a GitHub Pages spec home. - Add
scripts/build_docs.pyand Makefile targets to project version/date/license/DOIs fromCITATION.cffinto the page (with a--checkmode). - Enforce metadata sync via pre-commit (
lefthook.yml) and CI (.github/workflows/ci.yml).
Reviewed changes
Copilot reviewed 5 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/build_docs.py | New sync/check script that injects CITATION-driven metadata into docs/index.html. |
| Makefile | Adds docs / docs-check convenience targets to run the metadata sync/check. |
| lefthook.yml | Adds a pre-commit guard to block commits when docs/index.html is out of sync with CITATION.cff. |
| docs/kp.svg | Adds a small SVG mark used by the docs page. |
| docs/index.html | Adds the static spec home page with citation/OpenGraph/Dublin Core metadata and body anchors for CITATION-driven fields. |
| docs/.nojekyll | Disables Jekyll processing so Pages serves files as-is. |
| .github/workflows/ci.yml | Adds a CI step to enforce docs/index.html metadata stays in sync with CITATION.cff. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| if len(concept_hits) != 1: | ||
| fail(f"expected exactly one concept DOI (description containing 'concept'); found {len(concept_hits)}") | ||
| if len(version_hits) != 1: | ||
| fail(f"expected exactly one DOI whose description names {version!r}; found {len(version_hits)}") |
| def meta(name: str, value: str, html: str) -> str: | ||
| # Tolerate attribute order/spacing so an IDE reformat of <head> can't | ||
| # silently skip a field (a true miss still fails loudly via search()). | ||
| pat = re.compile(r'(<meta[^>]*\bname="' + re.escape(name) + r'"[^>]*\bcontent=")([^"]*)(")') | ||
| mt = pat.search(html) |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4a43d205d1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @@ -0,0 +1,440 @@ | |||
| <!DOCTYPE html> | |||
There was a problem hiding this comment.
Because this commit adds the public Pages content as docs/index.html, it falls outside the repository's public-text guards: the CI leak scan only includes md/txt/yml/yaml/json/cff/toml, and the mirrored lefthook globs use the same set. Prohibited process language or private engagement names added to this home page would therefore pass the guards and be publishable; please add *.html to the workflow and hook scans alongside the new page.
Useful? React with 👍 / 👎.
…ml, Canela favicon - build_docs.py: match <meta> tags order-independently (lookahead) so an HTML reformat cannot silently skip a field; correct the concept-DOI error message to name the wording it actually matches. - ci.yml + lefthook.yml: include *.html in the public-text leak/deny scans so the published page is covered, not only md/yml/etc. - kp.svg: redraw the favicon as the genuine Canela "KP:1" (real K/P/1 outlines plus a matched colon). Co-Authored-By: Claude <noreply@anthropic.com>
KP:1 spec home page
Adds a static, self-contained spec home served from
/docsvia GitHub Pages.The page
Metadata can't go stale
scripts/build_docs.pyprojects the version, release date, DOIs, and licence fromCITATION.cffinto the page.make docswrites them;make docs-checkverifies. A CI step and a pre-commit hook fail if the page falls out of sync withCITATION.cff.After merge
Enable Pages: Settings → Pages → Source
main//docs. The page goes live at https://tymofiy.github.io/kp/.