Skip to content

Move GitBook {% hint %} conversion upstream into the guidebook repo (remove transitional staging workaround) #8

Description

@sanchuanhehe

Background

PR #7 (fixing #4) made GitBook {% hint style="..." %}...{% endhint %} callouts render correctly by rewriting them into MyST admonitions at build time in the staging tree, via tools/convert_gitbook.py (invoked from tools/prepare-source.sh).

This is a transitional workaround, deliberately chosen so we don't fork/modify editorial content in the guidebook submodule. It is not the intended long-term state.

Why it's temporary / the problem

  • The source of truth (theopensourceway/guidebook) still contains GitBook-specific syntax that no current renderer (MyST/Sphinx) understands.
  • The conversion only exists in this production build pipeline, so anyone consuming the guidebook directly still sees broken {% hint %} markers.
  • It adds a build-time transform + maintenance surface (tools/convert_gitbook.py, an extra prepare-source.sh step) that has to be kept in sync with whatever hint styles appear upstream.

Proposed long-term fix

  1. Convert {% hint style="..." %}...{% endhint %} to MyST admonitions directly in the guidebook repo source Markdown:
    • successtip
    • infonote
    • warningwarning
    • dangerdanger
  2. Once upstream is converted, remove tools/convert_gitbook.py and its invocation in tools/prepare-source.sh.
  3. Re-extract gettext catalogs and confirm zh_CN .po msgids are unchanged (the admonition body text is the translatable unit, so translations should carry over).

Acceptance criteria

  • No {% hint %} / {% endhint %} syntax remains in the guidebook repo source.
  • tools/convert_gitbook.py and the prepare-source.sh conversion step are removed.
  • EN and zh_CN HTML + PDF still render the admonitions correctly.
  • zh_CN catalogs remain current (git diff --exit-code -- locales passes in CI).

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions