HagiCode Documentation

简体中文

This repository contains the standalone HagiCode documentation site built with Astro and Starlight.

Product overview

The docs site is where users learn the platform: product overviews, installation guides, tutorials, blog posts, and downloadable configuration presets all live here.

RSS feeds

Hagilight Starlight generates localized feeds from documentation content using its default configuration. Starlight Blog generates its standard /blog/rss.xml feed; the site does not define custom RSS item selection or language-specific blog feed routes.

What the site covers

• Product introductions and onboarding guides for new users
• Step-by-step installation and configuration documentation
• Blog content and updates for the HagiCode ecosystem
• Preset files and static assets referenced by public docs pages

Repository layout

• src/content/docs/ - baseline Chinese docs and shared docs assets
• src/content/translations/docs/<locale>/ - non-baseline localized authoring files using canonical source locale codes
• src/content/.generated/docs/ - build-time assembled Starlight input tree generated by npm run prepare:docs-content
• src/data/articles.snapshot/<locale>/ - structured *-vs-hagicode article snapshot files mirrored from the published repos/index article manifests
• src/components/ and src/layouts/ - site UI building blocks
• public/ - static assets, downloadable presets, and shared media
• scripts/ and tests/ - verification helpers for docs quality and routing behavior

Local development

npm install
npm run dev
npm run build
npm run preview

The local docs server runs on http://localhost:31265 by default.

Structured article snapshots

npm run sync:articles-snapshot refreshes the locale-folder structured article snapshot consumed by the *-vs-hagicode FAQ routes. By default it fetches the published dataset from https://index.hagicode.com so repos/docs does not depend on a sibling repos/index checkout. The preferred verification path is:

cd repos/docs && npm run sync:articles-snapshot

