diff --git a/docs/authoring/admonitions.md b/docs/authoring/admonitions.md index 2f2caea..056b3e6 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`" @@ -48,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/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/code-blocks.md b/docs/authoring/code-blocks.md index cb54e80..589038c 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, + } + pymdownx.inlinehilite = {} + pymdownx.snippets = {} + pymdownx.superfences = {} ``` === "`mkdocs.yml`" @@ -64,7 +66,7 @@ your configuration to enable them globally: ``` toml [project.theme] features = [ - "content.code.copy" + "content.code.copy", ] ``` @@ -113,7 +115,7 @@ to your configuration to enable it globally: ``` toml [project.theme] features = [ - "content.code.select" + "content.code.select", ] ``` @@ -159,7 +161,7 @@ your configuration to enable them globally: ``` toml [project.theme] features = [ - "content.code.annotate" # (1)! + "content.code.annotate", # (1)! ] ``` @@ -296,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 @@ -307,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 @@ -505,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`" @@ -531,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`" @@ -559,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 a40f871..c4620bb 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -20,9 +20,11 @@ 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 = {} + pymdownx.tabbed = { + alternate_style = true + } ``` === "`mkdocs.yml`" @@ -68,9 +70,13 @@ 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`" @@ -95,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 f371541..b25dca7 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`" @@ -148,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 63cf72c..9f28e24 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`" @@ -293,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 4fa62ad..cd5e74c 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`" @@ -44,7 +45,7 @@ enabled with: ``` toml [project.theme] features = [ - "content.footnote.tooltips" + "content.footnote.tooltips", ] ``` diff --git a/docs/authoring/formatting.md b/docs/authoring/formatting.md index e6a062c..a4fb023 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 = {} + pymdownx.keys = {} + pymdownx.mark = {} + pymdownx.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..bd1980b 100644 --- a/docs/authoring/icons-emojis.md +++ b/docs/authoring/icons-emojis.md @@ -19,8 +19,12 @@ 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 = { + emoji_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + } ``` === "`mkdocs.yml`" @@ -29,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: @@ -110,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`" @@ -158,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/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..0311ed2 100644 --- a/docs/authoring/lists.md +++ b/docs/authoring/lists.md @@ -20,9 +20,11 @@ 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/math.md b/docs/authoring/math.md index bab3cce..38104f1 100644 --- a/docs/authoring/math.md +++ b/docs/authoring/math.md @@ -57,11 +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 + + [project.markdown_extensions] + pymdownx.arithmatex = { + generic = true, + } ``` === "`mkdocs.yml`" @@ -125,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 + [project.markdown_extensions] + pymdownx.arithmatex = { + generic = true, + } ``` === "`mkdocs.yml`" diff --git a/docs/authoring/tooltips.md b/docs/authoring/tooltips.md index e35fd05..2448958 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`" @@ -52,7 +53,7 @@ lines to your configuration:: ``` toml [project.theme] features = [ - "content.tooltips" + "content.tooltips", ] ``` @@ -153,8 +154,10 @@ 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/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 0d8fa0f..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,47 +72,58 @@ 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`" ``` 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, + } + 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", + } + pymdownx.highlight = { + anchor_linenums = true, + line_spans = "__span", + pygments_lang_class = true, + } + pymdownx.inlinehilite = {} + pymdownx.keys = {} + pymdownx.magiclink = {} + pymdownx.mark = {} + pymdownx.smartsymbols = {} + pymdownx.superfences = { + 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.tilde = {} ``` === "`mkdocs.yml`" @@ -136,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 @@ -172,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 @@ -218,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 14b303e..47740b7 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,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`" @@ -50,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`" @@ -69,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`" @@ -88,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`" @@ -107,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`" @@ -127,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`" @@ -146,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 ff3af97..5248975 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,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`" @@ -63,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`" @@ -83,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`" @@ -119,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`" @@ -138,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`" @@ -157,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`" @@ -176,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`" @@ -195,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`" @@ -214,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`" @@ -233,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`" @@ -252,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`" @@ -271,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`" @@ -290,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`" @@ -309,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 603b84d..f92766d 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..a32c450 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -24,8 +24,10 @@ mathematical typesetting. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.arithmatex] - generic = true + [project.markdown_extensions] + 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", ] ``` @@ -106,7 +108,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`" @@ -129,9 +132,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 = {} + pymdownx.mark = {} + pymdownx.tilde = {} ``` === "`mkdocs.yml`" @@ -161,7 +165,8 @@ user. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.details] + [project.markdown_extensions] + pymdownx.details = {} ``` === "`mkdocs.yml`" @@ -183,9 +188,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_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", # (1)! + } ``` 1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to @@ -215,8 +222,10 @@ 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`" @@ -235,8 +244,10 @@ 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`" @@ -256,10 +267,14 @@ 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_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + options.custom_icons = [ + "overrides/.icons", + ], + } ``` === "`mkdocs.yml`" @@ -267,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 @@ -293,9 +308,11 @@ 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, + } + pymdownx.superfences = {} ``` 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to @@ -326,8 +343,10 @@ 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`" @@ -346,8 +365,10 @@ 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`" @@ -368,8 +389,10 @@ 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`" @@ -390,8 +413,10 @@ 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`" @@ -417,8 +442,10 @@ 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`" @@ -437,8 +464,10 @@ 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`" @@ -470,8 +499,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 = {} + pymdownx.inlinehilite = {} ``` === "`mkdocs.yml`" @@ -499,7 +529,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`" @@ -526,7 +557,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`" @@ -549,7 +581,8 @@ syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.snippets] + [project.markdown_extensions] + pymdownx.snippets = {} ``` === "`mkdocs.yml`" @@ -577,7 +610,8 @@ elements. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.pymdownx.superfences] + [project.markdown_extensions] + pymdownx.superfences = {} ``` === "`mkdocs.yml`" @@ -597,10 +631,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`" @@ -640,8 +680,11 @@ 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, + combine_header_slug = true, + } ``` === "`mkdocs.yml`" @@ -650,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: @@ -662,8 +706,10 @@ 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`" @@ -682,8 +728,10 @@ 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`" @@ -704,9 +752,13 @@ 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`" @@ -724,8 +776,12 @@ 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`" @@ -755,8 +811,10 @@ 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`" @@ -777,8 +835,10 @@ 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`" @@ -798,8 +858,10 @@ 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..68fe0d9 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,10 @@ page. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink = true + [project.markdown_extensions] + toc = { + permalink = true, + } ``` === "`mkdocs.yml`" @@ -209,8 +217,10 @@ 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 +244,10 @@ or string like so: === "`zensical.toml`" ``` toml - [project.markdown_extensions.toc] - permalink = "⚓︎" + [project.markdown_extensions] + toc = { + permalink = "⚓︎", + } ``` === "`mkdocs.yml`" @@ -256,8 +268,10 @@ 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 +292,13 @@ 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 +320,10 @@ 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 +339,10 @@ 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 +367,8 @@ simple syntax. Enable it via: === "`zensical.toml`" ``` toml - [project.markdown_extensions.tables] + [project.markdown_extensions] + tables = {} ``` === "`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 9428164..fb6a158 100644 --- a/docs/setup/logo-and-icons.md +++ b/docs/setup/logo-and-icons.md @@ -159,10 +159,14 @@ 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_generator = "zensical.extensions.emoji.to_svg", + emoji_index = "zensical.extensions.emoji.twemoji", + options.custom_icons = [ + "overrides/.icons", + ], + } ``` === "`mkdocs.yml`" diff --git a/docs/setup/navigation.md b/docs/setup/navigation.md index 2dde032..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,12 +246,14 @@ 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/*", + ] + }, ] ``` @@ -259,7 +261,7 @@ instant previews on a per-page or per-section level for your documentation: ``` yaml markdown_extensions: - - material.extensions.preview: + - zensical.extensions.preview: configurations: - targets: include: @@ -276,18 +278,26 @@ 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`" ``` yaml markdown_extensions: - - material.extensions.preview: + - zensical.extensions.preview: configurations: - sources: # (1)! include: @@ -333,7 +343,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.tracking" + "navigation.tracking", ] ``` @@ -356,7 +366,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.tabs" + "navigation.tabs", ] ``` @@ -389,8 +399,8 @@ flags to your configuration: ``` toml [project.theme] features = [ - "navigation.tabs", - "navigation.tabs.sticky" + "navigation.tabs", + "navigation.tabs.sticky", ] ``` @@ -414,7 +424,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.sections" + "navigation.sections", ] ``` @@ -451,7 +461,7 @@ Add the following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.expand" + "navigation.expand", ] ``` @@ -485,7 +495,7 @@ your configuration: ``` toml [project.theme] features = [ - "navigation.path" + "navigation.path", ] ``` @@ -518,7 +528,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.prune" # (1)! + "navigation.prune", # (1)! ] ``` @@ -554,7 +564,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.indexes" # (1)! + "navigation.indexes", # (1)! ] ``` @@ -581,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" }, + ] }, ] ``` @@ -600,7 +609,7 @@ navigation section: - Section: - section/index.md # (1)! - Page 1: section/page-1.md - ... + # ... - Page n: section/page-n.md ``` @@ -619,7 +628,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "toc.follow" + "toc.follow", ] ``` @@ -642,7 +651,7 @@ to your configuration: ``` toml [project.theme] features = [ - "toc.integrate" # (1)! + "toc.integrate", # (1)! ] ``` @@ -683,7 +692,7 @@ following lines to your configuration: ``` toml [project.theme] features = [ - "navigation.top" + "navigation.top", ] ``` @@ -764,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