➕ 📝 add more handy markdown extensions

Author: jorenham

mkdocs.yml

@@ -44,24 +44,33 @@ plugins:
             show_source: false
             show_signature_annotations: true
 
-  # https://squidfunk.github.io/mkdocs-material/plugins/search/
-  - search
-
   # https://squidfunk.github.io/mkdocs-material/plugins/privacy/
   - privacy:
       enabled: !ENV [CI, false]
 
+  # https://squidfunk.github.io/mkdocs-material/plugins/search/
+  - search
+
 markdown_extensions:
   # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/
   - abbr
-  - admonition
   - attr_list
   - def_list
   - footnotes
   - md_in_html
   - toc:
       permalink: "🔗"
 
+  # https://github.com/oprypin/markdown-callouts
+  - callouts
+
+  # https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+  - pymdownx.betterem:
+      smart_enable: asterisk
+
+  - pymdownx.blocks.tab:
+      alternate_style: true
+
   # https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
@@ -82,6 +91,24 @@ markdown_extensions:
       user: numpy
       repo: numtype
 
+  # https://facelessuser.github.io/pymdown-extensions/extensions/saneheaders/
+  - pymdownx.saneheaders
+
+extra:
+  analytics:
+    provider: google
+    property: G-JYJJ7JYLG1
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+
+extra_css:
+  - style/theme.css
+
 theme:
   name: material
   favicon: img/favicon.ico
@@ -126,19 +153,4 @@ theme:
         icon: fontawesome/regular/sun
         name: Switch to system preference
 
-extra_css:
-  - style/theme.css
-
-extra:
-  analytics:
-    provider: google
-    property: G-JYJJ7JYLG1
-  consent:
-    title: Cookie consent
-    description: >-
-      We use cookies to recognize your repeated visits and preferences, as well
-      as to measure the effectiveness of our documentation and whether users
-      find what they're searching for. With your consent, you're helping us to
-      make our documentation better.
-
 copyright: Copyright ©, 2025 NumPy Developers.

pyproject.toml

@@ -81,6 +81,7 @@ typecheck = [
 docs = [
     "mkdocs-material>=9.6.10",
     "mkdocs-awesome-nav>=3.1.0",
+    "markdown-callouts>=0.4.0",
     "mkdocs-include-markdown-plugin>=7.1.5",
     "mkdocs-minify-plugin>=0.8.0",
     "mkdocstrings[python]>=0.29.1",