From bed938b520cc8cbcc5b3e9bece52f59b9bfbfcb2 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Mon, 18 May 2026 07:14:40 -0400 Subject: [PATCH 1/2] add extensions tab, improve visibility Signed-off-by: alexvoss --- docs/setup/extensions/glightbox.md | 1 + docs/setup/extensions/index.md | 47 +++++++++++++++++++--------- docs/setup/extensions/macros.md | 1 + mkdocs.yml | 50 ++++++++++++++++-------------- 4 files changed, 60 insertions(+), 39 deletions(-) diff --git a/docs/setup/extensions/glightbox.md b/docs/setup/extensions/glightbox.md index 47adf98..a1fcecf 100644 --- a/docs/setup/extensions/glightbox.md +++ b/docs/setup/extensions/glightbox.md @@ -2,6 +2,7 @@ icon: lucide/box tags: - Extensions +status: new --- # GLightbox diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/index.md index 4aeacec..b64b82d 100644 --- a/docs/setup/extensions/index.md +++ b/docs/setup/extensions/index.md @@ -4,25 +4,44 @@ title: Extensions # 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. - +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. This is where Markdown extensions come in that +extend the Markdown syntax beyond the basics. !!! 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. + +## 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) + +## Python Markdown Extensions - [John Gruber's Markdown]: https://daringfireball.net/projects/markdown/ +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 +90,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 +200,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: diff --git a/docs/setup/extensions/macros.md b/docs/setup/extensions/macros.md index ccd4715..89707c1 100644 --- a/docs/setup/extensions/macros.md +++ b/docs/setup/extensions/macros.md @@ -2,6 +2,7 @@ icon: lucide/braces tags: - Extensions +status: new --- # Macros diff --git a/mkdocs.yml b/mkdocs.yml index 234dcbc..c4ddd84 100755 --- a/mkdocs.yml +++ b/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: + - setup/extensions/index.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 From 25e157915d1193e4ce2048dd23cfd0f9739ebbc1 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 19 May 2026 16:47:02 -0400 Subject: [PATCH 2/2] add extensions page to sidebar nav; mention Python Markdown before CommonMark Signed-off-by: alexvoss --- docs/setup/extensions/{index.md => about.md} | 15 ++++++++++----- docs/setup/extensions/python-markdown.md | 2 +- mkdocs.yml | 2 +- 3 files changed, 12 insertions(+), 7 deletions(-) rename docs/setup/extensions/{index.md => about.md} (92%) diff --git a/docs/setup/extensions/index.md b/docs/setup/extensions/about.md similarity index 92% rename from docs/setup/extensions/index.md rename to docs/setup/extensions/about.md index b64b82d..5fe6531 100644 --- a/docs/setup/extensions/index.md +++ b/docs/setup/extensions/about.md @@ -1,22 +1,27 @@ --- title: Extensions +icon: lucide/blocks --- -# Extensions +# 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. This is where Markdown extensions come in that -extend the Markdown syntax beyond the basics. +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 and - components in the future. Of course, we will provide tools to automatically + 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 diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index ac00c4b..3814c65 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index c4ddd84..a0fea44 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -205,7 +205,7 @@ nav: - Comment system: setup/comment-system.md - Offline usage: setup/offline.md - Extensions: - - setup/extensions/index.md + - About extensions: setup/extensions/about.md - GLightbox: setup/extensions/glightbox.md - Macros: setup/extensions/macros.md - mkdocstrings: setup/extensions/mkdocstrings.md