Website maintenance#
The public GitHub Pages website lives in site/. It is a static bilingual site: index.html is English and zh.html is Chinese. Keep their content and anchors aligned. Both pages share styles.css and app.js.
Design and product previews#
Use the console's neutral background, white surfaces, thin borders, 8px card corners and blue primary actions. The homepage contains an interactive, clearly labeled illustration of applications, routes, metrics, delivery and observability. Its example.com domains and resource values are sample data, not a live cluster or a screenshot. Keep route-relationship descriptions distinct from connectivity or health checks.
The illustration uses native HTML and SVG and works without remote images. All 25 sidebar menus and submenus switch to distinct illustrative screens and synchronize the breadcrumb and selected state. The five shortcut tabs share that navigation state and support arrow keys, Home and End. Keep the menu targets and sample screens aligned between both languages. JavaScript also provides the mobile menu and command copying; core page content and documentation remain readable without JavaScript.
The Geist font is self-hosted under site/assets/fonts/ with its license. Chinese text uses the platform's CJK fonts. Existing brand assets remain available; the old decorative hero graphics are not loaded.
Build and preview#
Use Python 3.12, matching CI:
python -m venv /tmp/luma-site-venv
/tmp/luma-site-venv/bin/python -m pip install Markdown==3.8.2
/tmp/luma-site-venv/bin/python scripts/build-site.py
python scripts/check-site.py
python -m http.server 5182 --directory _site
Open http://localhost:5182/ or http://localhost:5182/zh.html. To emulate a project Pages prefix, copy the artifact into a luma/ directory and serve its parent. All local URLs must work under that prefix.
The build copies static assets and the raw documentation, then renders docs/**/*.md files (excluding internal docs/research/ notes) into an adjacent HTML page. Markdown tables, fenced code and page outlines are supported. Relative links to Markdown documentation are rewritten to HTML; links to repository code and directories point to GitHub. Mermaid fences remain code examples rather than executing a remote diagram renderer.
Edit Markdown source, not generated HTML. Add high-priority guides to GUIDES in scripts/build-site.py and update both homepage document links when appropriate. Do not commit _site/. Generated output carries a .luma-site-output marker; subsequent builds replace only marked output directories, and refuse to overwrite an unrelated nonempty directory.
Publishing#
.github/workflows/pages.yml builds and deploys the site when relevant changes reach main, or when manually dispatched. It installs the pinned Markdown renderer and publishes the _site artifact using GitHub Pages.
A local build is not a public release. Review the English and Chinese pages, narrow-screen navigation, preview tabs, command-copy behavior and documentation links before merging and publishing.
Chinese documentation#
Every public English guide has a sibling *.zh-CN.md translation. Documents originally written in Chinese keep their existing paths. Keep translations synchronized when updating prose; preserve commands, configuration keys and fenced examples exactly. The generated CLI help remains the literal terminal output in both languages. Run the CLI reference generator first, then copy its updated help blocks into the Chinese reference.
Chinese pages localize navigation and resolve document links to Chinese counterparts. Explicit heading IDs ({#original-heading-id}) preserve existing English section links and language-switch anchors. Add matching IDs when translating new sections. English and Chinese homepage links should point to the corresponding language. scripts/check-site.py checks Chinese coverage, translated code blocks, heading IDs and local links before publication.