Skip to content

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

@sanchuanhehe

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions