Skip to content

docs: replace Sync/Async MkDocs tabs with GitHub-native <details> blocks#167

Merged
martinkersner merged 1 commit into
mainfrom
issue-166-sync-async-readme-details
Jul 4, 2026
Merged

docs: replace Sync/Async MkDocs tabs with GitHub-native <details> blocks#167
martinkersner merged 1 commit into
mainfrom
issue-166-sync-async-readme-details

Conversation

@martinkersner

Copy link
Copy Markdown
Member

Closes #166

What

Replace Material-for-MkDocs === "Sync"/"Async" content-tabs with GitHub-native collapsible <details markdown="1"><summary>Sync|Async</summary> blocks in the README and 16 docs pages. Enable md_in_html in mkdocs.yml so fenced code inside <details> still highlights on the ReadTheDocs site.

Why

=== "Sync" renders as literal text on GitHub and the 4-space-indented fenced code beneath it loses syntax highlighting. <details> renders correctly on both GitHub and MkDocs.

Changed

  • 34 tab blocks -> <details> across README.md + 16 docs/*.md (docs/index.md is a symlink to README, so it's covered automatically -> 36 blocks total).
  • mkdocs.yml: added - md_in_html to markdown_extensions. Left pymdownx.tabbed in place (removal not in scope; harmless once unused).
  • Code content preserved verbatim; only the tab wrapper syntax changed (de-indented 4 spaces to sit at column 0 inside <details>).

Verification

  • grep: zero === "Sync"/"Async" remain.
  • Structural check script: all 36 <details> have markdown="1", a blank line after </summary>, and a blank line before </details> (0 problems).
  • mkdocs build --strict: not run (mkdocs not installed locally; per task, no global tooling installed).

Replace pymdownx.tabbed '=== "Sync"/"Async"' content-tabs (render as
literal text + lose highlighting on GitHub) with <details markdown="1">
collapsible blocks in README + 16 docs pages. Add md_in_html extension so
fenced code inside <details> highlights on the MkDocs site.
@martinkersner martinkersner self-assigned this Jul 4, 2026
@martinkersner martinkersner merged commit 72981fd into main Jul 4, 2026
5 checks passed
@martinkersner martinkersner deleted the issue-166-sync-async-readme-details branch July 4, 2026 13:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Sync/Async usage examples to README with collapsible <details> blocks

1 participant