docs: Support GFM style admonitions in option descriptions

docs/0001-nixos-render-docs-Output-GFM-admonition.patch

@@ -1,7 +1,7 @@
-From 4545eca44e0865f4ccab518d8e1591f714cb333c Mon Sep 17 00:00:00 2001
+From a6565b5e6c967ca90a3bbf00515bdffd6f8ffb27 Mon Sep 17 00:00:00 2001
 From: Matt Sturgeon <matt@sturgeon.me.uk>
 Date: Tue, 10 Sep 2024 15:37:56 +0100
-Subject: [PATCH] Output GFM admonition
+Subject: [PATCH 1/2] nixos-render-docs: Output GFM admonition
 
 ---
  nixos_render_docs/commonmark.py | 5 +++--

docs/0002-nixos-render-docs-Support-gfm-style-admonitions.patch

@@ -0,0 +1,112 @@
+From cf462a681089ead8ac747b24116c78db0cc1df40 Mon Sep 17 00:00:00 2001
+From: Quentin Boyer <quentin+dev@familleboyer.net>
+Date: Wed, 11 Sep 2024 19:21:12 +0200
+Subject: [PATCH 2/2] nixos-render-docs: Support gfm-style admonitions
+
+---
+ nixos_render_docs/md.py  | 2 ++
+ tests/sample_md.py       | 3 +++
+ tests/test_asciidoc.py   | 6 ++++++
+ tests/test_commonmark.py | 3 +++
+ tests/test_html.py       | 4 ++++
+ tests/test_manpage.py    | 6 ++++++
+ 6 files changed, 24 insertions(+)
+
+diff --git a/nixos_render_docs/md.py b/nixos_render_docs/md.py
+index 894daf9ca9c7..e0aca42ebd14 100644
+--- a/nixos_render_docs/md.py
++++ b/nixos_render_docs/md.py
+@@ -14,6 +14,7 @@ from mdit_py_plugins.container import container_plugin # type: ignore[attr-defin
+ from mdit_py_plugins.deflist import deflist_plugin # type: ignore[attr-defined]
+ from mdit_py_plugins.footnote import footnote_plugin # type: ignore[attr-defined]
+ from mdit_py_plugins.myst_role import myst_role_plugin # type: ignore[attr-defined]
++from gfm_alerts_to_admonitions import gfm_alert_to_admonition
+ 
+ _md_escape_table = {
+     ord('*'): '\\*',
+@@ -588,6 +589,7 @@ class Converter(ABC, Generic[TR]):
+             renderer_cls=self.ForbiddenRenderer
+         )
+         self._md.enable('table')
++        self._md.use(gfm_alert_to_admonition)
+         self._md.use(
+             container_plugin,
+             name="blockattr",
+diff --git a/tests/sample_md.py b/tests/sample_md.py
+index 73a64fde8364..1648c4d9453e 100644
+--- a/tests/sample_md.py
++++ b/tests/sample_md.py
+@@ -1,4 +1,7 @@
+ sample1 = """\
++> [!NOTE]
++> This is a *note*
++
+ :::: {.warning}
+ foo
+ ::: {.note}
+diff --git a/tests/test_asciidoc.py b/tests/test_asciidoc.py
+index 3cf5b208f392..c9b39f4e47f9 100644
+--- a/tests/test_asciidoc.py
++++ b/tests/test_asciidoc.py
+@@ -45,6 +45,12 @@ f
+ def test_full() -> None:
+     c = Converter({ 'man(1)': 'http://example.org' })
+     assert c._render(sample1) == """\
++[NOTE]
++====
++This is a __note__
++====
++
++
+ [WARNING]
+ ====
+ foo
+diff --git a/tests/test_commonmark.py b/tests/test_commonmark.py
+index e151325338ca..ca137ce8cc48 100644
+--- a/tests/test_commonmark.py
++++ b/tests/test_commonmark.py
+@@ -27,6 +27,9 @@ def test_indented_fence() -> None:
+ def test_full() -> None:
+     c = Converter({ 'man(1)': 'http://example.org' })
+     assert c._render(sample1) == """\
++> [!Note]
++> This is a *note*
++
+ > [!Warning]
+ > foo
+ > 
+diff --git a/tests/test_html.py b/tests/test_html.py
+index 9a3e07cb24c7..b51bc47ec557 100644
+--- a/tests/test_html.py
++++ b/tests/test_html.py
+@@ -149,6 +149,10 @@ def test_footnotes() -> None:
+ def test_full() -> None:
+     c = Converter({ 'man(1)': 'http://example.org' }, {})
+     assert c._render(sample1) == unpretty("""
++        <div class="note">
++          <h3 class="title">Note</h3>
++          <p>This is a <span class="emphasis"><em>note</em></span></p>
++        </div>
+         <div class="warning">
+          <h3 class="title">Warning</h3>
+          <p>foo</p>
+diff --git a/tests/test_manpage.py b/tests/test_manpage.py
+index b6e4a94ef1c6..1943bb17f339 100644
+--- a/tests/test_manpage.py
++++ b/tests/test_manpage.py
+@@ -41,6 +41,12 @@ def test_full() -> None:
+     assert c._render(sample1) == """\
+ .sp
+ .RS 4
++\\fBNote\\fP
++.br
++This is a \\fInote\\fR
++.RE
++.sp
++.RS 4
+ \\fBWarning\\fP
+ .br
+ foo
+-- 
+2.46.0
+

docs/default.nix

@@ -54,6 +54,7 @@ let
 in
 {
   inherit options-json;
+  inherit (pkgs) nixos-render-docs;
 
   gfm-alerts-to-admonitions = pkgs.python3.pkgs.callPackage ./gfm-alerts-to-admonitions { };
 

docs/pkgs.nix

@@ -28,11 +28,18 @@ let
     lib = prev.lib.extend libOverlay;
 
     nixos-render-docs = prev.nixos-render-docs.overrideAttrs (old: {
+      propagatedBuildInputs = old.propagatedBuildInputs ++ [
+        (final.python3.pkgs.callPackage ./gfm-alerts-to-admonitions {
+          # Use the same override as `nixos-render-docs` does, to avoid "duplicate dependency" errors
+          markdown-it-py = final.python3.pkgs.markdown-it-py.overridePythonAttrs { doCheck = false; };
+        })
+      ];
+
       patches = old.patches or [ ] ++ [
         # Adds support for GFM-style admonitions in rendered commonmark
-        ./0001-Output-GFM-admonition.patch
+        ./0001-nixos-render-docs-Output-GFM-admonition.patch
-        # TODO:add support for _parsing_ GFM admonitions too
+        # Adds support for parsing GFM-style admonitions
-        # https://github.com/nix-community/nixvim/issues/2217
+        ./0002-nixos-render-docs-Support-gfm-style-admonitions.patch
       ];
     });
   };

typos.toml

@@ -10,3 +10,7 @@ Highligt = "Highligt"     # TODO: ./plugins/utils/neogen.nix
 Annote = "Annote"         # TODO: ./plugins/lsp/fidget.nix
 ket = "ket"               # ./plugins/utils/sandwich.nix
 tro = "tro"               # ./plugins/utils/spectre.nix
+
+[type.patch]
+extend-glob = ["*.patch"]
+check-file = false