Skip to content

Docs Site (GitHub Pages)

This documentation site is generated by MkDocs + Material and published automatically to GitHub Pages. The site is bilingual: Traditional Chinese and English.

Layout

Item Location
Content source (Traditional Chinese) docs/**/<page>.md
Content source (English) docs/**/<page>.en.md
Site config and navigation mkdocs.yml (nav and plugins.i18n)
Language-switch shim docs/javascripts/lang-switch.js
Build output site/ (generated by mkdocs, not in git, never edit by hand)
Deploy workflow .github/workflows/deploy-docs.yml
Published URL https://healthymind-tech.github.io/Taiwan-Health-MCP

MkDocs builds every .md under docs/, even one that never appears in nav. A file left off the navigation is still published publicly — it just has no entry point.

Bilingual rule (most important)

Every content change must update both languages

Every page exists as two files: <page>.md (Traditional Chinese) and <page>.en.md (English).

Any content change must be applied to both files, in the same commit. Changing only one side lets the two languages drift apart silently — and because fallback_to_default is enabled, a missing translation does not fail the build. It quietly serves the Chinese page instead, so the gap can hide for a long time.

When adding a page, create both .md and .en.md at once, add the entry to nav in mkdocs.yml, and add its English title to nav_translations.

Check for missing translations:

# List pages that exist in Chinese but have no English counterpart
comm -23 \
  <(find docs -name '*.md' ! -name '*.en.md' | sed 's/\.md$//' | sort) \
  <(find docs -name '*.en.md' | sed 's/\.en\.md$//' | sort)

The only expected output today is these three pages: docs/datasets, docs/MinerU-vs-OpenAI, and docs/ocr-test-setup. They are not in nav and nothing links to them (datasets.md even opens by declaring itself an outdated Python-era document), so they have not been translated; the English site falls back to showing the Chinese original for them. Anything else appearing in that output is a missing translation and must be filled in.

Languages and URLs

Language URL
Traditional Chinese (default) https://healthymind-tech.github.io/Taiwan-Health-MCP/<page>/
English https://healthymind-tech.github.io/Taiwan-Health-MCP/en/<page>/

Both static trees are produced by mkdocs-static-i18n in docs_structure: suffix mode. The language selector in the Material header is generated by the plugin.

Switching with a URL parameter

Besides the selector, any page accepts a ?lang= parameter:

Parameter Effect
?lang=en Switch to the English page
?lang=zh-TW Switch to the Traditional Chinese page

For example, .../Taiwan-Health-MCP/deployment/?lang=en redirects to .../Taiwan-Health-MCP/en/deployment/.

This lives in docs/javascripts/lang-switch.js. GitHub Pages is purely static and cannot route on a query string, so the parameter is read client-side and the page location.replace()s to the matching path, dropping the parameter from the address. Common spellings such as zh, zh-hant, tw, and en-US are normalised.

The canonical URL of each language is still the path form (/ and /en/). ?lang= is an entry point only; search indexing and deep links use the canonical URLs.

Local preview

The docs toolchain is unrelated to the project runtime (the project itself has no Python dependency):

pip install -r requirements-docs.txt
mkdocs serve          # http://127.0.0.1:8000
mkdocs build --strict # verification: any warning is an error

To iterate faster on a single language:

mkdocs build --strict -f mkdocs.yml   # both languages
# or temporarily add build_only_locale: en to the i18n config in mkdocs.yml

Deployment

.github/workflows/deploy-docs.yml:

  1. Trigger: a push to main whose changes touch docs/**, mkdocs.yml, or the workflow itself. (Changing only README.md or source code does not rebuild the site.)
  2. Build: Python 3.11, install requirements-docs.txt, run mkdocs build --strict.
  3. Publish: peaceiris/actions-gh-pages@v3 pushes ./site to the gh-pages branch (needs contents: write, using the built-in GITHUB_TOKEN).

No custom domain is configured (no CNAME). .nojekyll is written to the publish branch automatically by peaceiris/actions-gh-pages; it does not need to be maintained in the repository.

Known limitations

  • The search index is shared by both languages. mkdocs-static-i18n emits a single merged search_index.json, so searching on the English site can surface Chinese pages and vice versa. The plugin only removes entries whose content is byte-identical (that is, untranslated fallback pages).
  • MkDocs generates anchor ids like _1 / _2 for headings written purely in Chinese, and those ids shift as headings are added or removed. Give any Chinese heading you need to link to an explicit id via attr_list:

markdown ## 對外埠與強化 { #external-ports }

Content maintenance principles

  • Update Chinese and English together (see the bilingual rule above).
  • The code is the single source of truth. When docs and code disagree, fix the docs — do not change code to match the docs.
  • After adding a page, remember to add it to nav in mkdocs.yml, or users cannot find it (it is still published).
  • Never edit site/ (build output).
  • Command examples must run as-is from the directory the text specifies; use port :8080 (the nginx front door), never :8000.
  • For planning documents that are finished or superseded, add a status note at the top (every historical document on this site does this) rather than deleting them — they are decision records.
  • The public-facing marketing and legal pages (/, /status, /privacy, /dpa) are no longer part of this repo — they moved to a standalone marketing site. The web service here only serves the /admin console.