From 276cf48659b2057ef1c936afe7c2095eea7e99a3 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 7 Jul 2026 09:50:13 -0400 Subject: [PATCH 1/3] docs: use TOML 1.1 inline tables to simplify repeated pymdownx snippets Several TOML snippets used a separate [project.markdown_extensions...] table header for each sibling extension, mirroring a YAML conversion rather than idiomatic TOML. Collapse these into a single parent table with inline table values, taking advantage of TOML 1.1's newlines in inline tables for the larger multi-key cases. Closes #104 --- docs/authoring/admonitions.md | 7 +- docs/authoring/code-blocks.md | 16 +++-- docs/authoring/content-tabs.md | 6 +- docs/authoring/formatting.md | 9 +-- docs/authoring/grids.md | 5 +- docs/authoring/icons-emojis.md | 5 +- docs/authoring/images.md | 7 +- docs/authoring/lists.md | 6 +- docs/authoring/tooltips.md | 7 +- docs/setup/extensions/about.md | 72 +++++++++---------- docs/setup/extensions/mkdocstrings.md | 10 +-- .../extensions/python-markdown-extensions.md | 18 ++--- 12 files changed, 89 insertions(+), 79 deletions(-) diff --git a/docs/authoring/admonitions.md b/docs/authoring/admonitions.md index 3dac3ff..5db8529 100644 --- a/docs/authoring/admonitions.md +++ b/docs/authoring/admonitions.md @@ -19,9 +19,10 @@ configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.admonition] - [project.markdown_extensions.pymdownx.details] - [project.markdown_extensions.pymdownx.superfences] + [project.markdown_extensions] + admonition = {} + pymdownx.details = {} + pymdownx.superfences = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/code-blocks.md b/docs/authoring/code-blocks.md index a50898e..0389982 100644 --- a/docs/authoring/code-blocks.md +++ b/docs/authoring/code-blocks.md @@ -22,13 +22,15 @@ following lines to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - anchor_linenums = true - line_spans = "__span" - pygments_lang_class = true - [project.markdown_extensions.pymdownx.inlinehilite] - [project.markdown_extensions.pymdownx.snippets] - [project.markdown_extensions.pymdownx.superfences] + [project.markdown_extensions.pymdownx] + highlight = { + anchor_linenums = true, + line_spans = "__span", + pygments_lang_class = true, + } + inlinehilite = {} + snippets = {} + superfences = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/content-tabs.md b/docs/authoring/content-tabs.md index d8a0065..e76f431 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -21,9 +21,9 @@ following lines to your configuration file: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.superfences] - [project.markdown_extensions.pymdownx.tabbed] - alternate_style = true + [project.markdown_extensions.pymdownx] + superfences = {} + tabbed = { alternate_style = true } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/formatting.md b/docs/authoring/formatting.md index c259b12..018d1c3 100644 --- a/docs/authoring/formatting.md +++ b/docs/authoring/formatting.md @@ -18,10 +18,11 @@ configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.caret] - [project.markdown_extensions.pymdownx.keys] - [project.markdown_extensions.pymdownx.mark] - [project.markdown_extensions.pymdownx.tilde] + [project.markdown_extensions.pymdownx] + caret = {} + keys = {} + mark = {} + tilde = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/grids.md b/docs/authoring/grids.md index d67200d..7889660 100644 --- a/docs/authoring/grids.md +++ b/docs/authoring/grids.md @@ -19,8 +19,9 @@ to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.attr_list] - [project.markdown_extensions.md_in_html] + [project.markdown_extensions] + attr_list = {} + md_in_html = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/icons-emojis.md b/docs/authoring/icons-emojis.md index bcf5718..765ee81 100644 --- a/docs/authoring/icons-emojis.md +++ b/docs/authoring/icons-emojis.md @@ -21,8 +21,9 @@ shortcodes. Add the following lines to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.attr_list] - [project.markdown_extensions.pymdownx.emoji] + [project.markdown_extensions] + attr_list = {} + pymdownx.emoji = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/images.md b/docs/authoring/images.md index 5320337..b219412 100644 --- a/docs/authoring/images.md +++ b/docs/authoring/images.md @@ -19,9 +19,10 @@ following lines to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.attr_list] - [project.markdown_extensions.md_in_html] - [project.markdown_extensions.pymdownx.blocks.caption] + [project.markdown_extensions] + attr_list = {} + md_in_html = {} + pymdownx.blocks.caption = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/lists.md b/docs/authoring/lists.md index 93c334c..81478ac 100644 --- a/docs/authoring/lists.md +++ b/docs/authoring/lists.md @@ -21,9 +21,9 @@ your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.def_list] - [project.markdown_extensions.pymdownx.tasklist] - custom_checkbox = true + [project.markdown_extensions] + def_list = {} + pymdownx.tasklist = { custom_checkbox = true } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/tooltips.md b/docs/authoring/tooltips.md index 2402f06..c624374 100644 --- a/docs/authoring/tooltips.md +++ b/docs/authoring/tooltips.md @@ -21,9 +21,10 @@ following line to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.abbr] - [project.markdown_extensions.attr_list] - [project.markdown_extensions.pymdownx.snippets] + [project.markdown_extensions] + abbr = {} + attr_list = {} + pymdownx.snippets = {} ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/about.md b/docs/setup/extensions/about.md index 5fe6531..07d74b0 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -111,42 +111,42 @@ extensions are enabled by default: === "`zensical.toml`" ``` toml - [project.markdown_extensions.abbr] - [project.markdown_extensions.admonition] - [project.markdown_extensions.attr_list] - [project.markdown_extensions.def_list] - [project.markdown_extensions.footnotes] - [project.markdown_extensions.md_in_html] - [project.markdown_extensions.toc] - permalink = true - [project.markdown_extensions.pymdownx.arithmatex] - generic = true - [project.markdown_extensions.pymdownx.betterem] - [project.markdown_extensions.pymdownx.caret] - [project.markdown_extensions.pymdownx.details] - [project.markdown_extensions.pymdownx.emoji] - emoji_generator = "zensical.extensions.emoji.to_svg" - emoji_index = "zensical.extensions.emoji.twemoji" - [project.markdown_extensions.pymdownx.highlight] - anchor_linenums = true - line_spans = "__span" - pygments_lang_class = true - [project.markdown_extensions.pymdownx.inlinehilite] - [project.markdown_extensions.pymdownx.keys] - [project.markdown_extensions.pymdownx.magiclink] - [project.markdown_extensions.pymdownx.mark] - [project.markdown_extensions.pymdownx.smartsymbols] - [project.markdown_extensions.pymdownx.superfences] - custom_fences = [ - { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" } - ] - [project.markdown_extensions.pymdownx.tabbed] - alternate_style = true - combine_header_slug = true - [project.markdown_extensions.pymdownx.tasklist] - custom_checkbox = true - [project.markdown_extensions.pymdownx.tilde] - + [project.markdown_extensions] + abbr = {} + admonition = {} + attr_list = {} + def_list = {} + footnotes = {} + md_in_html = {} + toc = { permalink = true } + + [project.markdown_extensions.pymdownx] + arithmatex = { generic = true } + betterem = {} + caret = {} + details = {} + emoji = { + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + } + highlight = { + anchor_linenums = true, + line_spans = "__span", + pygments_lang_class = true, + } + inlinehilite = {} + keys = {} + magiclink = {} + mark = {} + smartsymbols = {} + superfences = { + custom_fences = [ + { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }, + ], + } + tabbed = { alternate_style = true, combine_header_slug = true } + tasklist = { custom_checkbox = true } + tilde = {} ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/mkdocstrings.md b/docs/setup/extensions/mkdocstrings.md index e4fc968..c8d95ab 100644 --- a/docs/setup/extensions/mkdocstrings.md +++ b/docs/setup/extensions/mkdocstrings.md @@ -46,11 +46,11 @@ Configure mkdocstrings as a plugin: [project.plugins.mkdocstrings.handlers.python] inventories = ["https://docs.python.org/3/objects.inv"] paths = ["src"] - - [project.plugins.mkdocstrings.handlers.python.options] - docstring_style = "google" - inherited_members = true - show_source = false + options = { + docstring_style = "google", + inherited_members = true, + show_source = false, + } ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 53a7a91..97ffb19 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -146,9 +146,10 @@ via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.caret] - [project.markdown_extensions.pymdownx.mark] - [project.markdown_extensions.pymdownx.tilde] + [project.markdown_extensions.pymdownx] + caret = {} + mark = {} + tilde = {} ``` === "`mkdocs.yml`" @@ -326,9 +327,9 @@ The [Highlight] extension adds support for syntax highlighting of code blocks === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - anchor_linenums = true - [project.markdown_extensions.pymdownx.superfences] + [project.markdown_extensions.pymdownx] + highlight = { anchor_linenums = true } + superfences = {} ``` 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to @@ -513,8 +514,9 @@ which it sources its configuration. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - [project.markdown_extensions.pymdownx.inlinehilite] + [project.markdown_extensions.pymdownx] + highlight = {} + inlinehilite = {} ``` === "`mkdocs.yml`" From 368e476b7c3cb5a89e45e16e86f75357a5eb10b0 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 7 Jul 2026 13:09:06 -0400 Subject: [PATCH 2/3] docs: apply TOML 1.1 inline tables to remaining markdown_extensions snippets --- docs/authoring/buttons.md | 3 +- docs/authoring/content-tabs.md | 8 +- docs/authoring/data-tables.md | 3 +- docs/authoring/diagrams.md | 14 +- docs/authoring/footnotes.md | 3 +- docs/authoring/math.md | 9 +- docs/authoring/tooltips.md | 4 +- docs/setup/extensions/about.md | 6 +- docs/setup/extensions/glightbox.md | 31 ++--- docs/setup/extensions/macros.md | 63 ++++----- .../extensions/python-markdown-extensions.md | 122 ++++++++++-------- docs/setup/extensions/python-markdown.md | 53 ++++---- docs/setup/logo-and-icons.md | 10 +- docs/setup/navigation.md | 28 ++-- 14 files changed, 204 insertions(+), 153 deletions(-) diff --git a/docs/authoring/buttons.md b/docs/authoring/buttons.md index ff20fb9..a7e1d1d 100644 --- a/docs/authoring/buttons.md +++ b/docs/authoring/buttons.md @@ -19,7 +19,8 @@ following lines to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.attr_list] + [project.markdown_extensions] + attr_list = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/content-tabs.md b/docs/authoring/content-tabs.md index e76f431..a01475a 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -69,9 +69,11 @@ function with the following lines: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed.slugify] - object = "pymdownx.slugs.slugify" - kwds = { case = "lower" } + [project.markdown_extensions.pymdownx] + tabbed.slugify = { + object = "pymdownx.slugs.slugify", + kwds = { case = "lower" }, + } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/data-tables.md b/docs/authoring/data-tables.md index 1cc0d2f..bbaed6e 100644 --- a/docs/authoring/data-tables.md +++ b/docs/authoring/data-tables.md @@ -23,7 +23,8 @@ configuration file: === "`zensical.toml`" ``` toml - [project.markdown_extensions.tables] + [project.markdown_extensions] + tables = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/diagrams.md b/docs/authoring/diagrams.md index 8acbbf5..d3e2f74 100644 --- a/docs/authoring/diagrams.md +++ b/docs/authoring/diagrams.md @@ -23,10 +23,16 @@ will automatically initialize the JavaScript runtime when a page includes a === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.superfences] - custom_fences = [ - { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" } - ] + [project.markdown_extensions.pymdownx] + superfences = { + custom_fences = [ + { + name = "mermaid", + class = "mermaid", + format = "pymdownx.superfences.fence_code_format", + }, + ], + } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/footnotes.md b/docs/authoring/footnotes.md index b567ecc..0424cb3 100644 --- a/docs/authoring/footnotes.md +++ b/docs/authoring/footnotes.md @@ -19,7 +19,8 @@ your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.footnotes] + [project.markdown_extensions] + footnotes = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/math.md b/docs/authoring/math.md index b3d74d0..4f35dff 100644 --- a/docs/authoring/math.md +++ b/docs/authoring/math.md @@ -67,8 +67,9 @@ to your configuration: "javascripts/mathjax.js", "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js" ] - [project.markdown_extensions.pymdownx.arithmatex] - generic = true + + [project.markdown_extensions.pymdownx] + arithmatex = { generic = true } ``` === "`mkdocs.yml`" @@ -143,8 +144,8 @@ supports a subset of LaTeX syntax and can render math to HTML and SVG. To use "https://unpkg.com/katex@0/dist/katex.min.css" ] - [project.markdown_extensions.pymdownx.arithmatex] - generic = true + [project.markdown_extensions.pymdownx] + arithmatex = { generic = true } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/tooltips.md b/docs/authoring/tooltips.md index c624374..43515d9 100644 --- a/docs/authoring/tooltips.md +++ b/docs/authoring/tooltips.md @@ -169,8 +169,8 @@ pages with the following configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.snippets] - auto_append = ["includes/abbreviations.md"] + [project.markdown_extensions.pymdownx] + snippets = { auto_append = ["includes/abbreviations.md"] } ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/about.md b/docs/setup/extensions/about.md index 07d74b0..6645e22 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -141,7 +141,11 @@ extensions are enabled by default: smartsymbols = {} superfences = { custom_fences = [ - { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }, + { + name = "mermaid", + class = "mermaid", + format = "pymdownx.superfences.fence_code_format", + }, ], } tabbed = { alternate_style = true, combine_header_slug = true } diff --git a/docs/setup/extensions/glightbox.md b/docs/setup/extensions/glightbox.md index a1fcecf..afe1d79 100644 --- a/docs/setup/extensions/glightbox.md +++ b/docs/setup/extensions/glightbox.md @@ -12,7 +12,8 @@ The GLightbox extension, included with Zensical, enables image zoom through ligh === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] + [project.markdown_extensions.zensical.extensions] + glightbox = {} ``` === "`mkdocs.yml`" @@ -31,8 +32,8 @@ When `true`, images are wrapped automatically, unless they have the `off-glb` CS === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - auto = false + [project.markdown_extensions.zensical.extensions] + glightbox = { auto = false } ``` === "`mkdocs.yml`" @@ -50,8 +51,8 @@ When set to `true`, images for light and dark modes are grouped into separate ga === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - auto_themed = true + [project.markdown_extensions.zensical.extensions] + glightbox = { auto_themed = true } ``` === "`mkdocs.yml`" @@ -69,8 +70,8 @@ Width of the lightbox overlay (default: `auto`). Accepts CSS units (`px`, `%`, ` === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - width = "800px" + [project.markdown_extensions.zensical.extensions] + glightbox = { width = "800px" } ``` === "`mkdocs.yml`" @@ -89,8 +90,8 @@ Height of the lightbox overlay (default: `auto`). Accepts CSS units (`px`, `%`, === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - height = "600px" + [project.markdown_extensions.zensical.extensions] + glightbox = { height = "600px" } ``` === "`mkdocs.yml`" @@ -108,8 +109,8 @@ List of image CSS classes to exclude from automatic wrapping. The default value === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - skip_classes = ["extra-class-to-exclude"] + [project.markdown_extensions.zensical.extensions] + glightbox = { skip_classes = ["extra-class-to-exclude"] } ``` === "`mkdocs.yml`" @@ -128,8 +129,8 @@ When set to `true`, the image `alt` attribute is used as a caption when no expli === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - auto_caption = true + [project.markdown_extensions.zensical.extensions] + glightbox = { auto_caption = true } ``` === "`mkdocs.yml`" @@ -147,8 +148,8 @@ Default caption position for images (default: `bottom`). Valid values: `bottom`, === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.glightbox] - caption_position = "right" + [project.markdown_extensions.zensical.extensions] + glightbox = { caption_position = "right" } ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/macros.md b/docs/setup/extensions/macros.md index 89707c1..f2766a3 100644 --- a/docs/setup/extensions/macros.md +++ b/docs/setup/extensions/macros.md @@ -12,7 +12,8 @@ The Macros extension, included with Zensical, enables [Jinja2] templating in Mar === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] + [project.markdown_extensions.zensical.extensions] + macros = {} ``` === "`mkdocs.yml`" @@ -39,8 +40,8 @@ Name of a Python module to load for defining variables, macros, and filters (def === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - module_name = "macros" + [project.markdown_extensions.zensical.extensions] + macros = { module_name = "macros" } ``` === "`mkdocs.yml`" @@ -58,8 +59,8 @@ List of additional importable module names (pluglets) to load on top of [`module === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - modules = ["my_package.macros"] + [project.markdown_extensions.zensical.extensions] + macros = { modules = ["my_package.macros"] } ``` === "`mkdocs.yml`" @@ -78,15 +79,15 @@ YAML files whose contents are merged into the template variables. A list of file === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - include_yaml = ["data/variables.yml"] + [project.markdown_extensions.zensical.extensions] + macros = { include_yaml = ["data/variables.yml"] } ``` To assign file contents to a named variable: ``` toml - [project.markdown_extensions.zensical.extensions.macros.include_yaml] - team = "data/team.yml" + [project.markdown_extensions.zensical.extensions] + macros = { include_yaml = { team = "data/team.yml" } } ``` === "`mkdocs.yml`" @@ -114,8 +115,8 @@ Directory used as a Jinja2 template loader, enabling `{% include %}` tags in pag === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - include_dir = "includes" + [project.markdown_extensions.zensical.extensions] + macros = { include_dir = "includes" } ``` === "`mkdocs.yml`" @@ -133,8 +134,8 @@ When `true`, all pages are rendered as Jinja2 templates. When `false`, only page === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - render_by_default = false + [project.markdown_extensions.zensical.extensions] + macros = { render_by_default = false } ``` === "`mkdocs.yml`" @@ -152,8 +153,8 @@ When `true`, render errors cause the build to fail. When `false`, pages that fai === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - on_error_fail = true + [project.markdown_extensions.zensical.extensions] + macros = { on_error_fail = true } ``` === "`mkdocs.yml`" @@ -171,8 +172,8 @@ How undefined template variables are handled. When set to `"keep"`, undefined ex === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - on_undefined = "strict" + [project.markdown_extensions.zensical.extensions] + macros = { on_undefined = "strict" } ``` === "`mkdocs.yml`" @@ -190,8 +191,8 @@ Opening delimiter for Jinja2 block tags (default: `{%`). === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_block_start_string = "<%" + [project.markdown_extensions.zensical.extensions] + macros = { j2_block_start_string = "<%" } ``` === "`mkdocs.yml`" @@ -209,8 +210,8 @@ Closing delimiter for Jinja2 block tags (default: `%}`). === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_block_end_string = "%>" + [project.markdown_extensions.zensical.extensions] + macros = { j2_block_end_string = "%>" } ``` === "`mkdocs.yml`" @@ -228,8 +229,8 @@ Opening delimiter for Jinja2 variable expressions (default: `{{`). === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_variable_start_string = "<<" + [project.markdown_extensions.zensical.extensions] + macros = { j2_variable_start_string = "<<" } ``` === "`mkdocs.yml`" @@ -247,8 +248,8 @@ Closing delimiter for Jinja2 variable expressions (default: `}}`). === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_variable_end_string = ">>" + [project.markdown_extensions.zensical.extensions] + macros = { j2_variable_end_string = ">>" } ``` === "`mkdocs.yml`" @@ -266,8 +267,8 @@ Opening delimiter for Jinja2 comments (default: `{#`). === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_comment_start_string = "<#" + [project.markdown_extensions.zensical.extensions] + macros = { j2_comment_start_string = "<#" } ``` === "`mkdocs.yml`" @@ -285,8 +286,8 @@ Closing delimiter for Jinja2 comments (default: `#}`). === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_comment_end_string = "#>" + [project.markdown_extensions.zensical.extensions] + macros = { j2_comment_end_string = "#>" } ``` === "`mkdocs.yml`" @@ -304,8 +305,8 @@ List of [Jinja2 extensions] to be loaded into the template environment. The defa === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.macros] - j2_extensions = ["jinja2.ext.do"] + [project.markdown_extensions.zensical.extensions] + macros = { j2_extensions = ["jinja2.ext.do"] } ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 97ffb19..b0782f7 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -30,8 +30,8 @@ mathematical typesetting. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.arithmatex] - generic = true + [project.markdown_extensions.pymdownx] + arithmatex = { generic = true } ``` === "`mkdocs.yml`" @@ -121,7 +121,8 @@ including images, tables, and code blocks. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.blocks.caption] + [project.markdown_extensions.pymdownx.blocks] + caption = {} ``` === "`mkdocs.yml`" @@ -185,7 +186,8 @@ user. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.details] + [project.markdown_extensions.pymdownx] + details = {} ``` === "`mkdocs.yml`" @@ -211,9 +213,11 @@ in `*.svg` file format into the resulting HTML page. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.emoji] - emoji_index = "zensical.extensions.emoji.twemoji" # (1)! - emoji_generator = "zensical.extensions.emoji.to_svg" + [project.markdown_extensions.pymdownx] + emoji = { + emoji_index = "zensical.extensions.emoji.twemoji", # (1)! + emoji_generator = "zensical.extensions.emoji.to_svg", + } ``` 1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to @@ -242,8 +246,8 @@ recommended due to [restrictions in licensing][Emoji index]: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.emoji] - emoji_index = "zensical.extensions.emoji.twemoji" + [project.markdown_extensions.pymdownx] + emoji = { emoji_index = "zensical.extensions.emoji.twemoji" } ``` === "`mkdocs.yml`" @@ -262,8 +266,8 @@ that icons can only be used together with the `to_svg` configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.emoji] - emoji_generator = "zensical.extensions.emoji.to_svg" + [project.markdown_extensions.pymdownx] + emoji = { emoji_generator = "zensical.extensions.emoji.to_svg" } ``` === "`mkdocs.yml`" @@ -283,10 +287,12 @@ Markdown or the configuration, which is explained in more detail in the === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.emoji] - emoji_index = "zensical.extensions.emoji.twemoji" - emoji_generator = "zensical.extensions.emoji.to_svg" - options.custom_icons = ["overrides/.icons"] + [project.markdown_extensions.pymdownx] + emoji = { + emoji_index = "zensical.extensions.emoji.twemoji", + emoji_generator = "zensical.extensions.emoji.to_svg", + options.custom_icons = ["overrides/.icons"], + } ``` === "`mkdocs.yml`" @@ -360,8 +366,8 @@ function. Enable via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - pygments_lang_class = true + [project.markdown_extensions.pymdownx] + highlight = { pygments_lang_class = true } ``` === "`mkdocs.yml`" @@ -380,8 +386,8 @@ the name of the language being used, e.g. `Python` is printed for a `py` block: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - auto_title = true + [project.markdown_extensions.pymdownx] + highlight = { auto_title = true } ``` === "`mkdocs.yml`" @@ -402,8 +408,8 @@ which also contains some tips on working with line numbers: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - linenums = true + [project.markdown_extensions.pymdownx] + highlight = { linenums = true } ``` === "`mkdocs.yml`" @@ -424,8 +430,8 @@ line itself: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - linenums_style = "pymdownx-inline" + [project.markdown_extensions.pymdownx] + highlight = { linenums_style = "pymdownx-inline" } ``` === "`mkdocs.yml`" @@ -450,8 +456,8 @@ with anchor links, so they can be hyperlinked and shared more easily: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - anchor_linenums = true + [project.markdown_extensions.pymdownx] + highlight = { anchor_linenums = true } ``` === "`mkdocs.yml`" @@ -470,8 +476,8 @@ which is essential for features like line highlighting to work correctly: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.highlight] - line_spans = "__span" + [project.markdown_extensions.pymdownx] + highlight = { line_spans = "__span" } ``` === "`mkdocs.yml`" @@ -549,7 +555,8 @@ keys and combinations, e.g. ++ctrl+alt+del++. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.keys] + [project.markdown_extensions.pymdownx] + keys = {} ``` === "`mkdocs.yml`" @@ -580,7 +587,8 @@ corresponding symbols, e.g. copyright symbols or fractions. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.smartsymbols] + [project.markdown_extensions.pymdownx] + smartsymbols = {} ``` === "`mkdocs.yml`" @@ -605,7 +613,8 @@ syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.snippets] + [project.markdown_extensions.pymdownx] + snippets = {} ``` === "`mkdocs.yml`" @@ -637,7 +646,8 @@ elements. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.superfences] + [project.markdown_extensions.pymdownx] + superfences = {} ``` === "`mkdocs.yml`" @@ -656,10 +666,16 @@ the definitions of [Mermaid.js] diagrams to be interpreted in the browser: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.superfences] - custom_fences = [ - { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" } - ] + [project.markdown_extensions.pymdownx] + superfences = { + custom_fences = [ + { + name = "mermaid", + class = "mermaid", + format = "pymdownx.superfences.fence_code_format", + }, + ], + } ``` === "`mkdocs.yml`" @@ -709,8 +725,8 @@ related content and code blocks under accessible tabs. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed] - alternate_style = true + [project.markdown_extensions.pymdownx] + tabbed = { alternate_style = true } ``` === "`mkdocs.yml`" @@ -731,8 +747,8 @@ This option enables the content tabs [alternate style], which has [better === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed] - alternate_style = true + [project.markdown_extensions.pymdownx] + tabbed = { alternate_style = true } ``` === "`mkdocs.yml`" @@ -751,8 +767,8 @@ prepends the id of the header to the `id` of the tab: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed] - combine_header_slug = true + [project.markdown_extensions.pymdownx] + tabbed = { combine_header_slug = true } ``` === "`mkdocs.yml`" @@ -772,9 +788,11 @@ Markdown Extensions][Slugs]. To produce all-lowercase slugs: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed.slugify] - object = "pymdownx.slugs.slugify" - kwds = { case = "lower" } + [project.markdown_extensions.pymdownx] + tabbed.slugify = { + object = "pymdownx.slugs.slugify", + kwds = { case = "lower" }, + } ``` === "`mkdocs.yml`" @@ -792,8 +810,8 @@ In order to retain the case of the input: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed.slugify] - object = "pymdownx.slugs.slugify" + [project.markdown_extensions.pymdownx] + tabbed.slugify = { object = "pymdownx.slugs.slugify" } ``` === "`mkdocs.yml`" @@ -831,8 +849,8 @@ conventions. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tasklist] - custom_checkbox = true + [project.markdown_extensions.pymdownx] + tasklist = { custom_checkbox = true } ``` === "`mkdocs.yml`" @@ -853,8 +871,8 @@ checkbox styles with beautiful icons, and is therefore recommended: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tasklist] - custom_checkbox = true + [project.markdown_extensions.pymdownx] + tasklist = { custom_checkbox = true } ``` === "`mkdocs.yml`" @@ -874,8 +892,8 @@ experience perspective: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tasklist] - clickable_checkbox = true + [project.markdown_extensions.pymdownx] + tasklist = { clickable_checkbox = true } ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 3814c65..936e4c0 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -28,7 +28,8 @@ supported. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.abbr] + [project.markdown_extensions] + abbr = {} ``` === "`mkdocs.yml`" @@ -57,7 +58,8 @@ it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.admonition] + [project.markdown_extensions] + admonition = {} ``` === "`mkdocs.yml`" @@ -90,7 +92,8 @@ element with a special syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.attr_list] + [project.markdown_extensions] + attr_list = {} ``` === "`mkdocs.yml`" @@ -130,7 +133,8 @@ document. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.def_list] + [project.markdown_extensions] + def_list = {} ``` === "`mkdocs.yml`" @@ -157,7 +161,8 @@ rendered below all Markdown content of a document. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.footnotes] + [project.markdown_extensions] + footnotes = {} ``` === "`mkdocs.yml`" @@ -186,7 +191,8 @@ via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.md_in_html] + [project.markdown_extensions] + md_in_html = {} ``` === "`mkdocs.yml`" @@ -220,8 +226,8 @@ page. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink = true + [project.markdown_extensions] + toc = { permalink = true } ``` === "`mkdocs.yml`" @@ -243,8 +249,8 @@ the [site language]. Set the title explicitly via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - title = "On this page" + [project.markdown_extensions] + toc = { title = "On this page" } ``` === "`mkdocs.yml`" @@ -268,8 +274,8 @@ or string like so: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink = "⚓︎" + [project.markdown_extensions] + toc = { permalink = "⚓︎" } ``` === "`mkdocs.yml`" @@ -289,8 +295,8 @@ section itself: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink_title = "Anchor link to this section" + [project.markdown_extensions] + toc = { permalink_title = "Anchor link to this section" } ``` === "`mkdocs.yml`" @@ -310,9 +316,11 @@ Python Markdown Extensions][Slugs]: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc.slugify] - object = "pymdownx.slugs.slugify" - kwds = { case = "lower" } + [project.markdown_extensions] + toc.slugify = { + object = "pymdownx.slugs.slugify", + kwds = { case = "lower" }, + } ``` === "`mkdocs.yml`" @@ -333,8 +341,8 @@ headings to decrease the length of the table of contents: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - toc_depth = 3 + [project.markdown_extensions] + toc = { toc_depth = 3 } ``` === "`mkdocs.yml`" @@ -350,8 +358,8 @@ To remove the table of contents altogether: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - toc_depth = 0 + [project.markdown_extensions] + toc = { toc_depth = 0 } ``` === "`mkdocs.yml`" @@ -379,7 +387,8 @@ simple syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.tables] + [project.markdown_extensions] + tables = {} ``` === "`mkdocs.yml`" diff --git a/docs/setup/logo-and-icons.md b/docs/setup/logo-and-icons.md index f886542..7000137 100644 --- a/docs/setup/logo-and-icons.md +++ b/docs/setup/logo-and-icons.md @@ -154,10 +154,12 @@ your project documentation. The structure of your project should look like this: [project.theme] custom_dir = "overrides" - [project.markdown_extensions.pymdownx.emoji] - emoji_index = "zensical.extensions.emoji.twemoji" - emoji_generator = "zensical.extensions.emoji.to_svg" - options.custom_icons = ["overrides/.icons"] + [project.markdown_extensions.pymdownx] + emoji = { + emoji_index = "zensical.extensions.emoji.twemoji", + emoji_generator = "zensical.extensions.emoji.to_svg", + options.custom_icons = ["overrides/.icons"], + } ``` === "`mkdocs.yml`" diff --git a/docs/setup/navigation.md b/docs/setup/navigation.md index 613eea4..940b38c 100644 --- a/docs/setup/navigation.md +++ b/docs/setup/navigation.md @@ -254,13 +254,15 @@ instant previews on a per-page or per-section level for your documentation: === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions.preview] - configurations = [ - { targets.include = [ - "customization.md", - "setup/extensions/*" - ]} - ] + [project.markdown_extensions.zensical.extensions] + preview = { + configurations = [ + { targets.include = [ + "customization.md", + "setup/extensions/*", + ] }, + ], + } ``` === "`mkdocs.yml`" @@ -283,11 +285,13 @@ extensions in the setup guide. === "`zensical.toml`" ``` toml - [[project.markdown_extensions.zensical.extensions.preview.configurations]] - sources.include = [...] - sources.exclude = [...] - targets.include = [...] - targets.exclude = [...] + [project.markdown_extensions.zensical.extensions] + preview.configurations = [ + { + sources = { include = [...], exclude = [...] }, # (1)! + targets = { include = [...], exclude = [...] }, # (2)! + }, + ] ``` === "`mkdocs.yml`" From d7c6bfde5cc79cb202ee81fb5d4c38b17836fc0e Mon Sep 17 00:00:00 2001 From: alexvoss Date: Sat, 11 Jul 2026 02:56:20 -0400 Subject: [PATCH 3/3] fix code block start lines Signed-off-by: alexvoss --- docs/customization.md | 2 +- docs/setup/extensions/markdown-exec.md | 2 +- docs/setup/tags.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/customization.md b/docs/customization.md index 8405c90..467bfa1 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -525,7 +525,7 @@ configuration: === "`zensical.toml`" - ```toml + ``` toml [project.theme] name = "my_theme" ``` diff --git a/docs/setup/extensions/markdown-exec.md b/docs/setup/extensions/markdown-exec.md index 9652d58..28be9ab 100644 --- a/docs/setup/extensions/markdown-exec.md +++ b/docs/setup/extensions/markdown-exec.md @@ -45,7 +45,7 @@ Markdown Exec relies on the [SuperFences] extension, which is [enabled by defaul === "`zensical.toml`" - ```toml + ``` toml [project.plugins.markdown-exec] ``` diff --git a/docs/setup/tags.md b/docs/setup/tags.md index 2b287cd..439bcfd 100644 --- a/docs/setup/tags.md +++ b/docs/setup/tags.md @@ -35,7 +35,7 @@ by adding the following to your configuration: === "`zensical.toml`" - ```toml + ``` toml [project.extra.tags] = "" ``` @@ -77,7 +77,7 @@ setting: === "`zensical.toml`" - ```toml + ``` toml [project.theme.icon.tag] default = "" = "" @@ -96,7 +96,7 @@ setting: ??? example "Expand to see an example" === "`zensical.toml`" - ```toml + ``` toml [project.theme.icon.tag] default = "lucide/hash" html = "fontawesome/brands/html5"