add extensions tab, improve visibility

docs/setup/extensions/index.md → docs/setup/extensions/about.md

@@ -1,28 +1,52 @@
 ---
 title: Extensions
+icon: lucide/blocks
 ---
 
-# Extensions
-
-Markdown is a very small language with a kind-of reference implementation called
-[John Gruber's Markdown]. [Python Markdown] and [Python Markdown Extensions]
-are two packages that enhance the Markdown writing experience, adding useful
-syntax extensions for technical writing.
+# About extensions
 
+Markdown is a very small language with an [initial implementation by John
+Gruber][gruber] that has long served as the reference for Markdown
+implementations. Its minimal functionality makes it easy to learn but also
+limits what it can express. Zensical currently uses [Python Markdown],
+which supports additional syntax elements provided by __Markdown extensions__.
+These enrich Python Markdown and make it suitable for technical writing.
 
 !!! info "We'll be moving to CommonMark soon"
 
     Zensical is being actively developed, and we're working towards a more
-    comprehensive module system that will allow us to support CommonMark in
-    the future. Of course, we will provide tools to automatically migrate your
-    existing content when the time comes.
+    comprehensive module system that will allow us to support [CommonMark] and
+    [components] in the future. Of course, we will provide tools to automatically
+    migrate your existing content when the time comes.
+
+[CommonMark]: https://zensical.org/about/roadmap/#compatibility
+[components]: https://zensical.org/about/roadmap/#component-system
+
+## Zensical extensions
+
+Zensical itself provides support for a number of extensions in addition to the
+Python Markdown extensions described below.
+
+* [GLightbox](glightbox.md)
+* [Macros](macros.md)
+* [mkdocstrings](mkdocstrings.md)
 
-  [John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
+## Python Markdown Extensions
+
+Since Zensical currently uses [Python Markdown], its extensions for the original
+Markdown syntax are available. The [Python Markdown Extensions] package is
+also installed with Zensical, adding more extensions.
+
+Most of the extensions are enabled [by default] and are included explicitly in
+the template generated by the `zensical new` command. You can [turn off the
+defaults] if they do not suit your project.
+
+  [gruber]: https://daringfireball.net/projects/markdown/
+  [by default]: #default-configuration
+  [turn off the defaults]: #turning-off-the-defaults
   [Python Markdown]: python-markdown.md
   [Python Markdown Extensions]: python-markdown-extensions.md
 
-## Supported extensions
-
 The following extensions are all supported by Zensical and therefore strongly
 recommended. Click on each extension to learn about its purpose and
 configuration:
@@ -71,9 +95,7 @@ configuration:
   [Tables]: python-markdown.md#tables
   [Tasklist]: python-markdown-extensions.md#tasklist
 
-## Configuration
-
-### Default configuration
+## Default configuration
 
 If your configuration file contains no definitions for the extensions then
 Zensical will use a default configuration that enables the extensions that are
@@ -183,7 +205,7 @@ extensions are enabled by default:
   [preset mechanism]: https://zensical.org/about/roadmap/#configuration
   [new command]: ../../usage/new.md
 
-### Disable the defaults
+## Turning off the defaults
 
 If you want to reset the behavior to the default behavior of MkDocs, create a
 configuration with an empty list of extensions:

docs/setup/extensions/glightbox.md

@@ -2,6 +2,7 @@
 icon: lucide/box
 tags:
   - Extensions
+status: new
 ---
 
 # GLightbox

docs/setup/extensions/macros.md

@@ -2,6 +2,7 @@
 icon: lucide/braces
 tags:
   - Extensions
+status: new
 ---
 
 # Macros

docs/setup/extensions/python-markdown.md

@@ -15,7 +15,7 @@ which features they need to be enabled.
     Zensical has [sensible defaults] for the Markdown extensions settings. Make
     sure to check these out before you begin to configure things manually.
 
-[sensible defaults]: index.md#default-configuration
+[sensible defaults]: about.md#default-configuration
 
 ## Supported extensions
 

mkdocs.yml

@@ -185,30 +185,32 @@ nav:
       - Build: usage/build.md
   - Setup:
       - Basics: setup/basics.md
-      - Colors: setup/colors.md
-      - Fonts: setup/fonts.md
-      - Language: setup/language.md
-      - Logo and icons: setup/logo-and-icons.md
-      - Data privacy: setup/data-privacy.md
-      - Navigation: setup/navigation.md
-      - Validation: setup/validation.md
-      - Site search: setup/search.md
-      - Site analytics: setup/analytics.md
-      - Social cards: setup/social-cards.md
-      - Tags: setup/tags.md
-      - Header: setup/header.md
-      - Footer: setup/footer.md
-      - Repository: setup/repository.md
-      - Versioning: setup/versioning.md
-      - Comment system: setup/comment-system.md
-      - Offline usage: setup/offline.md
-      - Extensions:
-          - setup/extensions/index.md
-          - Markdown: setup/extensions/python-markdown.md
-          - Markdown Extensions: setup/extensions/python-markdown-extensions.md
-          - GLightbox: setup/extensions/glightbox.md
-          - Macros: setup/extensions/macros.md
-          - mkdocstrings: setup/extensions/mkdocstrings.md
+      - Theme:
+          - Colors: setup/colors.md
+          - Fonts: setup/fonts.md
+          - Language: setup/language.md
+          - Logo and icons: setup/logo-and-icons.md
+          - Header: setup/header.md
+          - Footer: setup/footer.md
+          - Repository: setup/repository.md
+      - Site settings:
+          - Data privacy: setup/data-privacy.md
+          - Navigation: setup/navigation.md
+          - Validation: setup/validation.md
+          - Site search: setup/search.md
+          - Site analytics: setup/analytics.md
+          - Social cards: setup/social-cards.md
+          - Tags: setup/tags.md
+          - Versioning: setup/versioning.md
+          - Comment system: setup/comment-system.md
+          - Offline usage: setup/offline.md
+  - Extensions:
+      - About extensions: setup/extensions/about.md
+      - GLightbox: setup/extensions/glightbox.md
+      - Macros: setup/extensions/macros.md
+      - mkdocstrings: setup/extensions/mkdocstrings.md
+      - Python Markdown: setup/extensions/python-markdown.md
+      - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
   - Authoring:
       - Markdown: authoring/markdown.md
       - Front matter: authoring/frontmatter.md