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
- Convert
{% hint style="..." %}...{% endhint %} to MyST admonitions directly in the guidebook repo source Markdown:
success → tip
info → note
warning → warning
danger → danger
- Once upstream is converted, remove
tools/convert_gitbook.py and its invocation in tools/prepare-source.sh.
- 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
References
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, viatools/convert_gitbook.py(invoked fromtools/prepare-source.sh).This is a transitional workaround, deliberately chosen so we don't fork/modify editorial content in the
guidebooksubmodule. It is not the intended long-term state.Why it's temporary / the problem
theopensourceway/guidebook) still contains GitBook-specific syntax that no current renderer (MyST/Sphinx) understands.productionbuild pipeline, so anyone consuming the guidebook directly still sees broken{% hint %}markers.tools/convert_gitbook.py, an extraprepare-source.shstep) that has to be kept in sync with whatever hint styles appear upstream.Proposed long-term fix
{% hint style="..." %}...{% endhint %}to MyST admonitions directly in theguidebookrepo source Markdown:success→tipinfo→notewarning→warningdanger→dangertools/convert_gitbook.pyand its invocation intools/prepare-source.sh..pomsgids are unchanged (the admonition body text is the translatable unit, so translations should carry over).Acceptance criteria
{% hint %}/{% endhint %}syntax remains in theguidebookrepo source.tools/convert_gitbook.pyand theprepare-source.shconversion step are removed.git diff --exit-code -- localespasses in CI).References
growing-contributors/community-manager-self-care.md,attracting-users/communication-norms-in-open-source-software-projects.md