GitBook {% hint %} blocks not rendered — displayed as literal text

[sanchuanhehe]

Description

The source Markdown files use GitBook-specific {% hint style="..." %}...{% endhint %} syntax for callout/admonition blocks. MyST/Sphinx does not support this syntax, so the {% hint %} and {% endhint %} markers are rendered as literal text in the output, and the hint content is displayed as a regular paragraph without any callout styling.

This affects both the English and Chinese versions.

Affected pages and instances

attracting-users/communication-norms-in-open-source-software-projects.html — 4 hint blocks

• style="success": "Develop a style guide for your project..."
• style="success": "In your project's 'getting started' guide for new users..."
• style="success": "If your project carries on most of its development discussions..."
• style="success": "People who are not native speakers of English..."

growing-contributors/community-manager-self-care.html — 1 hint block

• style="danger": "Materials in this chapter are for informational purposes only..."

Total: 5 hint blocks in each language (10 across both).

Expected rendering

These should be rendered as Sphinx admonition directives:

• style="success" → .. admonition:: or .. tip:: with a success/tip style
• style="danger" → .. warning:: or .. danger:: with a warning style

Suggested fix

1. Convert in source Markdown: Replace {% hint style="success" %}...{% endhint %} with MyST admonition syntax:

   ```{admonition} Tip
   :class: tip
   Content here
   ```

   And {% hint style="danger" %}...{% endhint %} with:

   ```{warning}
   Content here
   ```

2. Or add a pre-processing step in prepare-source.sh to automatically convert GitBook hint syntax to MyST admonition directives during the build.

3. The mapping from GitBook hint styles to Sphinx directives:

   • style="success" → {admonition} with :class: tip or {tip}
   • style="info" → {note} or {seealso}
   • style="warning" → {warning}
   • style="danger" → {danger} or {warning}