From 5beccd211557c89067b844b82bd7d71fcaf1a211 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 7 Jul 2026 09:50:13 -0400 Subject: [PATCH 1/8] 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 2f2caea..f867451 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 cb54e80..44faaa1 100644 --- a/docs/authoring/code-blocks.md +++ b/docs/authoring/code-blocks.md @@ -20,13 +20,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 a40f871..786c534 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -20,9 +20,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 e6a062c..6bd0412 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 fdaa530..2304fb4 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 32306cb..dcfb19e 100644 --- a/docs/authoring/icons-emojis.md +++ b/docs/authoring/icons-emojis.md @@ -19,8 +19,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 3e5aeef..cfbbe6d 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 dbc0425..0c5d8ab 100644 --- a/docs/authoring/lists.md +++ b/docs/authoring/lists.md @@ -20,9 +20,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 e35fd05..e198850 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 0d8fa0f..99a30f2 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -80,42 +80,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 603b84d..eda8957 100644 --- a/docs/setup/extensions/mkdocstrings.md +++ b/docs/setup/extensions/mkdocstrings.md @@ -42,11 +42,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 039110e..4f04b49 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -129,9 +129,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`" @@ -293,9 +294,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 @@ -470,8 +471,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 795ea51ed89eb075a9d0df15b306c30d52327c5a Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 7 Jul 2026 13:09:06 -0400 Subject: [PATCH 2/8] 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 9fb6320..d67e87c 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 786c534..cd53014 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -68,9 +68,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 f371541..b3bdfbf 100644 --- a/docs/authoring/data-tables.md +++ b/docs/authoring/data-tables.md @@ -20,7 +20,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 63cf72c..82b4998 100644 --- a/docs/authoring/diagrams.md +++ b/docs/authoring/diagrams.md @@ -21,10 +21,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 4fa62ad..91a4338 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 bab3cce..3cc6e19 100644 --- a/docs/authoring/math.md +++ b/docs/authoring/math.md @@ -60,8 +60,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`" @@ -134,8 +135,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 e198850..5d3da48 100644 --- a/docs/authoring/tooltips.md +++ b/docs/authoring/tooltips.md @@ -154,8 +154,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 99a30f2..20be7f2 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -110,7 +110,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 14b303e..3d7bef8 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`" @@ -88,8 +89,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`" @@ -107,8 +108,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`" @@ -127,8 +128,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`" @@ -146,8 +147,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 ff3af97..9e46dcc 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`" @@ -44,8 +45,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`" @@ -63,8 +64,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`" @@ -83,15 +84,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`" @@ -119,8 +120,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`" @@ -138,8 +139,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`" @@ -157,8 +158,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`" @@ -176,8 +177,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`" @@ -195,8 +196,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`" @@ -214,8 +215,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`" @@ -233,8 +234,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`" @@ -252,8 +253,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`" @@ -271,8 +272,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`" @@ -290,8 +291,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`" @@ -309,8 +310,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 4f04b49..90b0df3 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -24,8 +24,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`" @@ -106,7 +106,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`" @@ -162,7 +163,8 @@ user. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.details] + [project.markdown_extensions.pymdownx] + details = {} ``` === "`mkdocs.yml`" @@ -184,9 +186,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 @@ -216,8 +220,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`" @@ -236,8 +240,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`" @@ -257,10 +261,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`" @@ -327,8 +333,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`" @@ -347,8 +353,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`" @@ -369,8 +375,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`" @@ -391,8 +397,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`" @@ -418,8 +424,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`" @@ -438,8 +444,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`" @@ -501,7 +507,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`" @@ -528,7 +535,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`" @@ -551,7 +559,8 @@ syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.snippets] + [project.markdown_extensions.pymdownx] + snippets = {} ``` === "`mkdocs.yml`" @@ -579,7 +588,8 @@ elements. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.superfences] + [project.markdown_extensions.pymdownx] + superfences = {} ``` === "`mkdocs.yml`" @@ -599,10 +609,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`" @@ -642,8 +658,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`" @@ -664,8 +680,8 @@ behavior on mobile viewports], and is the only supported style: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.tabbed] - alternate_style = true + [project.markdown_extensions.pymdownx] + tabbed = { alternate_style = true } ``` === "`mkdocs.yml`" @@ -684,8 +700,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`" @@ -706,9 +722,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`" @@ -726,8 +744,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`" @@ -757,8 +775,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`" @@ -779,8 +797,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`" @@ -800,8 +818,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 5d66bce..873f359 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -25,7 +25,8 @@ supported. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.abbr] + [project.markdown_extensions] + abbr = {} ``` === "`mkdocs.yml`" @@ -50,7 +51,8 @@ it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.admonition] + [project.markdown_extensions] + admonition = {} ``` === "`mkdocs.yml`" @@ -77,7 +79,8 @@ element with a special syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.attr_list] + [project.markdown_extensions] + attr_list = {} ``` === "`mkdocs.yml`" @@ -107,7 +110,8 @@ document. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.def_list] + [project.markdown_extensions] + def_list = {} ``` === "`mkdocs.yml`" @@ -130,7 +134,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`" @@ -155,7 +160,8 @@ via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.md_in_html] + [project.markdown_extensions] + md_in_html = {} ``` === "`mkdocs.yml`" @@ -186,8 +192,8 @@ page. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink = true + [project.markdown_extensions] + toc = { permalink = true } ``` === "`mkdocs.yml`" @@ -209,8 +215,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`" @@ -234,8 +240,8 @@ or string like so: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink = "⚓︎" + [project.markdown_extensions] + toc = { permalink = "⚓︎" } ``` === "`mkdocs.yml`" @@ -256,8 +262,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`" @@ -278,9 +284,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`" @@ -302,8 +310,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`" @@ -319,8 +327,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`" @@ -345,7 +353,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 9428164..8e8d120 100644 --- a/docs/setup/logo-and-icons.md +++ b/docs/setup/logo-and-icons.md @@ -159,10 +159,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 2dde032..faec4d5 100644 --- a/docs/setup/navigation.md +++ b/docs/setup/navigation.md @@ -246,13 +246,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`" @@ -276,11 +278,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 5da8c7e2f7a796207b1124ccf1cb89cf57a63483 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 14 Jul 2026 10:53:20 -0400 Subject: [PATCH 3/8] refator: using pymdownx prefix in extensions Signed-off-by: alexvoss --- docs/authoring/code-blocks.md | 10 +- docs/authoring/content-tabs.md | 10 +- docs/authoring/diagrams.md | 4 +- docs/authoring/formatting.md | 10 +- docs/authoring/math.md | 8 +- docs/authoring/tooltips.md | 4 +- docs/setup/extensions/about.md | 32 ++--- .../extensions/python-markdown-extensions.md | 124 +++++++++--------- docs/setup/logo-and-icons.md | 4 +- 9 files changed, 103 insertions(+), 103 deletions(-) diff --git a/docs/authoring/code-blocks.md b/docs/authoring/code-blocks.md index 44faaa1..3849ac7 100644 --- a/docs/authoring/code-blocks.md +++ b/docs/authoring/code-blocks.md @@ -20,15 +20,15 @@ following lines to your configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - highlight = { + [project.markdown_extensions] + pymdownx.highlight = { anchor_linenums = true, line_spans = "__span", pygments_lang_class = true, } - inlinehilite = {} - snippets = {} - superfences = {} + pymdownx.inlinehilite = {} + pymdownx.snippets = {} + pymdownx.superfences = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/content-tabs.md b/docs/authoring/content-tabs.md index cd53014..d530767 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -20,9 +20,9 @@ following lines to your configuration file: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - superfences = {} - tabbed = { alternate_style = true } + [project.markdown_extensions] + pymdownx.superfences = {} + pymdownx.tabbed = { alternate_style = true } ``` === "`mkdocs.yml`" @@ -68,8 +68,8 @@ function with the following lines: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - tabbed.slugify = { + [project.markdown_extensions] + pymdownx.tabbed.slugify = { object = "pymdownx.slugs.slugify", kwds = { case = "lower" }, } diff --git a/docs/authoring/diagrams.md b/docs/authoring/diagrams.md index 82b4998..a750f74 100644 --- a/docs/authoring/diagrams.md +++ b/docs/authoring/diagrams.md @@ -21,8 +21,8 @@ will automatically initialize the JavaScript runtime when a page includes a === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - superfences = { + [project.markdown_extensions] + pymdownx.superfences = { custom_fences = [ { name = "mermaid", diff --git a/docs/authoring/formatting.md b/docs/authoring/formatting.md index 6bd0412..a4fb023 100644 --- a/docs/authoring/formatting.md +++ b/docs/authoring/formatting.md @@ -18,11 +18,11 @@ configuration: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - caret = {} - keys = {} - mark = {} - tilde = {} + [project.markdown_extensions] + pymdownx.caret = {} + pymdownx.keys = {} + pymdownx.mark = {} + pymdownx.tilde = {} ``` === "`mkdocs.yml`" diff --git a/docs/authoring/math.md b/docs/authoring/math.md index 3cc6e19..531891b 100644 --- a/docs/authoring/math.md +++ b/docs/authoring/math.md @@ -61,8 +61,8 @@ to your configuration: "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`" @@ -135,8 +135,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 5d3da48..41e55cb 100644 --- a/docs/authoring/tooltips.md +++ b/docs/authoring/tooltips.md @@ -154,8 +154,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 20be7f2..98469cd 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -89,26 +89,26 @@ extensions are enabled by default: md_in_html = {} toc = { permalink = true } - [project.markdown_extensions.pymdownx] - arithmatex = { generic = true } - betterem = {} - caret = {} - details = {} - emoji = { + [project.markdown_extensions] + pymdownx.arithmatex = { generic = true } + pymdownx.betterem = {} + pymdownx.caret = {} + pymdownx.details = {} + pymdownx.emoji = { emoji_generator = "zensical.extensions.emoji.to_svg", emoji_index = "zensical.extensions.emoji.twemoji", } - highlight = { + pymdownx.highlight = { anchor_linenums = true, line_spans = "__span", pygments_lang_class = true, } - inlinehilite = {} - keys = {} - magiclink = {} - mark = {} - smartsymbols = {} - superfences = { + pymdownx.inlinehilite = {} + pymdownx.keys = {} + pymdownx.magiclink = {} + pymdownx.mark = {} + pymdownx.smartsymbols = {} + pymdownx.superfences = { custom_fences = [ { name = "mermaid", @@ -117,9 +117,9 @@ extensions are enabled by default: }, ], } - tabbed = { alternate_style = true, combine_header_slug = true } - tasklist = { custom_checkbox = true } - tilde = {} + pymdownx.tabbed = { alternate_style = true, combine_header_slug = true } + pymdownx.tasklist = { custom_checkbox = true } + pymdownx.tilde = {} ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 90b0df3..6fcf3dd 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -24,8 +24,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`" @@ -106,8 +106,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`" @@ -130,10 +130,10 @@ via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - caret = {} - mark = {} - tilde = {} + [project.markdown_extensions] + pymdownx.caret = {} + pymdownx.mark = {} + pymdownx.tilde = {} ``` === "`mkdocs.yml`" @@ -163,8 +163,8 @@ user. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - details = {} + [project.markdown_extensions] + pymdownx.details = {} ``` === "`mkdocs.yml`" @@ -186,8 +186,8 @@ in `*.svg` file format into the resulting HTML page. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - emoji = { + [project.markdown_extensions] + pymdownx.emoji = { emoji_index = "zensical.extensions.emoji.twemoji", # (1)! emoji_generator = "zensical.extensions.emoji.to_svg", } @@ -220,8 +220,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`" @@ -240,8 +240,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`" @@ -261,8 +261,8 @@ Markdown or the configuration, which is explained in more detail in the === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - emoji = { + [project.markdown_extensions] + pymdownx.emoji = { emoji_index = "zensical.extensions.emoji.twemoji", emoji_generator = "zensical.extensions.emoji.to_svg", options.custom_icons = ["overrides/.icons"], @@ -300,9 +300,9 @@ The [Highlight] extension adds support for syntax highlighting of code blocks === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - highlight = { anchor_linenums = true } - superfences = {} + [project.markdown_extensions] + pymdownx.highlight = { anchor_linenums = true } + pymdownx.superfences = {} ``` 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to @@ -333,8 +333,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`" @@ -353,8 +353,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`" @@ -375,8 +375,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`" @@ -397,8 +397,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`" @@ -424,8 +424,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`" @@ -444,8 +444,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`" @@ -477,9 +477,9 @@ which it sources its configuration. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - highlight = {} - inlinehilite = {} + [project.markdown_extensions] + pymdownx.highlight = {} + pymdownx.inlinehilite = {} ``` === "`mkdocs.yml`" @@ -507,8 +507,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`" @@ -535,8 +535,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`" @@ -559,8 +559,8 @@ syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - snippets = {} + [project.markdown_extensions] + pymdownx.snippets = {} ``` === "`mkdocs.yml`" @@ -588,8 +588,8 @@ elements. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - superfences = {} + [project.markdown_extensions] + pymdownx.superfences = {} ``` === "`mkdocs.yml`" @@ -609,8 +609,8 @@ the definitions of [Mermaid.js] diagrams to be interpreted in the browser: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - superfences = { + [project.markdown_extensions] + pymdownx.superfences = { custom_fences = [ { name = "mermaid", @@ -658,8 +658,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`" @@ -680,8 +680,8 @@ behavior on mobile viewports], and is the only supported style: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - tabbed = { alternate_style = true } + [project.markdown_extensions] + pymdownx.tabbed = { alternate_style = true } ``` === "`mkdocs.yml`" @@ -700,8 +700,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`" @@ -722,8 +722,8 @@ Markdown Extensions][Slugs]. To produce all-lowercase slugs: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx] - tabbed.slugify = { + [project.markdown_extensions] + pymdownx.tabbed.slugify = { object = "pymdownx.slugs.slugify", kwds = { case = "lower" }, } @@ -744,8 +744,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`" @@ -775,8 +775,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`" @@ -797,8 +797,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`" @@ -818,8 +818,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/logo-and-icons.md b/docs/setup/logo-and-icons.md index 8e8d120..3233642 100644 --- a/docs/setup/logo-and-icons.md +++ b/docs/setup/logo-and-icons.md @@ -159,8 +159,8 @@ your project documentation. The structure of your project should look like this: [project.theme] custom_dir = "overrides" - [project.markdown_extensions.pymdownx] - emoji = { + [project.markdown_extensions] + pymdownx.emoji = { emoji_index = "zensical.extensions.emoji.twemoji", emoji_generator = "zensical.extensions.emoji.to_svg", options.custom_icons = ["overrides/.icons"], From 79632bf3101e490428e8269d2599ad01405b8a04 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Sat, 18 Jul 2026 07:25:33 +0200 Subject: [PATCH 4/8] fix: duplicate TOML table Signed-off-by: alexvoss --- docs/setup/extensions/about.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/setup/extensions/about.md b/docs/setup/extensions/about.md index 98469cd..cd73321 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -89,7 +89,6 @@ extensions are enabled by default: md_in_html = {} toc = { permalink = true } - [project.markdown_extensions] pymdownx.arithmatex = { generic = true } pymdownx.betterem = {} pymdownx.caret = {} From c99409b197a94fa100352cf060aebeb894581066 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Sat, 18 Jul 2026 08:20:13 +0200 Subject: [PATCH 5/8] fix: separate slugify from tabbed Signed-off-by: alexvoss --- docs/setup/extensions/python-markdown-extensions.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 6fcf3dd..3eec338 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -723,9 +723,11 @@ Markdown Extensions][Slugs]. To produce all-lowercase slugs: ``` toml [project.markdown_extensions] - pymdownx.tabbed.slugify = { - object = "pymdownx.slugs.slugify", - kwds = { case = "lower" }, + pymdownx.tabbed = { + slugify = { + object = "pymdownx.slugs.slugify", + kwds = { case = "lower" }, + }, } ``` @@ -745,7 +747,9 @@ In order to retain the case of the input: ``` toml [project.markdown_extensions] - pymdownx.tabbed.slugify = { object = "pymdownx.slugs.slugify" } + pymdownx.tabbed = { + slugify = { object = "pymdownx.slugs.slugify" }, + } ``` === "`mkdocs.yml`" From 8c1bb464380327e81b39d2ab5da6a25bfd6e822a Mon Sep 17 00:00:00 2001 From: alexvoss Date: Sat, 18 Jul 2026 08:23:38 +0200 Subject: [PATCH 6/8] fix: separate slugify option from toc extension Signed-off-by: alexvoss --- docs/setup/extensions/python-markdown.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 873f359..b004ccd 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -285,9 +285,11 @@ Python Markdown Extensions][Slugs]: ``` toml [project.markdown_extensions] - toc.slugify = { - object = "pymdownx.slugs.slugify", - kwds = { case = "lower" }, + toc = { + slugify = { + object = "pymdownx.slugs.slugify", + kwds = { case = "lower" }, + }, } ``` From 88c447f1afd4705d20df8a49c163908e30a14d26 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Sat, 18 Jul 2026 08:28:51 +0200 Subject: [PATCH 7/8] fix: separate configurations from preview Signed-off-by: alexvoss --- docs/setup/navigation.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/setup/navigation.md b/docs/setup/navigation.md index faec4d5..da0870c 100644 --- a/docs/setup/navigation.md +++ b/docs/setup/navigation.md @@ -279,12 +279,14 @@ extensions in the setup guide. ``` toml [project.markdown_extensions.zensical.extensions] - preview.configurations = [ - { - sources = { include = [...], exclude = [...] }, # (1)! - targets = { include = [...], exclude = [...] }, # (2)! - }, - ] + preview = { + configurations = [ + { + sources = { include = [...], exclude = [...] }, # (1)! + targets = { include = [...], exclude = [...] }, # (2)! + }, + ], + } ``` === "`mkdocs.yml`" From 9afa3755e519036af39a042bc63bf3f871299d5e Mon Sep 17 00:00:00 2001 From: squidfunk Date: Tue, 4 Aug 2026 17:25:03 +0200 Subject: [PATCH 8/8] docs: make sure TOML examples are consistent Signed-off-by: squidfunk --- docs/authoring/admonitions.md | 4 +- docs/authoring/code-blocks.md | 32 +++-- docs/authoring/content-tabs.md | 15 ++- docs/authoring/data-tables.md | 4 +- docs/authoring/diagrams.md | 18 +-- docs/authoring/footnotes.md | 2 +- docs/authoring/icons-emojis.md | 17 ++- docs/authoring/lists.md | 4 +- docs/authoring/math.md | 20 +-- docs/authoring/tooltips.md | 6 +- docs/customization.md | 28 +++-- docs/setup/analytics.md | 4 +- docs/setup/basics.md | 5 +- docs/setup/colors.md | 11 +- docs/setup/data-privacy.md | 28 +++-- docs/setup/extensions/about.md | 80 +++++------- docs/setup/extensions/glightbox.md | 48 ++++--- docs/setup/extensions/macros.md | 102 ++++++++++----- docs/setup/extensions/mkdocstrings.md | 6 +- .../extensions/python-markdown-extensions.md | 112 +++++++++++------ docs/setup/extensions/python-markdown.md | 32 +++-- docs/setup/fonts.md | 4 +- docs/setup/footer.md | 2 +- docs/setup/header.md | 4 +- docs/setup/language.md | 4 +- docs/setup/logo-and-icons.md | 8 +- docs/setup/navigation.md | 117 +++++++++--------- docs/setup/offline.md | 18 ++- docs/setup/repository.md | 2 +- docs/setup/search.md | 2 +- docs/setup/versioning.md | 5 +- 31 files changed, 457 insertions(+), 287 deletions(-) diff --git a/docs/authoring/admonitions.md b/docs/authoring/admonitions.md index f867451..056b3e6 100644 --- a/docs/authoring/admonitions.md +++ b/docs/authoring/admonitions.md @@ -49,8 +49,8 @@ lines to your configuration: === "`zensical.toml`" ``` toml - [project.theme.icon] - admonition = { = ""} + [project.theme.icon.admonition] + = "" ``` ??? example "Expand to show alternate icon sets" diff --git a/docs/authoring/code-blocks.md b/docs/authoring/code-blocks.md index 3849ac7..589038c 100644 --- a/docs/authoring/code-blocks.md +++ b/docs/authoring/code-blocks.md @@ -22,9 +22,9 @@ following lines to your configuration: ``` toml [project.markdown_extensions] pymdownx.highlight = { - anchor_linenums = true, - line_spans = "__span", - pygments_lang_class = true, + anchor_linenums = true, + line_spans = "__span", + pygments_lang_class = true, } pymdownx.inlinehilite = {} pymdownx.snippets = {} @@ -66,7 +66,7 @@ your configuration to enable them globally: ``` toml [project.theme] features = [ - "content.code.copy" + "content.code.copy", ] ``` @@ -115,7 +115,7 @@ to your configuration to enable it globally: ``` toml [project.theme] features = [ - "content.code.select" + "content.code.select", ] ``` @@ -161,7 +161,7 @@ your configuration to enable them globally: ``` toml [project.theme] features = [ - "content.code.annotate" # (1)! + "content.code.annotate", # (1)! ] ``` @@ -298,7 +298,9 @@ language of the block can be placed, e.g. for JavaScript in `#!js // ...` and ```` markdown title="Code block with annotation" ``` toml [project.theme] -features = ["content.code.annotate"] # (1)! +features = [ + "content.code.annotate", # (1)! +] ``` 1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted @@ -309,7 +311,9 @@ features = ["content.code.annotate"] # (1)! ``` toml [project.theme] -features = ["content.code.annotate"] # (1)! +features = [ + "content.code.annotate", # (1)! +] ``` 1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted @@ -507,7 +511,9 @@ a new color by using an [additional style sheet]: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" @@ -533,7 +539,9 @@ override it as part of your [additional style sheet]: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" @@ -561,7 +569,9 @@ of an [additional style sheet]: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" diff --git a/docs/authoring/content-tabs.md b/docs/authoring/content-tabs.md index d530767..c4620bb 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -22,7 +22,9 @@ following lines to your configuration file: ``` toml [project.markdown_extensions] pymdownx.superfences = {} - pymdownx.tabbed = { alternate_style = true } + pymdownx.tabbed = { + alternate_style = true + } ``` === "`mkdocs.yml`" @@ -69,9 +71,11 @@ function with the following lines: ``` toml [project.markdown_extensions] - pymdownx.tabbed.slugify = { + pymdownx.tabbed = { + slugify = { object = "pymdownx.slugs.slugify", - kwds = { case = "lower" }, + kwds.case = "lower", + } } ``` @@ -97,8 +101,9 @@ following lines to your configuration: ``` toml [project.theme] - features = ["content.tabs.link"] - + features = [ + "content.tabs.link", + ] ``` === "`mkdocs.yml`" diff --git a/docs/authoring/data-tables.md b/docs/authoring/data-tables.md index b3bdfbf..b25dca7 100644 --- a/docs/authoring/data-tables.md +++ b/docs/authoring/data-tables.md @@ -149,8 +149,8 @@ via [additional JavaScript]: ``` toml [project] extra_javascript = [ - "https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js", - "javascripts/tablesort.js" + "https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js", + "javascripts/tablesort.js", ] ``` diff --git a/docs/authoring/diagrams.md b/docs/authoring/diagrams.md index a750f74..9f28e24 100644 --- a/docs/authoring/diagrams.md +++ b/docs/authoring/diagrams.md @@ -23,13 +23,13 @@ will automatically initialize the JavaScript runtime when a page includes a ``` toml [project.markdown_extensions] pymdownx.superfences = { - custom_fences = [ - { - name = "mermaid", - class = "mermaid", - format = "pymdownx.superfences.fence_code_format", - }, - ], + custom_fences = [ + { + name = "mermaid", + class = "mermaid", + format = "pymdownx.superfences.fence_code_format", + }, + ], } ``` @@ -299,7 +299,9 @@ you can do so by adding a custom JavaScript file to your configuration: ``` toml [project] - extra_javascript = ["javascripts/mermaid.mjs"] + extra_javascript = [ + "javascripts/mermaid.mjs", + ] ``` === "`mkdocs.yml`" diff --git a/docs/authoring/footnotes.md b/docs/authoring/footnotes.md index 91a4338..cd5e74c 100644 --- a/docs/authoring/footnotes.md +++ b/docs/authoring/footnotes.md @@ -45,7 +45,7 @@ enabled with: ``` toml [project.theme] features = [ - "content.footnote.tooltips" + "content.footnote.tooltips", ] ``` diff --git a/docs/authoring/icons-emojis.md b/docs/authoring/icons-emojis.md index dcfb19e..bd1980b 100644 --- a/docs/authoring/icons-emojis.md +++ b/docs/authoring/icons-emojis.md @@ -21,7 +21,10 @@ shortcodes. Add the following lines to your configuration: ``` toml [project.markdown_extensions] attr_list = {} - pymdownx.emoji = {} + pymdownx.emoji = { + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + } ``` === "`mkdocs.yml`" @@ -30,8 +33,8 @@ shortcodes. Add the following lines to your configuration: markdown_extensions: - attr_list - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_generator: !!python/name:zensical.extensions.emoji.to_svg + emoji_index: !!python/name:zensical.extensions.emoji.twemoji ``` See additional configuration options: @@ -111,7 +114,9 @@ While HTML allows inline styles, it's always recommended to add an ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" @@ -159,7 +164,9 @@ dedicated CSS class to the icon: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" diff --git a/docs/authoring/lists.md b/docs/authoring/lists.md index 0c5d8ab..0311ed2 100644 --- a/docs/authoring/lists.md +++ b/docs/authoring/lists.md @@ -22,7 +22,9 @@ your configuration: ``` toml [project.markdown_extensions] def_list = {} - pymdownx.tasklist = { custom_checkbox = true } + pymdownx.tasklist = { + custom_checkbox = true + } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/math.md b/docs/authoring/math.md index 531891b..38104f1 100644 --- a/docs/authoring/math.md +++ b/docs/authoring/math.md @@ -57,12 +57,14 @@ to your configuration: ``` toml [project] extra_javascript = [ - "javascripts/mathjax.js", - "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js" + "javascripts/mathjax.js", + "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js", ] [project.markdown_extensions] - pymdownx.arithmatex = { generic = true } + pymdownx.arithmatex = { + generic = true, + } ``` === "`mkdocs.yml`" @@ -126,17 +128,19 @@ supports a subset of LaTeX syntax and can render math to HTML and SVG. To use ``` toml [project] extra_javascript = [ - "javascripts/katex.js", - "https://unpkg.com/katex@0/dist/katex.min.js", - "https://unpkg.com/katex@0/dist/contrib/auto-render.min.js" + "javascripts/katex.js", + "https://unpkg.com/katex@0/dist/katex.min.js", + "https://unpkg.com/katex@0/dist/contrib/auto-render.min.js", ] extra_css = [ - "https://unpkg.com/katex@0/dist/katex.min.css" + "https://unpkg.com/katex@0/dist/katex.min.css", ] [project.markdown_extensions] - pymdownx.arithmatex = { generic = true } + pymdownx.arithmatex = { + generic = true, + } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/tooltips.md b/docs/authoring/tooltips.md index 41e55cb..2448958 100644 --- a/docs/authoring/tooltips.md +++ b/docs/authoring/tooltips.md @@ -53,7 +53,7 @@ lines to your configuration:: ``` toml [project.theme] features = [ - "content.tooltips" + "content.tooltips", ] ``` @@ -155,7 +155,9 @@ pages with the following configuration: ``` toml [project.markdown_extensions] - pymdownx.snippets = { auto_append = ["includes/abbreviations.md"] } + pymdownx.snippets = { + auto_append = ["includes/abbreviations.md"], + } ``` === "`mkdocs.yml`" diff --git a/docs/customization.md b/docs/customization.md index fa6e2d5..e81be8a 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -40,7 +40,9 @@ design or apply specific branding, simply place your style sheet file within the ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" @@ -80,7 +82,9 @@ the `docs` directory: ``` toml [project] - extra_javascript = ["javascripts/extra.js"] + extra_javascript = [ + "javascripts/extra.js", + ] ``` === "`mkdocs.yml`" @@ -125,9 +129,13 @@ to be loaded as a module: === "`zensical.toml`" ``` toml - [[project.extra_javascript]] - path = "javascripts/extra.js" - type = "module" + [project] + extra_javascript = [ + { + path = "javascripts/extra.js", + type = "module", + }, + ] ``` === "`mkdocs.yml`" @@ -148,9 +156,13 @@ the `async` case: === "`zensical.toml`" ``` toml - [[project.extra_javascript]] - path = "javascripts/extra.js" - async = true + [project] + extra_javascript = [ + { + path = "javascripts/extra.js", + async = true, + }, + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/analytics.md b/docs/setup/analytics.md index 9a86f71..2efc7d4 100644 --- a/docs/setup/analytics.md +++ b/docs/setup/analytics.md @@ -322,7 +322,9 @@ generated by users interacting with the feedback widget with the help of some ``` toml [project] - extra_javascript = ["javascripts/feedback.js"] + extra_javascript = [ + "javascripts/feedback.js", + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/basics.md b/docs/setup/basics.md index 822fc84..e569511 100644 --- a/docs/setup/basics.md +++ b/docs/setup/basics.md @@ -327,7 +327,10 @@ configuration: ``` toml [project] - watch = ["data.csv", "fragments"] + watch = [ + "data.csv", + "fragments", + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/colors.md b/docs/setup/colors.md index 752beb3..07ccccb 100644 --- a/docs/setup/colors.md +++ b/docs/setup/colors.md @@ -179,11 +179,13 @@ following lines to allow users to switch between light and dark mode: === "`zensical.toml`" ``` toml + # Palette toggle for light mode [[project.theme.palette]] # (1)! scheme = "default" toggle.icon = "lucide/sun" toggle.name = "Switch to dark mode" + # Palette toggle for dark mode [[project.theme.palette]] scheme = "slate" toggle.icon = "lucide/moon" @@ -395,7 +397,9 @@ your configuration: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" @@ -427,7 +431,10 @@ in the [color schemes][palette.scheme] section: ``` toml [project] theme.palette.scheme = "youtube" - extra_css = ["stylesheets/extra.css"] + + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/data-privacy.md b/docs/setup/data-privacy.md index 99b5261..fc20c07 100644 --- a/docs/setup/data-privacy.md +++ b/docs/setup/data-privacy.md @@ -25,10 +25,10 @@ following to your configuration: [project.extra.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. + 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. """ # (1)! ``` @@ -101,8 +101,10 @@ The following properties are available: ``` toml [project.extra.consent.cookies] - analytics.name = "Google Analytics" - checked = false + analytics = { + name = "Google Analytics", + checked = false, + } ``` === "`mkdocs.yml`" @@ -122,8 +124,10 @@ The following properties are available: ``` toml [project.extra.consent.cookies] - analytics.name = "Google Analytics" # (1)! - custom = "Custom cookie" + analytics = { + name = "Google Analytics", # (1)! + custom = "Custom cookie", + } ``` 1. If you define a custom cookie as part of the `cookies` property, @@ -158,8 +162,8 @@ The following properties are available: ``` toml [project.extra.consent] actions = [ - "accept", - "manage" # (1)! + "accept", + "manage", # (1)! ] ``` @@ -238,7 +242,9 @@ Use [additional JavaScript] to query the result: ``` toml [project] - extra_javascript = ["javascripts/consent.js"] + extra_javascript = [ + "javascripts/consent.js", + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/about.md b/docs/setup/extensions/about.md index cd73321..516a1f6 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -30,15 +30,12 @@ Python Markdown extensions described below. ## 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. +Because Zensical uses [Python Markdown], its built-in extensions are available. +Zensical also installs the [Python Markdown Extensions] package, which provides +additional extensions. Most are enabled [by default] and listed explicitly in +the `zensical.toml` file generated by `zensical new`. -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. - -The following extensions are all supported by Zensical and therefore strongly +The following extensions are supported by Zensical and therefore strongly recommended. Click on each extension to learn about its purpose and configuration: @@ -75,7 +72,7 @@ the default configuration until you find a reason to change it. This will enable most of the features listed in the [Authoring] part of this documentation. If you bootstrap your project with [`zensical new`][new command], the following -extensions are enabled by default: +default configuration is written to the generated `zensical.toml` file: === "`zensical.toml`" @@ -87,20 +84,23 @@ extensions are enabled by default: def_list = {} footnotes = {} md_in_html = {} - toc = { permalink = true } - - pymdownx.arithmatex = { generic = true } + toc = { + permalink = true, + } + pymdownx.arithmatex = { + generic = true, + } pymdownx.betterem = {} pymdownx.caret = {} pymdownx.details = {} pymdownx.emoji = { - emoji_generator = "zensical.extensions.emoji.to_svg", - emoji_index = "zensical.extensions.emoji.twemoji", + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", } pymdownx.highlight = { - anchor_linenums = true, - line_spans = "__span", - pygments_lang_class = true, + anchor_linenums = true, + line_spans = "__span", + pygments_lang_class = true, } pymdownx.inlinehilite = {} pymdownx.keys = {} @@ -108,16 +108,21 @@ extensions are enabled by default: pymdownx.mark = {} pymdownx.smartsymbols = {} pymdownx.superfences = { - custom_fences = [ - { - name = "mermaid", - class = "mermaid", - format = "pymdownx.superfences.fence_code_format", - }, - ], + custom_fences = [ + { + name = "mermaid", + class = "mermaid", + format = "pymdownx.superfences.fence_code_format", + }, + ], + } + pymdownx.tabbed = { + alternate_style = true, + combine_header_slug = true, + } + pymdownx.tasklist = { + custom_checkbox = true, } - pymdownx.tabbed = { alternate_style = true, combine_header_slug = true } - pymdownx.tasklist = { custom_checkbox = true } pymdownx.tilde = {} ``` @@ -139,8 +144,8 @@ extensions are enabled by default: - pymdownx.caret - pymdownx.details - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_generator: !!python/name:zensical.extensions.emoji.to_svg + emoji_index: !!python/name:zensical.extensions.emoji.twemoji - pymdownx.highlight: anchor_linenums: true line_spans: __span @@ -175,24 +180,6 @@ extensions are enabled by default: will allow you to add extensions to a set of defaults, customize extensions included in the defaults, as well as remove them. -## 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: - -=== "`zensical.toml`" - - ``` toml - [project] - markdown_extensions = {} - ``` - -=== "`mkdocs.yml`" - - ``` yaml - markdown_extensions: {} - ``` - [Abbreviations]: python-markdown.md#abbreviations [Admonition]: python-markdown.md#admonition [Arithmatex]: python-markdown-extensions.md#arithmatex @@ -221,4 +208,3 @@ configuration with an empty list of extensions: [Table of Contents]: python-markdown.md#table-of-contents [Tables]: python-markdown.md#tables [Tasklist]: python-markdown-extensions.md#tasklist -[turn off the defaults]: #turning-off-the-defaults diff --git a/docs/setup/extensions/glightbox.md b/docs/setup/extensions/glightbox.md index 3d7bef8..47740b7 100644 --- a/docs/setup/extensions/glightbox.md +++ b/docs/setup/extensions/glightbox.md @@ -12,8 +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`" @@ -32,8 +32,10 @@ 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`" @@ -51,8 +53,10 @@ 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`" @@ -70,8 +74,10 @@ 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 +95,10 @@ 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 +116,12 @@ 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 +140,10 @@ 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 +161,10 @@ 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 9e46dcc..5248975 100644 --- a/docs/setup/extensions/macros.md +++ b/docs/setup/extensions/macros.md @@ -12,8 +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`" @@ -45,8 +45,10 @@ 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`" @@ -64,8 +66,12 @@ 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`" @@ -84,15 +90,23 @@ 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`" @@ -120,8 +134,10 @@ 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`" @@ -139,8 +155,10 @@ 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`" @@ -158,8 +176,10 @@ 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`" @@ -177,8 +197,10 @@ 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`" @@ -196,8 +218,10 @@ 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`" @@ -215,8 +239,10 @@ 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`" @@ -234,8 +260,10 @@ 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`" @@ -253,8 +281,10 @@ 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`" @@ -272,8 +302,10 @@ 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`" @@ -291,8 +323,10 @@ 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`" @@ -310,8 +344,12 @@ 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/mkdocstrings.md b/docs/setup/extensions/mkdocstrings.md index eda8957..f92766d 100644 --- a/docs/setup/extensions/mkdocstrings.md +++ b/docs/setup/extensions/mkdocstrings.md @@ -43,9 +43,9 @@ Configure mkdocstrings as a plugin: inventories = ["https://docs.python.org/3/objects.inv"] paths = ["src"] options = { - docstring_style = "google", - inherited_members = true, - show_source = false, + docstring_style = "google", + inherited_members = true, + show_source = false, } ``` diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 3eec338..a32c450 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -25,7 +25,9 @@ mathematical typesetting. Enable it via: ``` toml [project.markdown_extensions] - pymdownx.arithmatex = { generic = true } + pymdownx.arithmatex = { + generic = true, + } ``` === "`mkdocs.yml`" @@ -76,8 +78,8 @@ of [additional JavaScript]: ``` toml [project] extra_javascript = [ - "javascripts/mathjax.js", - "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js" + "javascripts/mathjax.js", + "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js", ] ``` @@ -188,8 +190,8 @@ in `*.svg` file format into the resulting HTML page. Enable it via: ``` toml [project.markdown_extensions] pymdownx.emoji = { - emoji_index = "zensical.extensions.emoji.twemoji", # (1)! - emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", # (1)! } ``` @@ -221,7 +223,9 @@ recommended due to [restrictions in licensing][Emoji index]: ``` toml [project.markdown_extensions] - pymdownx.emoji = { emoji_index = "zensical.extensions.emoji.twemoji" } + pymdownx.emoji = { + emoji_index = "zensical.extensions.emoji.twemoji", + } ``` === "`mkdocs.yml`" @@ -241,7 +245,9 @@ that icons can only be used together with the `to_svg` configuration: ``` toml [project.markdown_extensions] - pymdownx.emoji = { emoji_generator = "zensical.extensions.emoji.to_svg" } + pymdownx.emoji = { + emoji_generator = "zensical.extensions.emoji.to_svg", + } ``` === "`mkdocs.yml`" @@ -263,9 +269,11 @@ Markdown or the configuration, which is explained in more detail in the ``` toml [project.markdown_extensions] pymdownx.emoji = { - emoji_index = "zensical.extensions.emoji.twemoji", - emoji_generator = "zensical.extensions.emoji.to_svg", - options.custom_icons = ["overrides/.icons"], + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + options.custom_icons = [ + "overrides/.icons", + ], } ``` @@ -274,8 +282,8 @@ Markdown or the configuration, which is explained in more detail in the ``` yaml markdown_extensions: - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:zensical.extensions.emoji.twemoji + emoji_generator: !!python/name:zensical.extensions.emoji.to_svg options: custom_icons: - overrides/.icons @@ -301,7 +309,9 @@ The [Highlight] extension adds support for syntax highlighting of code blocks ``` toml [project.markdown_extensions] - pymdownx.highlight = { anchor_linenums = true } + pymdownx.highlight = { + anchor_linenums = true, + } pymdownx.superfences = {} ``` @@ -334,7 +344,9 @@ function. Enable via: ``` toml [project.markdown_extensions] - pymdownx.highlight = { pygments_lang_class = true } + pymdownx.highlight = { + pygments_lang_class = true, + } ``` === "`mkdocs.yml`" @@ -354,7 +366,9 @@ the name of the language being used, e.g. `Python` is printed for a `py` block: ``` toml [project.markdown_extensions] - pymdownx.highlight = { auto_title = true } + pymdownx.highlight = { + auto_title = true, + } ``` === "`mkdocs.yml`" @@ -376,7 +390,9 @@ which also contains some tips on working with line numbers: ``` toml [project.markdown_extensions] - pymdownx.highlight = { linenums = true } + pymdownx.highlight = { + linenums = true, + } ``` === "`mkdocs.yml`" @@ -398,7 +414,9 @@ line itself: ``` toml [project.markdown_extensions] - pymdownx.highlight = { linenums_style = "pymdownx-inline" } + pymdownx.highlight = { + linenums_style = "pymdownx-inline", + } ``` === "`mkdocs.yml`" @@ -425,7 +443,9 @@ with anchor links, so they can be hyperlinked and shared more easily: ``` toml [project.markdown_extensions] - pymdownx.highlight = { anchor_linenums = true } + pymdownx.highlight = { + anchor_linenums = true, + } ``` === "`mkdocs.yml`" @@ -445,7 +465,9 @@ which is essential for features like line highlighting to work correctly: ``` toml [project.markdown_extensions] - pymdownx.highlight = { line_spans = "__span" } + pymdownx.highlight = { + line_spans = "__span", + } ``` === "`mkdocs.yml`" @@ -611,13 +633,13 @@ the definitions of [Mermaid.js] diagrams to be interpreted in the browser: ``` toml [project.markdown_extensions] pymdownx.superfences = { - custom_fences = [ - { - name = "mermaid", - class = "mermaid", - format = "pymdownx.superfences.fence_code_format", - }, - ], + custom_fences = [ + { + name = "mermaid", + class = "mermaid", + format = "pymdownx.superfences.fence_code_format", + }, + ], } ``` @@ -659,7 +681,10 @@ related content and code blocks under accessible tabs. Enable it via: ``` toml [project.markdown_extensions] - pymdownx.tabbed = { alternate_style = true } + pymdownx.tabbed = { + alternate_style = true, + combine_header_slug = true, + } ``` === "`mkdocs.yml`" @@ -668,6 +693,7 @@ related content and code blocks under accessible tabs. Enable it via: markdown_extensions: - pymdownx.tabbed: alternate_style: true + combine_header_slug: true ``` The following configuration options are supported: @@ -681,7 +707,9 @@ behavior on mobile viewports], and is the only supported style: ``` toml [project.markdown_extensions] - pymdownx.tabbed = { alternate_style = true } + pymdownx.tabbed = { + alternate_style = true, + } ``` === "`mkdocs.yml`" @@ -701,7 +729,9 @@ prepends the id of the header to the `id` of the tab: ``` toml [project.markdown_extensions] - pymdownx.tabbed = { combine_header_slug = true } + pymdownx.tabbed = { + combine_header_slug = true, + } ``` === "`mkdocs.yml`" @@ -724,10 +754,10 @@ Markdown Extensions][Slugs]. To produce all-lowercase slugs: ``` toml [project.markdown_extensions] pymdownx.tabbed = { - slugify = { - object = "pymdownx.slugs.slugify", - kwds = { case = "lower" }, - }, + slugify = { + object = "pymdownx.slugs.slugify", + kwds.case = "lower", + }, } ``` @@ -748,7 +778,9 @@ In order to retain the case of the input: ``` toml [project.markdown_extensions] pymdownx.tabbed = { - slugify = { object = "pymdownx.slugs.slugify" }, + slugify = { + object = "pymdownx.slugs.slugify" + }, } ``` @@ -780,7 +812,9 @@ conventions. Enable it via: ``` toml [project.markdown_extensions] - pymdownx.tasklist = { custom_checkbox = true } + pymdownx.tasklist = { + custom_checkbox = true, + } ``` === "`mkdocs.yml`" @@ -802,7 +836,9 @@ checkbox styles with beautiful icons, and is therefore recommended: ``` toml [project.markdown_extensions] - pymdownx.tasklist = { custom_checkbox = true } + pymdownx.tasklist = { + custom_checkbox = true, + } ``` === "`mkdocs.yml`" @@ -823,7 +859,9 @@ experience perspective: ``` toml [project.markdown_extensions] - pymdownx.tasklist = { clickable_checkbox = true } + pymdownx.tasklist = { + clickable_checkbox = true, + } ``` === "`mkdocs.yml`" diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index b004ccd..68fe0d9 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -193,7 +193,9 @@ page. Enable it via: ``` toml [project.markdown_extensions] - toc = { permalink = true } + toc = { + permalink = true, + } ``` === "`mkdocs.yml`" @@ -216,7 +218,9 @@ the [site language]. Set the title explicitly via: ``` toml [project.markdown_extensions] - toc = { title = "On this page" } + toc = { + title = "On this page", + } ``` === "`mkdocs.yml`" @@ -241,7 +245,9 @@ or string like so: ``` toml [project.markdown_extensions] - toc = { permalink = "⚓︎" } + toc = { + permalink = "⚓︎", + } ``` === "`mkdocs.yml`" @@ -263,7 +269,9 @@ section itself: ``` toml [project.markdown_extensions] - toc = { permalink_title = "Anchor link to this section" } + toc = { + permalink_title = "Anchor link to this section", + } ``` === "`mkdocs.yml`" @@ -286,10 +294,10 @@ Python Markdown Extensions][Slugs]: ``` toml [project.markdown_extensions] toc = { - slugify = { - object = "pymdownx.slugs.slugify", - kwds = { case = "lower" }, - }, + slugify = { + object = "pymdownx.slugs.slugify", + kwds.case = "lower", + }, } ``` @@ -313,7 +321,9 @@ headings to decrease the length of the table of contents: ``` toml [project.markdown_extensions] - toc = { toc_depth = 3 } + toc = { + toc_depth = 3, + } ``` === "`mkdocs.yml`" @@ -330,7 +340,9 @@ To remove the table of contents altogether: ``` toml [project.markdown_extensions] - toc = { toc_depth = 0 } + toc = { + toc_depth = 0, + } ``` === "`mkdocs.yml`" diff --git a/docs/setup/fonts.md b/docs/setup/fonts.md index 177ca0e..4e6db2f 100644 --- a/docs/setup/fonts.md +++ b/docs/setup/fonts.md @@ -97,7 +97,9 @@ corresponding `@font-face` definition: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/footer.md b/docs/setup/footer.md index e234758..63c0b8f 100644 --- a/docs/setup/footer.md +++ b/docs/setup/footer.md @@ -24,7 +24,7 @@ configuration: ``` toml [project.theme] features = [ - "navigation.footer" + "navigation.footer", ] ``` diff --git a/docs/setup/header.md b/docs/setup/header.md index c15590b..52c0962 100644 --- a/docs/setup/header.md +++ b/docs/setup/header.md @@ -24,7 +24,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "header.autohide" + "header.autohide", ] ``` @@ -63,7 +63,7 @@ your configuration: ``` toml [project.theme] features = [ - "announce.dismiss" + "announce.dismiss", ] ``` diff --git a/docs/setup/language.md b/docs/setup/language.md index 8402bae..5a3452f 100644 --- a/docs/setup/language.md +++ b/docs/setup/language.md @@ -49,8 +49,8 @@ can be defined via configuration: ``` toml [project.extra] alternate = [ - { name = "English", link = "/en/", lang = "en" }, - { name = "Deutsch", link = "/de/", lang = "de" } + { name = "English", link = "/en/", lang = "en" }, + { name = "Deutsch", link = "/de/", lang = "de" }, ] ``` diff --git a/docs/setup/logo-and-icons.md b/docs/setup/logo-and-icons.md index 3233642..fb6a158 100644 --- a/docs/setup/logo-and-icons.md +++ b/docs/setup/logo-and-icons.md @@ -161,9 +161,11 @@ your project documentation. The structure of your project should look like this: [project.markdown_extensions] pymdownx.emoji = { - emoji_index = "zensical.extensions.emoji.twemoji", - emoji_generator = "zensical.extensions.emoji.to_svg", - options.custom_icons = ["overrides/.icons"], + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + options.custom_icons = [ + "overrides/.icons", + ], } ``` diff --git a/docs/setup/navigation.md b/docs/setup/navigation.md index da0870c..832546e 100644 --- a/docs/setup/navigation.md +++ b/docs/setup/navigation.md @@ -35,7 +35,7 @@ the content itself. The paths need to be relative to the [`docs_dir`][docs_dir]. [project] nav = [ "index.md", - "about.md" + "about.md", ] ``` @@ -55,8 +55,8 @@ for a page, you can also explicitly specify a title: ``` toml [project] nav = [ - {"Home" = "index.md"}, - {"About" = "about.md"} + { "Home" = "index.md" }, + { "About" = "about.md" }, ] ``` @@ -78,12 +78,12 @@ your users to the information they require. ``` toml [project] nav = [ - {"Home" = "index.md"}, - {"About" = [ - "about/index.md", - "about/vision.md", - "about/team.md" - ]} + { "Home" = "index.md" }, + { "About" = [ + "about/index.md", + "about/vision.md", + "about/team.md", + ] }, ] ``` @@ -108,7 +108,7 @@ string that cannot be resolved to a Markdown page is treated as a URL. ``` toml [project] nav = [ - {"GitHub Repo" = "https://github.com/zensical/docs"} + { "GitHub Repo" = "https://github.com/zensical/docs" }, ] ``` @@ -133,7 +133,7 @@ the following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.instant" + "navigation.instant", ] ``` @@ -168,8 +168,8 @@ immediately upon navigation. Enable it with: ``` toml [project.theme] features = [ - "navigation.instant", - "navigation.instant.prefetch" + "navigation.instant", + "navigation.instant.prefetch", ] ``` @@ -194,8 +194,8 @@ enable it in your configuration with: ``` toml [project.theme] features = [ - "navigation.instant", - "navigation.instant.progress" + "navigation.instant", + "navigation.instant.progress", ] ``` @@ -246,22 +246,22 @@ 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`" ``` yaml markdown_extensions: - - material.extensions.preview: + - zensical.extensions.preview: configurations: - targets: include: @@ -278,22 +278,26 @@ extensions in the setup guide. === "`zensical.toml`" ``` toml - [project.markdown_extensions.zensical.extensions] - preview = { - configurations = [ - { - sources = { include = [...], exclude = [...] }, # (1)! - targets = { include = [...], exclude = [...] }, # (2)! - }, - ], - } + [project.markdown_extensions] + zensical.extensions.preview.configurations = [ + { + sources = { + include = [], + exclude = [], + }, # (1)! + targets = { + include = [], + exclude = [], + }, # (2)! + }, + ] ``` === "`mkdocs.yml`" ``` yaml markdown_extensions: - - material.extensions.preview: + - zensical.extensions.preview: configurations: - sources: # (1)! include: @@ -339,7 +343,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.tracking" + "navigation.tracking", ] ``` @@ -362,7 +366,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.tabs" + "navigation.tabs", ] ``` @@ -395,8 +399,8 @@ flags to your configuration: ``` toml [project.theme] features = [ - "navigation.tabs", - "navigation.tabs.sticky" + "navigation.tabs", + "navigation.tabs.sticky", ] ``` @@ -420,7 +424,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.sections" + "navigation.sections", ] ``` @@ -457,7 +461,7 @@ Add the following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.expand" + "navigation.expand", ] ``` @@ -491,7 +495,7 @@ your configuration: ``` toml [project.theme] features = [ - "navigation.path" + "navigation.path", ] ``` @@ -524,7 +528,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.prune" # (1)! + "navigation.prune", # (1)! ] ``` @@ -560,7 +564,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.indexes" # (1)! + "navigation.indexes", # (1)! ] ``` @@ -587,13 +591,12 @@ navigation section: ``` toml [project] nav = [ - {"Section" = [ - "section/index.md", # (1)! - {"Page 1" = "section/page-1.md"}, - ... - {"Page n" = "section/page-n.md"} - - ]} + { "Section" = [ + "section/index.md", # (1)! + { "Page 1" = "section/page-1.md" }, + # ... + { "Page n" = "section/page-n.md" }, + ] }, ] ``` @@ -606,7 +609,7 @@ navigation section: - Section: - section/index.md # (1)! - Page 1: section/page-1.md - ... + # ... - Page n: section/page-n.md ``` @@ -625,7 +628,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "toc.follow" + "toc.follow", ] ``` @@ -648,7 +651,7 @@ to your configuration: ``` toml [project.theme] features = [ - "toc.integrate" # (1)! + "toc.integrate", # (1)! ] ``` @@ -689,7 +692,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.top" + "navigation.top", ] ``` @@ -770,7 +773,9 @@ of CSS: ``` toml [project] - extra_css = ["stylesheets/extra.css"] + extra_css = [ + "stylesheets/extra.css", + ] ``` === "`mkdocs.yml`" diff --git a/docs/setup/offline.md b/docs/setup/offline.md index 019976d..cf16d90 100644 --- a/docs/setup/offline.md +++ b/docs/setup/offline.md @@ -82,17 +82,23 @@ in `extra.polyfills`: ``` toml [project.extra] -polyfills = ["js/iframe-worker-shim.js"] +polyfills = [ + "js/iframe-worker-shim.js", +] ``` or ``` toml -[[project.extra.polyfills]] -path = "js/iframe-worker-shim.js" -type = "text/javascript" -async = false -defer = false +[project.extra] +polyfills = [ + { + path = "js/iframe-worker-shim.js", + type = "text/javascript", + async = false, + defer = false, + }, +] ``` Here it is assumed the asset is in a `js/` folder in your configured `docs/` directory: diff --git a/docs/setup/repository.md b/docs/setup/repository.md index f8c1134..08b9430 100644 --- a/docs/setup/repository.md +++ b/docs/setup/repository.md @@ -107,7 +107,7 @@ features: [project.theme] features = [ "content.action.edit", # Edit this page - "content.action.view" # View source of this page + "content.action.view", # View source of this page ] ``` diff --git a/docs/setup/search.md b/docs/setup/search.md index 7ca56e4..deca04f 100644 --- a/docs/setup/search.md +++ b/docs/setup/search.md @@ -44,7 +44,7 @@ Add the following lines to your configuration: ``` toml [project.theme] features = [ - "search.highlight" + "search.highlight", ] ``` diff --git a/docs/setup/versioning.md b/docs/setup/versioning.md index 31443fa..010e650 100644 --- a/docs/setup/versioning.md +++ b/docs/setup/versioning.md @@ -86,7 +86,10 @@ to your configuration: ``` toml [project.extra.version] - default = ["stable", "development"] + default = [ + "stable", + "development", + ] ``` Now every version that has the `stable` and `development` aliases will not