Skip to content

feat: Add AdmonitionExtension for semantic admonition markup#129

Merged
dereuromark merged 2 commits intomasterfrom
feature/admonition-extension
Mar 26, 2026
Merged

feat: Add AdmonitionExtension for semantic admonition markup#129
dereuromark merged 2 commits intomasterfrom
feature/admonition-extension

Conversation

@dereuromark
Copy link
Copy Markdown
Contributor

Summary

Adds a new AdmonitionExtension that transforms divs with admonition type classes into semantic HTML. Inspired by Python-Markdown/Material for MkDocs admonition syntax, but using djot's native fenced div syntax.

Features

  • Recognizes admonition types: note, tip, warning, danger, info, success, caution
  • Adds proper ARIA roles (role="note" or role="alert" for warning types)
  • Auto-generates titles from type name (configurable)
  • Supports custom titles via {title="Custom Title"} attribute
  • Supports collapsible blocks via {collapsible} or {collapsible=open} attributes
  • Fully configurable (types, title tag/class, container class)

Usage

$converter = new DjotConverter();
$converter->addExtension(new AdmonitionExtension());

Input/Output Examples

Basic admonition:

::: note
This is a note.
:::
<div class="admonition note" role="note">
  <p class="admonition-title">Note</p>
  <p>This is a note.</p>
</div>

With custom title:

{title="Watch Out!"}
::: warning
Be careful here.
:::

Collapsible:

{collapsible}
::: tip
Click to expand.
:::
<details class="admonition tip">
  <summary>Tip</summary>
  <p>Click to expand.</p>
</details>

Transforms divs with admonition type classes (note, tip, warning, danger,
info, success, caution) into semantic HTML with:

- Proper ARIA roles (role="note" or role="alert")
- Auto-generated or custom titles
- Collapsible blocks using details/summary
- Configurable container/title classes and tags
@codecov
Copy link
Copy Markdown

codecov Bot commented Mar 26, 2026

Codecov Report

❌ Patch coverage is 95.38462% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.97%. Comparing base (41bdb80) to head (11d2c08).
⚠️ Report is 3 commits behind head on master.

Files with missing lines Patch % Lines
src/Extension/AdmonitionExtension.php 95.38% 3 Missing ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##             master     #129      +/-   ##
============================================
+ Coverage     93.94%   93.97%   +0.02%     
- Complexity     2385     2419      +34     
============================================
  Files            81       83       +2     
  Lines          6310     6403      +93     
============================================
+ Hits           5928     6017      +89     
- Misses          382      386       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Documents the new AdmonitionExtension with examples for:
- Basic admonition syntax
- Custom titles via {title="..."} attribute
- Collapsible admonitions via {collapsible} and {collapsible=open}
- ARIA roles (note vs alert)
- Configuration options table
- Custom types, title tag customization, and disabling auto-titles
@dereuromark dereuromark marked this pull request as ready for review March 26, 2026 16:17
@dereuromark dereuromark merged commit 9d39838 into master Mar 26, 2026
6 checks passed
@dereuromark dereuromark deleted the feature/admonition-extension branch March 26, 2026 16:18
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.

1 participant