Publish the bilingual documentation

.github/workflows/docs.yml builds two Just the Docs sites and deploys a combined Pages artifact. Each language has independent navigation and search.

Enable or migrate Pages

  1. Push the documentation and workflow to main.
  2. Open Pages settings.
  3. Set Build and deployment → Source → GitHub Actions.
  4. In Actions, open Documentation.
  5. If the initial push preceded Pages enablement, use Run workflow on main.
  6. Wait for build and deploy, then open Visit site in Pages settings.

Change the previous branch-based main + /docs method. See GitHub’s custom workflow guide.

URLs and updates

Old top-level .html URLs redirect to matching Chinese pages; JavaScript preserves query strings and fragments. Documentation changes on Chal1ce/FinFlow’s main publish automatically. Pull requests, the private fin-doc-governance mirror, and other repositories only build: they neither upload Pages artifacts nor deploy. A Skipped deploy job is expected in those runs. Manual publication also requires the public repository’s main. See Writing docs. The common configuration is docs/_config.yml; Just the Docs is fixed at v0.12.0.

Local build

With Ruby 3.3 and Python 3 installed:

BUNDLE_GEMFILE=docs/Gemfile bundle install
python3 scripts/prepare_docs.py
BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build --source _build/docs-source/zh --destination _site/zh --config _build/docs-source/zh/_config.yml,_build/docs-source/zh/_config.language.yml
BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build --source _build/docs-source/en --destination _site/en --config _build/docs-source/en/_config.yml,_build/docs-source/en/_config.language.yml
python3 scripts/prepare_docs.py --finalize

Generated files are ignored by Git. Builds do not call OCR/models. Dependencies, theme downloads, and Mermaid need internet. For renaming, change the script’s default base URL and repository links. For a custom domain, update url, pass --baseurl '' to both workflow script steps, and configure the domain in Pages. To publish from a renamed repository or a fork, also update both github.repository == 'Chal1ce/FinFlow' conditions in the upload step and deploy job.

Troubleshooting

Confirm GitHub Actions is the Pages source and the workflow is on main. Read the failing step: build errors may involve front matter, missing translation revisions, dependencies, or theme downloads; deployment errors may involve Pages enablement, permissions, or environment restrictions. Check deployment success before investigating a 404. URL casing must match FinFlow. Committing a workflow alone does not enable Pages.

For No artifacts named "github-pages", inspect the upload log and Artifacts list for the same run. If the upload succeeded but the artifact is unavailable, select Re-run all jobs in the public repository to rebuild and upload it again, instead of rerunning only deploy. If it persists, check GitHub Actions/Pages service status and whether the artifact was deleted.