jacobinwwey_obsidian-NotEMD/docs/maintainer/github-pages-language-geo-workflow.md

GitHub Pages Language And GEO Workflow

Language: English | 简体中文

This workflow records the current public documentation-site gate for website/. It is intentionally separate from runtime plugin i18n and from Slidev export acceptance.

Current Contract

The website publishes one complete language surface and one partial language surface:

1. English is the canonical complete documentation surface under https://jacobinwwey.github.io/obsidian-NotEMD/docs/....
2. Simplified Chinese currently publishes the homepage and FAQ only.
3. Untranslated zh-CN fallback docs may still be generated by Docusaurus, but they must be fenced with noindex,follow and excluded from the zh-CN sitemap.
4. zh-CN homepage entry points for untranslated docs must route to canonical English URLs, not to /zh-CN/docs/... fallback pages.
5. llms.txt must describe the same language boundary so answer engines do not infer full multilingual coverage.

Implemented Gate

The blocking gate is:

cd website
npm run build
npm run audit:build

npm run audit:build executes website/scripts/audit-build.cjs. The script checks the built output, not just source files:

1. root pages exist: build/index.html and build/zh-CN/index.html;
2. root pages have the expected lang, canonical URL, and WebPage JSON-LD URL;
3. zh-CN homepage links untranslated critical docs to canonical English URLs;
4. zh-CN homepage keeps FAQ on /zh-CN/docs/faq;
5. untranslated zh-CN docs emit noindex,follow;
6. published zh-CN FAQ does not emit noindex,follow;
7. sitemap output includes canonical English docs and excludes untranslated zh-CN docs;
8. llms.txt records the language scope.

The GitHub Pages workflow now runs this audit before uploading the Pages artifact:

.github/workflows/deploy-docs.yml
  -> npm run build
  -> npm run audit:build
  -> upload-pages-artifact

Source Ownership

The language scope is shared through:

website/src/lib/publishedLanguageScope.js

Current values:

publishedZhCnDocIds = faq
publishedZhCnDocPaths = /docs/faq

This module is consumed by:

1. website/docusaurus.config.js for sitemap filtering;
2. website/src/theme/DocItem/Layout/index.js for fallback-doc noindex,follow;
3. website/src/pages/index.js for zh-CN homepage routing.

This avoids a previous drift pattern where sitemap, noindex, and homepage links each carried a separate copy of the same exception.

For canonical English links rendered from a zh-CN page, use the canonical origin-relative path with autoAddBaseUrl: false and data-noBrokenLinkCheck. Docusaurus checks broken links against the current locale route table, so these intentional cross-locale links must not be "fixed" back to localized fallback routes. npm run audit:build is the guard that proves the final path is correct.

What Was Wrong

The previous Pages state was better than the old roadmap, but still incomplete:

1. Docusaurus generated untranslated zh-CN fallback docs.
2. Those fallback docs were noindexed and removed from sitemap, which protected crawlers.
3. The zh-CN homepage, navbar, and footer still linked users into /zh-CN/docs/intro and similar fallback routes.
4. The deploy workflow only ran npm run build; it did not enforce the language route contract.

That means the site could pass build while still presenting a weak public language surface. noindex is not enough when the UI itself sends readers to the wrong locale route.

Better GEO Direction

The better GEO strategy is still truth-first:

1. keep English canonical until specific zh-CN pages are fully translated and reviewed;
2. only promote a zh-CN doc path by adding it to publishedLanguageScope.js in the same batch as the translation;
3. require npm run audit:build before Pages deploy;
4. keep llms.txt, sitemap, homepage links, and noindex behavior aligned;
5. expand or consolidate thin provider pages before adding more locale surfaces.

Do not use empty locale folders or fallback English pages as GEO surface area. That produces weak hreflang signals and worse user trust.

Next Direction

1. Translate and review the zh-CN critical path in this order: intro, installation, quick-start, configuration, provider overview, AI knowledge pillar.
2. Each translated page promotion must update publishedLanguageScope.js and rerun npm --prefix website run build && npm --prefix website run audit:build.
3. Add a small provider-page quality audit only after the language route gate stays stable; provider thinness is a content quality problem, not a routing problem.
4. Keep generated website/build output ignored and uncommitted.