## Summary Stands up a bilingual MkDocs site under `docs-site/`, published to GitHub Pages by a workflow that builds on every pull request and deploys only from `main`. Fourteen topics ship in English and Chinese: the quick start, self-hosting, Docker, the WebUI, the sandbox manual, the runtime architecture, the command reference, the repository layout, the developer workflow, the proactivity design and reference pair, the self-evolution map and the tracing API. This pull request is additive. Both READMEs keep their prose and gain one link to the site in the header row; trimming them is deliberately a second pull request, so the site can be confirmed live before anything depends on it. Key decisions: - **`docs-site/`, not `docs/`.** `docs/README.md` defines `docs/` as design notes and dated records, and `docs/plans/` is an archive explicitly not held to today's layout. A user manual has the opposite lifecycle. - **Full bilingual parity**, via the `mkdocs-static-i18n` suffix structure (`page.md` beside `page.zh.md`). Parity decays immediately without a guard, so a test fails when a page has no twin. - **Anchors are pinned on the Chinese side.** A CJK heading slugifies to nothing, so Markdown numbers it `_1`, `_2`, and inserting one heading renumbers every anchor below it, silently breaking links readers already hold. Each Chinese heading therefore states the anchor its English twin gets for free: 133 heading anchors, identical across the two languages, none positional. - **A left rail, not a top bar.** The header carries the brand, the search box and the navigation tree down the left; the table of contents on the right is one continuous polyline clipped to the headings currently on screen. - **No template overrides.** Material customises through `theme.custom_dir` with Jinja partials, those partials are `.html`, and `scripts/check_large_files.py` holds `.html` in `BLOCKED_ASSET_EXTENSIONS`. The skin is therefore one stylesheet remapping Material's own custom properties, plus one script for the table-of-contents rail. The brand mark is a `data:` URI for the same reason. - **An owner-signed `docs-site/` exemption zone** in AGENTS.md section 1.3. The i18n config carries the Chinese navigation labels, and `mkdocs.yml` is not `*.md`, so the blanket suffix exemption does not reach it. A contract test holds the AGENTS.md list and `EXEMPT_PREFIXES` equal, so both moved together. - **The site never links out to a file it does not host.** Documents that stay in the repository are named as plain paths rather than linked, and a guard fails a page that links to an external webpage or a repository-relative path. Two defects found and closed here rather than after publication. The Chinese site rendered an English sidebar: navigation labels live in `mkdocs.yml`, not in any page, so comparing the two languages' Markdown finds nothing and only the rendered output shows it. And a control could be present, sized, animated and answer `querySelector` while being unclickable, because a popup Material sized for a top bar landed outside the viewport once the header became a rail. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification All commands run at the pushed head, rebased onto `origin/main`. ``` make check-large-files exit 0 make check-source-language exit 0 make docs-build exit 0, 0 errors docs-site/site/index.html and docs-site/site/zh/index.html both present mkdocs_static_i18n: Translated 17 navigation elements to zh uv run pytest tests/test_docs_site.py tests/test_source_language_check.py \ tests/test_readme_scope_canon.py tests/test_docker_runtime.py \ tests/test_living_docs.py 44 passed uv run pytest tests/integration/test_docs_site_controls_e2e.py 13 passed pre-commit run --files <changed files> all hooks pass git diff --check clean ``` Anchor parity was measured on the built HTML rather than assumed: 14 page pairs, 133 heading anchors compared at h2 through h6, every one identical between the two languages and none positional. The controls are hit-tested rather than queried. `document.elementFromPoint` at the exact point a reader clicks must return the control itself, which is the only check that catches an off-viewport popup; the language switcher, the search panel, the repository link and the table-of-contents rail each pass it. The brand lockup is measured, not eyeballed. A failing test was written first and reported the wordmark sitting 4.00px below the mark's centre line; it is 0.00px after the fix, and a 4x screenshot puts the residual optical offset at 0.25px. Every guard this branch adds was confirmed to fail first. The brand-class guard was mutated from both sides in turn: renaming `.em-eyebrow` in the stylesheet turned it red, renaming `class="em-standfirst"` in `index.md` turned it red, and it is green again with both restored. The anchor guard was shown to catch both failure modes, a missing anchor and a wrong one. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk No behaviour change to any shipped code path. Nothing imports `docs-site/`, the new Makefile targets are additive, and the only change outside `docs-site/` and its tests is one link added to each README's header row. Rollback is deleting the branch: the site does not exist until Pages is enabled with `Source: GitHub Actions`, and every other change is inert without it. Disclosed residue, checked and deliberately not changed: - The README header now links to `https://evermind-ai.github.io/Raven/`, which 404s until Pages is enabled. It is the same URL the Documentation section already carries. - The `deploy` job is skipped on pull requests by design, so a green check here does not prove deployment works. The first real evidence is the `deploy` job's own conclusion on the `main` run after merge. - GitHub Pages is not enabled on this repository. Measured: `GET /repos/.../pages` returns 404. Under `Deploy from a branch` the uploaded artifact is silently ignored while the workflow still reports success, so the source must be set to `GitHub Actions`. - `tests/integration/` is excluded by `norecursedirs`, so the browser suite is a local guard and never runs in CI. - The self-hosting page's Makefile target, docker path and port claims are unguarded. They were equally unguarded in the README they came from, and the owner ruled against adding a guard for them. - The self-evolution SOP and the benchmark contract stay in the repository and are named as plain paths from the pages that reference them. The SOP is a translation of an upstream project's internal document and carries redaction placeholders, which is a publication decision rather than a formatting one. - `docs/plans/` still shows the pre-restyle `mkdocs.yml`. CONTEXT.md defines that directory as an archive of the tree as it stood, with an explicit rule against updating an old plan to match a later change. - The Chinese pages drop the brand's italic serif accent word. Cormorant Garamond carries no CJK glyphs, so it would fall back to another face without any sign. - The code font is Material's default Roboto Mono. The brand names four typefaces and no monospace, so none was invented for it. ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
54 lines
1.2 KiB
YAML
54 lines
1.2 KiB
YAML
name: Docs
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
pull_request:
|
|
|
|
concurrency:
|
|
group: docs-${{ github.workflow }}-${{ github.ref }}
|
|
cancel-in-progress: true
|
|
|
|
permissions:
|
|
contents: read
|
|
|
|
jobs:
|
|
build:
|
|
name: docs build
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 10
|
|
steps:
|
|
- uses: actions/checkout@v7
|
|
with:
|
|
fetch-depth: 0
|
|
- name: Install uv
|
|
uses: astral-sh/setup-uv@v8.2.0
|
|
with:
|
|
enable-cache: true
|
|
cache-dependency-glob: uv.lock
|
|
- name: Set up Python
|
|
run: uv python install 3.12
|
|
- run: uv run --frozen --group docs mkdocs build -f docs-site/mkdocs.yml --strict
|
|
- uses: actions/upload-pages-artifact@v5.0.0
|
|
with:
|
|
path: docs-site/site
|
|
|
|
deploy:
|
|
name: docs deploy
|
|
needs: build
|
|
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 10
|
|
concurrency:
|
|
group: docs-pages-deploy
|
|
cancel-in-progress: false
|
|
permissions:
|
|
pages: write
|
|
id-token: write
|
|
environment:
|
|
name: github-pages
|
|
url: ${{ steps.deployment.outputs.page_url }}
|
|
steps:
|
|
- id: deployment
|
|
uses: actions/deploy-pages@v5.0.1
|