moonbit-docs-maintainer

MoonBit Docs Maintainer

Use this skill for changes to the moonbitlang/moonbit-docs repository. It is a repo-maintenance router, not a MoonBit language tutorial.

First steps

1. Read the user request and classify the touched area before editing.
2. Inspect the relevant local files. Prefer existing layout and wording patterns.
3. Load only the reference file for the task area.
4. Make minimal, reviewable changes.
5. Run the narrowest validation command that proves the change.

Routing

• Sphinx docs in next/, Markdown pages, images, Sphinx config, or local docs builds: read references/sphinx.md.
• MoonBit examples under next/sources/, excluding next/sources/error_codes/: read references/examples.md.
• Error-code docs under next/language/error_codes/ or paired examples under next/sources/error_codes/: read references/error-docs.md.
• Translation catalogs under next/locales/ or gettext template updates: read references/translation.md.
• Interactive tour changes under moonbit-tour/: read references/tour.md.
• Typo, spelling, or prose lint changes involving typos or autocorrect: read references/typo.md.

If a task spans multiple areas, read the most specific reference first, then any secondary reference needed for validation.

Repository Map

• next/: Sphinx documentation site. Markdown sources live under next/. MoonBit example projects used by docs live under next/sources/.
• next/locales/<locale>/LC_MESSAGES/: gettext translation catalogs.
• moonbit-tour/: pnpm-based interactive language tour web app.
• legacy/: legacy docs and examples. Treat as reference unless the user asks to maintain it directly.
• scripts/: repo-level checks for examples and i18n helpers.
• justfile: preferred maintainer command entrypoints.

Tooling Commands

Prefer just recipes and uv-managed Python dependencies when available. Do not create ad-hoc virtualenvs unless the task explicitly requires one or uv is unavailable.

• just i18n: runs gettext extraction and catalog sync for zh_CN.
• just i18n ja: runs the i18n flow for another locale.
• just docs-html: builds the default Sphinx docs.
• just docs-html-zh: builds the Chinese Sphinx docs.
• just docs-html-ja: builds the Japanese Sphinx docs.
• just check-docs: checks non-error-code MoonBit examples under next/sources/.
• just check-errors: checks all error-code docs examples under next/sources/error_codes/.
• just check-error 0001: checks one four-digit error code.

If just is unavailable, use the task-specific fallback in the relevant reference. Example checks fall back to Python scripts; Sphinx and i18n tasks fall back to manual cd next commands.

General Rules

• Do not edit generated output such as next/_build/, moonbit-tour/dist/, or dependency directories.
• Keep examples runnable. When documentation references code in next/sources/, update docs and examples together.
• Avoid broad moon fmt runs in next/sources/; format only touched files when formatting is necessary.
• Preserve existing bilingual structure where it exists.
• Prefer functional style for new MoonBit code, and keep changes small.
• Use conventional commit messages if asked to commit; this is a repo-wide rule from AGENTS.md.

Validation

Choose the smallest useful check:

• Sphinx docs: just docs-html
• Chinese Sphinx build: just docs-html-zh
• Japanese Sphinx build: just docs-html-ja
• MoonBit docs examples: python3 scripts/check-document.py
• Error-code examples: python3 next/check_error_docs.py all
• One error code: python3 next/check_error_docs.py 0001
• Tour build: cd moonbit-tour && pnpm build
• Prose lint: autocorrect . --lint --no-diff-bg-color

If dependencies are missing or a full check is too expensive, run the closest targeted command and report the remaining risk.