Use DOCS_ARTICLES_PUBLISHED_ROOT=/absolute/or/relative/path/to/dist or npm run sync:articles-snapshot -- --published-root <path> only when you intentionally want to test against a specific local published build. npm run sync:articles-snapshot -- --no-remote still reuses the committed snapshot when you explicitly need offline or pinned local verification. npm run prepare:docs-runtime now syncs the article snapshot before npm run prepare:docs-content, and prepare:docs-content synthesizes the faq/*-vs-hagicode.mdx pages directly into src/content/.generated/docs/ instead of keeping those shell pages under source authoring trees.

GitHub Actions

• .github/workflows/docs-ci.yml validates pushes and pull requests targeting main.
• .github/workflows/docs-deploy-gh-pages.yml publishes a validated gh-pages payload for pushes to main and workflow_dispatch.
• The gh-pages payload contract is branch-root esa.jsonc, wrangler.jsonc, and dist/ containing the validated Astro snapshot assembled after npm run build:ci succeeds.
• The build job stays read-only and uploads the validated payload artifact; gh-pages remains authoritative and only the deploy job receives contents: write.
• Manual workflow_dispatch runs rebuild from the selected ref, validate with npm run build:ci, and republish the resulting payload to gh-pages.
• Direct Cloudflare publication is handled outside this workflow; keep gh-pages/wrangler.jsonc as the versioned Wrangler contract used by direct publish operations.
• Existing workflows remain in place: .github/workflows/docs-ci.yml, .github/workflows/azure-static-web-apps-agreeable-stone-04924c800.yml, .github/workflows/compress-images.yml, and .github/workflows/indexnow.yml are additive peers, not replaced by the new workflow.
• Treat host cutover as a separate operational step: adding the workflow does not prove docs.hagicode.com already reads gh-pages/esa.jsonc, the Wrangler contract in gh-pages/wrangler.jsonc, and gh-pages/dist/.
• Follow-up checks before treating docs.hagicode.com as a gh-pages consumer: confirm the workflow published esa.jsonc, wrangler.jsonc, and dist/, verify the hosting target still points at gh-pages, and then load https://docs.hagicode.com from the deployed branch snapshot.
• This change migrates only repos/docs; repos/awesome-design-md-site, repos/cost, repos/index, repos/soul, repos/trait, and repos/docker-compose-builder-web remain unchanged follow-up migration candidates.
• .github/workflows/compress-images.yml and .github/workflows/indexnow.yml handle repository maintenance automation.

hagi18n maintenance workflow

Docs UI strings are maintained with @hagicode/hagi18n from this repository. The source of truth is the YAML tree under src/i18n/locales/<locale>/; generated runtime resources are committed under src/i18n/generated/ because astro.config.mjs imports them during config evaluation.

Use these commands from repos/docs:

npm run i18n:audit
npm run i18n:doctor
npm run i18n:generate
npm run i18n:check

npm install installs the project-local hagi18n CLI. To verify CLI availability directly, run npx hagi18n info or any script above.

Updating UI translations

Edit YAML files in src/i18n/locales/en-US/ and src/i18n/locales/zh-CN/. Keep namespace files, scalar key paths, and {{placeholder}} tokens aligned between locales. Run npm run i18n:audit or npm run i18n:doctor, then run npm run i18n:generate to refresh src/i18n/generated/docs-locale-resources.mjs.

npm run i18n:check combines hagi18n validation with a stale generated-resource check. npm run dev, npm run build, and npm run typecheck run prepare:docs-runtime first so both generated locale resources and the assembled docs content tree exist before Astro or TypeScript consumes them.

Safe sync and prune commands

Sync and prune default to dry-run previews:

npm run i18n:sync
npm run i18n:prune

Only the explicit write variants mutate locale source files:

npm run i18n:sync:write
npm run i18n:prune:write

Content boundary

hagi18n manages docs UI strings, blog plugin UI labels, Starlight locale metadata, and common selector labels. MDX documentation pages and blog posts now use a split authoring contract:

• Baseline Chinese content lives under src/content/docs/.
• Non-baseline localized authoring files live under src/content/translations/docs/<source-locale>/.
• Astro/Starlight reads the generated build input under src/content/.generated/docs/, produced by npm run prepare:docs-content.

When adding or updating localized docs, keep the canonical doc key identical to the baseline file path and use canonical locale directory names such as en-US, ja-JP, or zh-Hant.

Shared Starlight presentation

Hagilight 0.4.0 owns the Starlight header, footer, language chooser, reading-width control, AI disclosures, article promotion, and 404 recovery. Docs maps its generated locale routes and labels onto Hagilight's locale catalog by lang, preserving the root Chinese route and /en-US/ path. Docs also keeps the localized promotion fallback and PageFrame composition, site metadata and analytics, AI frontmatter defaults, and blog-specific metadata, ads, CTA, and image lightbox.

Documentation pages show Hagilight's article promotion by default. Set hagicodePromotion: false in frontmatter to opt out. Blog posts opt out by default to avoid competing with blog promotions; set hagicodePromotion: true to enable the article promotion on an individual post. Existing isAITranslation, isAIAuthor, hideAd, and hideCta frontmatter controls remain supported.

After building, npm run verify:hagilight-build checks localized navigation, preference migration, shared shell composition, blog and release-note content, 404 recovery, and standalone redirects.

Translation coverage reports

Use these commands to see which docs pages, blog posts, or locales are still untranslated:

npm run report:translation
npm run report:docs-translation
npm run report:blog-translation

npm run report:translation writes a combined summary to .tmp/translation-report.json and refreshes the per-surface JSON reports in .tmp/docs-translation-report.json and .tmp/blog-translation-report.json. The combined output shows per-locale coverage for baseline Chinese docs pages and blog slugs, plus missing, duplicate, and high-similarity findings.

Pi CLI translation autofill

To fill missing translations directly from the zh-CN source content with the local Pi CLI, run:

npm run translate:missing:pi

Default behavior only creates files for entries that are still missing in the translation reports. To also rewrite files that are flagged as exact duplicates of the zh-CN baseline, run:

npm run translate:missing:pi -- --include-duplicates

Useful filters:

npm run translate:missing:pi -- --surface blog --locales en-US,ja-JP --limit 5 --dry-run

This workflow calls local pi CLI and asks it to translate Markdown/MDX directly from repository source files. It does not use separate machine-translation API. Default model is gh/gpt-codex-5.3 (override with --model or PI_MODEL). Script writes docs translations to src/content/translations/docs/<locale>/...; blog translations currently follow blog report layout under src/content/docs/<locale>/blog/....

Screenshot analysis workflow

The managed screenshot sync flow reads repos/docs/.env before it launches ImgBin. The repository default for image analysis is:

• IMGBIN_ANALYSIS_PROVIDER=codex
• IMGBIN_CODEX_MODEL=lemon/gpt-5.4
• IMGBIN_CODEX_BASE_URL=http://localhost:36129/v1

Copy ./.env.example to .env when you need a local config file for npm run screenshots:sync.

Desktop version data

Desktop download data is fetched at runtime from the canonical index endpoint published by repos/index. When runtime loading reaches terminal failure, docs falls back to the Index Desktop history page at https://index.hagicode.com/desktop/history/. repos/index remains a referenced dependency only; the stable fallback surface is https://index.hagicode.com/desktop/history/ plus https://index.hagicode.com/desktop/index.json. This repository still serves public/version-index.json as a local snapshot for offline fallback, but maintainers should investigate the runtime fetch chain and the index deployment before changing docs UI behavior. Repository-scoped update detail pages are no longer hosted in this docs site. A future change will introduce the replacement version update information surface.

Release-notes sync workflow

The replacement release-notes surface now lives in this repository under src/content/docs/release-notes/, src/content/translations/docs/en-US/release-notes/, and the managed src/data/release-notes/ directory. Managed outputs are generated from the authoritative repos/release-notes workspace data. For monorepo automation, the preferred path is direct repository-to-repository transfer. GitHub Release assets remain only as an optional fallback source for standalone sync jobs. hagirepocron is expected to reach this repo only after release-notes has produced a complete bilingual published dataset for each tag.

Commands

npm run release-notes:fetch
npm run release-notes:materialize
npm run release-notes:sync
npm run verify:release-notes:input
npm run verify:release-notes:output
npm run test:release-notes

# Monorepo / cron path: read release-notes directly from a sibling checkout
DOCS_RELEASE_NOTES_SOURCE=local \
DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT=../release-notes \
npm run release-notes:sync

Source modes

• DOCS_RELEASE_NOTES_SOURCE=local
  • Reads artifacts/tags/<tag>/<tag>.json and published/<tag>.<locale>.md directly from DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT.
  • This is the intended mode for hagirepocron and other same-machine orchestration.
• DOCS_RELEASE_NOTES_SOURCE=github
  • Fetches GitHub Releases plus release-notes-<tag>-history.zip assets from DOCS_RELEASE_NOTES_REPOSITORY.
  • Use this only when docs runs without access to a sibling release-notes checkout.
• DOCS_RELEASE_NOTES_SOURCE=auto
  • Default mode.
  • Uses local mode when DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT is set; otherwise falls back to GitHub mode.

Local repository contract

• Each synchronized tag must provide artifacts/tags/<tag>/<tag>.json.
• Each synchronized tag must also provide published/<tag>.zh-CN.md and published/<tag>.en.md.
• In the monorepo cron path, these published bilingual files are expected to come from the upstream release-notes AI preparation step before docs sync begins.
• Tags with missing JSON, malformed JSON, tag mismatches, or incomplete locale bodies are skipped with deterministic reasons and do not publish partial pages.

GitHub fallback asset contract

• The GitHub fallback workflow only accepts assets named release-notes-<tag>-history.zip.
• Each accepted archive must contain artifacts/tags/<tag>/<tag>.json.
• Each accepted archive must also contain published/<tag>.zh-CN.md and published/<tag>.en.md.

Automation and troubleshooting

• .github/workflows/release-notes-sync.yml runs daily and via workflow_dispatch.
• In the monorepo cron path, hagirepocron sets DOCS_RELEASE_NOTES_SOURCE=local and passes the sibling release-notes checkout root, so docs no longer depends on published release assets to materialize pages.
• Docs-managed output now uses src/data/release-notes/index.json plus src/data/release-notes/<tag>.json, together with src/content/docs/release-notes/index.mdx and src/content/translations/docs/en-US/release-notes/index.mdx.
• The lightweight index keeps browse metadata only; detailed rendered bodies live in the per-tag JSON files generated inside this repository.
• Incomplete upstream tags must not create partial detail files or extra docs routes.
• npm run build runs release-notes input verification before Astro and output verification after Astro. Empty release-notes pages are valid only when src/data/release-notes/index.json has zero entries; if entries exist, missing detail JSON, missing localized body HTML, missing anchors, or empty-state output must fail the build.
• The workflow uses DOCS_RELEASE_NOTES_TOKEN for upstream GitHub API access and falls back to the repository GITHUB_TOKEN only when that token already has cross-repository visibility.
• In CI, DOCS_RELEASE_NOTES_ALLOW_STALE_ON_SOURCE_ERROR=true keeps the job green when the upstream repository is temporarily inaccessible and existing managed outputs are already present.
• The sync scripts depend on the standard zip and unzip utilities in addition to Node.js.
• If the sync job reports skipped tags in local mode, inspect the source files in release-notes first; in GitHub mode, inspect the published asset contents.
• If release discovery returns 404, treat it as an authentication or repository-access problem first and verify that DOCS_RELEASE_NOTES_TOKEN can read HagiCode-org/release-notes.
• For monorepo-local development, prefer DOCS_RELEASE_NOTES_SOURCE=local plus DOCS_RELEASE_NOTES_LOCAL_REPO_ROOT.

Ecosystem role

Use this repository when the goal is end-user education and public documentation. Product storytelling lives in repos/site, while application behavior lives in repos/web, repos/hagicode-desktop, and repos/hagicode-core.