You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Move GitBook {% hint %} conversion upstream into the guidebook repo (remove transitional staging workaround) #8
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
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).
Activity