From ca5cd9ed112214cb29cf34be7659c1522daf1431 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Thu, 30 Jul 2026 18:44:14 +0200 Subject: [PATCH] refactor: format Markdown with Zensical Studio Signed-off-by: squidfunk --- .editorconfig | 2 + .vscode/settings.json | 4 + docs/authoring/admonitions.md | 23 +-- docs/authoring/buttons.md | 18 +- docs/authoring/code-blocks.md | 99 ++++----- docs/authoring/content-tabs.md | 37 ++-- docs/authoring/data-tables.md | 121 ++++++----- docs/authoring/diagrams.md | 50 ++--- docs/authoring/footnotes.md | 15 +- docs/authoring/formatting.md | 21 +- docs/authoring/frontmatter.md | 31 ++- docs/authoring/grids.md | 100 ++++----- docs/authoring/icons-emojis.md | 44 ++-- docs/authoring/images.md | 48 ++--- docs/authoring/lists.md | 37 ++-- docs/authoring/markdown.md | 33 ++- docs/authoring/math.md | 29 ++- docs/authoring/tooltips.md | 40 ++-- docs/browser-support.md | 41 ++-- docs/community/contribute/code-of-conduct.md | 27 ++- docs/community/contribute/index.md | 63 +++--- docs/community/contribute/pull-requests.md | 92 ++++----- docs/community/contribute/report-a-bug.md | 142 ++++++------- .../contribute/report-a-docs-issue.md | 38 ++-- docs/community/contribute/request-a-change.md | 92 ++++----- docs/community/faqs.md | 90 ++++---- docs/community/get-involved.md | 30 ++- .../community/guides/create-a-reproduction.md | 5 +- docs/community/guides/develop.md | 40 ++-- docs/community/how-we-work.md | 155 +++++++------- docs/create-your-site.md | 54 ++--- docs/customization.md | 96 ++++----- docs/get-started.md | 74 ++++--- docs/publish-your-site.md | 43 ++-- docs/setup/analytics.md | 111 +++++----- docs/setup/basics.md | 60 +++--- docs/setup/colors.md | 54 +++-- docs/setup/comment-system.md | 22 +- docs/setup/data-privacy.md | 66 +++--- docs/setup/extensions/about.md | 73 ++++--- docs/setup/extensions/glightbox.md | 8 +- docs/setup/extensions/macros.md | 125 ++++++----- docs/setup/extensions/markdown-exec.md | 38 ++-- docs/setup/extensions/mkdocstrings.md | 13 +- .../extensions/python-markdown-extensions.md | 181 ++++++++-------- docs/setup/extensions/python-markdown.md | 81 ++++---- docs/setup/fonts.md | 20 +- docs/setup/footer.md | 35 ++-- docs/setup/header.md | 11 +- docs/setup/language.md | 38 ++-- docs/setup/logo-and-icons.md | 72 ++++--- docs/setup/navigation.md | 194 +++++++++--------- docs/setup/offline.md | 21 +- docs/setup/repository.md | 33 ++- docs/setup/search.md | 9 +- docs/setup/social-cards.md | 4 +- docs/setup/tags.md | 21 +- docs/setup/validation.md | 39 ++-- docs/setup/versioning.md | 36 ++-- docs/upgrade.md | 11 +- docs/usage/build.md | 5 +- docs/usage/cli.md | 4 +- docs/usage/new.md | 15 +- docs/usage/preview.md | 8 +- 64 files changed, 1525 insertions(+), 1717 deletions(-) diff --git a/.editorconfig b/.editorconfig index cf4c8f8..3834ff3 100644 --- a/.editorconfig +++ b/.editorconfig @@ -30,3 +30,5 @@ end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true +[*.md] +indent_size = 4 diff --git a/.vscode/settings.json b/.vscode/settings.json index 28e2080..cbb38f3 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,6 +3,10 @@ "docs/**/*.md": "python-markdown", }, "git.ignoreLimitWarning": true, + "[python-markdown]": { + "editor.defaultFormatter": "zensical.zensical-studio", + "editor.formatOnSave": true + }, "search.followSymlinks": false, "typescript.tsdk": "node_modules/typescript/lib", "yaml.schemas": { diff --git a/docs/authoring/admonitions.md b/docs/authoring/admonitions.md index 3dac3ff..2f2caea 100644 --- a/docs/authoring/admonitions.md +++ b/docs/authoring/admonitions.md @@ -39,10 +39,6 @@ See additional configuration options: - [Details] - [SuperFences] - [Admonition]: ../setup/extensions/python-markdown.md#admonition - [Details]: ../setup/extensions/python-markdown-extensions.md#details - [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences - ### Admonition icons Each of the supported admonition types has a distinct icon, which can be changed @@ -76,7 +72,6 @@ lines to your configuration: quote = "octicons/quote-16" ``` - === ":fontawesome-brands-font-awesome: FontAwesome" ``` toml @@ -126,7 +121,6 @@ lines to your configuration: quote: octicons/quote-16 ``` - === ":fontawesome-brands-font-awesome: FontAwesome" ``` yaml @@ -147,8 +141,6 @@ lines to your configuration: quote: fontawesome/solid/quote-left ``` - [custom icon]: ../setup/logo-and-icons.md#additional-icons - ## Usage Admonitions follow a simple syntax: a block starts with `!!!`, followed by a @@ -173,8 +165,6 @@ the next line, indented by four spaces: - [type qualifier]: #supported-types - ### Change the title By default, the title will equal the type qualifier in titlecase. However, it @@ -231,6 +221,7 @@ can use your existing admonitions and indent the desired ones: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. + ### Remove the title @@ -257,9 +248,6 @@ not work for [collapsible blocks]: - [changing the title]: #change-the-title - [collapsible blocks]: #collapsible-blocks - ### Collapsible blocks When [Details] is enabled and an admonition block is started with `???` instead @@ -350,7 +338,7 @@ only the `inline` modifier: Use `inline` to align to the left (right for rtl languages). -__Important__: admonitions that use the `inline` modifiers _must_ be declared +**Important**: admonitions that use the `inline` modifiers _must_ be declared prior to the content block you want to place them beside. If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g., on mobile viewports. @@ -443,3 +431,10 @@ The following admonition types are available in Zensical. The default is `note`. euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. +[Admonition]: ../setup/extensions/python-markdown.md#admonition +[changing the title]: #change-the-title +[collapsible blocks]: #collapsible-blocks +[custom icon]: ../setup/logo-and-icons.md#additional-icons +[Details]: ../setup/extensions/python-markdown-extensions.md#details +[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences +[type qualifier]: #supported-types diff --git a/docs/authoring/buttons.md b/docs/authoring/buttons.md index ff20fb9..9fb6320 100644 --- a/docs/authoring/buttons.md +++ b/docs/authoring/buttons.md @@ -33,8 +33,6 @@ See additional configuration options: - [Attribute Lists] - [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists - ## Usage ### Add a button @@ -53,10 +51,6 @@ In order to render a link as a button, suffix it with curly braces and add the - [primary color]: ../setup/colors.md#primary-color - [accent color]: ../setup/colors.md#accent-color - [Demo]: javascript:alert$.next("Demo") - ### Add a primary button If you want to display a filled, primary button (like on the [landing page] @@ -73,16 +67,11 @@ CSS class selectors. - [landing page]: https://zensical.org - ### Add a button with an icon Of course, icons can be added to all types of buttons by using the [icon syntax] together with any valid [icon shortcode]: - [icon shortcode]: icons-emojis.md#included-icon-sets - [icon syntax]: icons-emojis.md#use-icons - ``` markdown title="Button with icon" [Send :fontawesome-solid-paper-plane:](#){ .md-button } ``` @@ -93,3 +82,10 @@ together with any valid [icon shortcode]: +[accent color]: ../setup/colors.md#accent-color +[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists +[Demo]: javascript:alert$.next("Demo") +[icon shortcode]: icons-emojis.md#included-icon-sets +[icon syntax]: icons-emojis.md#use-icons +[landing page]: https://zensical.org +[primary color]: ../setup/colors.md#primary-color diff --git a/docs/authoring/code-blocks.md b/docs/authoring/code-blocks.md index 0bec324..2c03d42 100644 --- a/docs/authoring/code-blocks.md +++ b/docs/authoring/code-blocks.md @@ -11,8 +11,6 @@ documentation. Zensical provides different ways to set up syntax highlighting for code blocks, either during build time using [Pygments] or during runtime using a JavaScript syntax highlighter. - [Pygments]: https://pygments.org - ## Configuration This configuration enables syntax highlighting on code blocks and inline code @@ -55,11 +53,6 @@ See additional configuration options: - [SuperFences] - [Snippets] - [Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight - [InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite - [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences - [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets - ### Code copy button Code blocks can automatically render a button on the right side to allow the @@ -123,6 +116,7 @@ to your configuration to enable it globally: "content.code.select" ] ``` + === "`mkdocs.yml`" ``` yaml @@ -153,8 +147,6 @@ to your configuration to enable it globally: ``` ```` - [line highlighting]: #highlight-specific-lines - ### Code annotations Code annotations offer a comfortable and friendly way to attach arbitrary @@ -171,9 +163,8 @@ your configuration to enable them globally: ] ``` - 1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted - text__, images, ... basically anything that can be written in Markdown. - + 1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted + text**, images, ... basically anything that can be written in Markdown. === "`mkdocs.yml`" @@ -183,8 +174,8 @@ your configuration to enable them globally: - content.code.annotate # (1)! ``` - 1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted - text__, images, ... basically anything that can be written in Markdown. + 1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted + text**, images, ... basically anything that can be written in Markdown. ??? info "Enabling code annotations for a specific code block" @@ -202,8 +193,6 @@ your configuration to enable them globally: Note that the language shortcode which has to come first must now also be prefixed by a `.`. - [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists - #### Custom selectors Normally, code annotations can only be [placed in comments], as comments can be @@ -220,10 +209,10 @@ Additional selectors can be set per-language: json = [".s2"] # (1)! ``` - 1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for - double-quoted strings. If you want to use a code annotation in another - lexeme than a comment, inspect the code block and determine which lexeme - needs to be added to the list of additional selectors. + 1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for + double-quoted strings. If you want to use a code annotation in another + lexeme than a comment, inspect the code block and determine which lexeme + needs to be added to the list of additional selectors. === "`mkdocs.yml`" @@ -233,10 +222,10 @@ Additional selectors can be set per-language: json: [.s2] # (1)! ``` - 1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for - double-quoted strings. If you want to use a code annotation in another - lexeme than a comment, inspect the code block and determine which lexeme - needs to be added to the list of additional selectors. + 1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for + double-quoted strings. If you want to use a code annotation in another + lexeme than a comment, inspect the code block and determine which lexeme + needs to be added to the list of additional selectors. Now, code annotations can be used from within strings in JSON: @@ -246,11 +235,8 @@ Now, code annotations can be used from within strings in JSON: } ``` -1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted - text__, images, ... basically anything that can be written in Markdown. - - [placed in comments]: #add-annotations - [s2]: https://github.com/zensical/ui/blob/master/src/assets/stylesheets/modern/main/extensions/pymdownx/_highlight.scss +1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted + text**, images, ... basically anything that can be written in Markdown. ## Usage @@ -273,8 +259,6 @@ import tensorflow as tf - [list of available lexers]: https://pygments.org/docs/lexers/ - ### Add a title In order to provide additional context, a custom title can be added to a code @@ -309,13 +293,6 @@ Code annotations can be placed anywhere in a code block where a comment for the language of the block can be placed, e.g. for JavaScript in `#!js // ...` and `#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]: - [^1]: - Code annotations require syntax highlighting with [Pygments] – they're - currently not compatible with JavaScript syntax highlighters, or languages - that do not have comments in their grammar. However, we're actively working - on supporting alternate ways of defining code annotations, allowing to - always place code annotations at the end of lines. - ```` markdown title="Code block with annotation" ``` toml [project.theme] @@ -333,8 +310,8 @@ features = ["content.code.annotate"] # (1)! features = ["content.code.annotate"] # (1)! ``` -1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted - text__, images, ... basically anything that can be written in Markdown. +1. :man_raising_hand: I'm a code annotation! I can contain `code`, **formatted + text**, images, ... basically anything that can be written in Markdown. @@ -357,7 +334,7 @@ simply add an `!` after the closing parenthesis of the code annotation: # (1)! ``` -1. Look ma, less line noise! +1. Look ma, less line noise! @@ -414,7 +391,7 @@ at `1`, regardless of the starting line number specified as part of ````
- + ``` py linenums="1" hl_lines="2 3" def bubble_sort(items): for i in range(len(items)): @@ -422,7 +399,7 @@ at `1`, regardless of the starting line number specified as part of if items[j] > items[j + 1]: items[j], items[j + 1] = items[j + 1], items[j] ``` - +
=== "Line ranges" @@ -438,7 +415,7 @@ at `1`, regardless of the starting line number specified as part of ````
- + ``` py linenums="1" hl_lines="3-5" def bubble_sort(items): for i in range(len(items)): @@ -446,11 +423,9 @@ at `1`, regardless of the starting line number specified as part of if items[j] > items[j + 1]: items[j], items[j + 1] = items[j + 1], items[j] ``` - +
- [Adding line numbers]: #add-line-numbers - ### Highlight inline code blocks When [InlineHilite] is enabled, syntax highlighting can be applied to inline @@ -487,8 +462,6 @@ last 4 years - [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation - ## Customization ### Custom syntax theme @@ -560,6 +533,7 @@ override it as part of your [additional style sheet]: [project] extra_css = ["stylesheets/extra.css"] ``` + === "`mkdocs.yml`" ``` yaml @@ -567,12 +541,6 @@ override it as part of your [additional style sheet]: - stylesheets/extra.css ``` - [colors]: https://github.com/zensical/ui/blob/master/src/assets/stylesheets/modern/main/_colors.scss - [color schemes]: ../setup/colors.md#color-scheme - [types of string tokens]: https://pygments.org/docs/tokens/#literals - [additional style sheet]: ../customization.md#additional-css - [syntax theme definition]: https://github.com/zensical/ui/blob/master/src/assets/stylesheets/modern/main/extensions/pymdownx/_highlight.scss - ### Annotation tooltip width If you have a lot of content hosted inside your code annotations, it can be a @@ -593,6 +561,7 @@ of an [additional style sheet]: [project] extra_css = ["stylesheets/extra.css"] ``` + === "`mkdocs.yml`" ``` yaml @@ -611,3 +580,23 @@ This will render annotations with a larger width: 1. Muuuuuuuuuuuuuuuch more space for content + +[^1]: Code annotations require syntax highlighting with [Pygments] – they're currently not compatible with JavaScript syntax highlighters, or languages that do not have comments in their grammar. However, we're actively working on supporting alternate ways of defining code annotations, allowing to always place code annotations at the end of lines. + +[Adding line numbers]: #add-line-numbers +[additional style sheet]: ../customization.md#additional-css +[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists +[color schemes]: ../setup/colors.md#color-scheme +[colors]: https://github.com/zensical/ui/blob/master/src/assets/stylesheets/modern/main/_colors.scss +[Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight +[InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite +[line highlighting]: #highlight-specific-lines +[list of available lexers]: https://pygments.org/docs/lexers/ +[placed in comments]: #add-annotations +[Pygments]: https://pygments.org +[s2]: https://github.com/zensical/ui/blob/master/src/assets/stylesheets/modern/main/extensions/pymdownx/_highlight.scss +[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets +[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation +[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences +[syntax theme definition]: https://github.com/zensical/ui/blob/master/src/assets/stylesheets/modern/main/extensions/pymdownx/_highlight.scss +[types of string tokens]: https://pygments.org/docs/tokens/#literals diff --git a/docs/authoring/content-tabs.md b/docs/authoring/content-tabs.md index d8a0065..a40f871 100644 --- a/docs/authoring/content-tabs.md +++ b/docs/authoring/content-tabs.md @@ -11,7 +11,6 @@ Sometimes, it's desirable to group alternative content under different tabs, e.g. when describing how to access an API from different languages or environments. Zensical allows for beautiful and functional tabs, grouping code blocks and other content. - ## Configuration This configuration enables content tabs, and allows to nest arbitrary content @@ -40,9 +39,6 @@ See additional configuration options: - [SuperFences] - [Tabbed] - [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences - [Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed - ### Anchor links In order to link to content tabs and share them more easily, an anchor link is @@ -50,12 +46,15 @@ automatically added to each content tab, which you can copy via right click or open in a new tab: === "Open me in a new tab ..." + First tab! === "... or me ..." + Second tab! === "... or even me" + Third tab! You can copy the link of the tab and create a link on the same or any other @@ -86,11 +85,6 @@ function with the following lines: For more information, please [see the extension guide][slugification]. - [first]: #anchor-links-open-me-in-a-new-tab- - [second]: #anchor-links--or-me- - [third]: #anchor-links--or-even-me - [slugification]: ../setup/extensions/python-markdown-extensions.md#slugify - ### Linked content tabs When enabled, all content tabs across the whole documentation site will be @@ -118,8 +112,6 @@ tabs with the same label will be activated when a user clicks a content tab regardless of order inside a container. Moreover, this feature is fully integrated with [instant navigation] and persisted across page loads. - [instant navigation]: ../setup/navigation.md#instant-navigation - ## Usage ### Group code blocks @@ -128,7 +120,7 @@ Code blocks are one of the primary targets to be grouped, and can be considered a special case of content tabs, as tabs with a single code block are always rendered without horizontal spacing: -``` title="Content tabs with code blocks" +```` title="Content tabs with code blocks" === "C" ``` c @@ -150,7 +142,7 @@ rendered without horizontal spacing: return 0; } ``` -``` +````
@@ -202,9 +194,9 @@ by nesting tabs in other blocks: === "Unordered list" - * Sed sagittis eleifend rutrum - * Donec vitae suscipit est - * Nulla tempor lobortis orci + - Sed sagittis eleifend rutrum + - Donec vitae suscipit est + - Nulla tempor lobortis orci === "Ordered list" @@ -220,7 +212,7 @@ When [SuperFences] is enabled, content tabs can contain arbitrary nested content, including further content tabs, and can be nested in other blocks like [admonitions] or blockquotes: -``` title="Content tabs in admonition" +```` title="Content tabs in admonition" !!! example === "Unordered List" @@ -238,7 +230,7 @@ content, including further content tabs, and can be nested in other blocks like 2. Donec vitae suscipit est 3. Nulla tempor lobortis orci ``` -``` +````
@@ -262,4 +254,11 @@ content, including further content tabs, and can be nested in other blocks like
- [admonitions]: admonitions.md +[admonitions]: admonitions.md +[first]: #anchor-links-open-me-in-a-new-tab- +[instant navigation]: ../setup/navigation.md#instant-navigation +[second]: #anchor-links--or-me- +[slugification]: ../setup/extensions/python-markdown-extensions.md#slugify +[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences +[Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed +[third]: #anchor-links--or-even-me diff --git a/docs/authoring/data-tables.md b/docs/authoring/data-tables.md index 1cc0d2f..846c6d9 100644 --- a/docs/authoring/data-tables.md +++ b/docs/authoring/data-tables.md @@ -11,9 +11,6 @@ tabular data in project documentation. Furthermore, customizations like [sortable tables] can be achieved with a third-party library and some [additional JavaScript]. - [sortable tables]: #sortable-tables - [additional JavaScript]: ../customization.md#additional-javascript - ## Configuration This configuration enables Markdown table support, which should normally be @@ -37,8 +34,6 @@ See additional configuration options: - [Tables] - [Tables]: ../setup/extensions/python-markdown.md#tables - ## Usage Data tables can be used at any position in your project documentation and can @@ -46,25 +41,23 @@ contain arbitrary Markdown, including inline code blocks, as well as [icons and emojis]: ``` markdown title="Data table" -| Method | Description | -| ----------- | ------------------------------------ | -| `GET` | :lucide-check: Fetch resource | -| `PUT` | :lucide-check-check: Update resource | -| `DELETE` | :lucide-x: Delete resource | +| Method | Description | +| -------- | ------------------------------------ | +| `GET` | :lucide-check: Fetch resource | +| `PUT` | :lucide-check-check: Update resource | +| `DELETE` | :lucide-x: Delete resource | ```
-| Method | Description | -| ----------- | ------------------------------------ | -| `GET` | :lucide-check: Fetch resource | -| `PUT` | :lucide-check-check: Update resource | -| `DELETE` | :lucide-x: Delete resource | +| Method | Description | +| -------- | ------------------------------------ | +| `GET` | :lucide-check: Fetch resource | +| `PUT` | :lucide-check-check: Update resource | +| `DELETE` | :lucide-x: Delete resource |
- [icons and emojis]: icons-emojis.md - ### Column alignment If you want to align a specific column to the `left`, `center` or `right`, you @@ -74,65 +67,63 @@ and/or end of the divider. === "Left" ``` markdown hl_lines="2" title="Data table, columns aligned to left" - | Method | Description | - | :---------- | :----------------------------------- | - | `GET` | :lucide-check: Fetch resource | - | `PUT` | :lucide-check-check: Update resource | - | `DELETE` | :lucide-x: Delete resource | + | Method | Description | + | :------- | :----------------------------------- | + | `GET` | :lucide-check: Fetch resource | + | `PUT` | :lucide-check-check: Update resource | + | `DELETE` | :lucide-x: Delete resource | ```
- - | Method | Description | - | :---------- | :----------------------------------- | - | `GET` | :lucide-check: Fetch resource | - | `PUT` | :lucide-check-check: Update resource | - | `DELETE` | :lucide-x: Delete resource | - + + | Method | Description | + | :------- | :----------------------------------- | + | `GET` | :lucide-check: Fetch resource | + | `PUT` | :lucide-check-check: Update resource | + | `DELETE` | :lucide-x: Delete resource | +
=== "Center" ``` markdown hl_lines="2" title="Data table, columns centered" - | Method | Description | - | :---------: | :----------------------------------: | - | `GET` | :lucide-check: Fetch resource | - | `PUT` | :lucide-check-check: Update resource | - | `DELETE` | :lucide-x: Delete resource | + | Method | Description | + | :------: | :----------------------------------: | + | `GET` | :lucide-check: Fetch resource | + | `PUT` | :lucide-check-check: Update resource | + | `DELETE` | :lucide-x: Delete resource | ```
- - | Method | Description | - | :---------: | :----------------------------------: | - | `GET` | :lucide-check: Fetch resource | - | `PUT` | :lucide-check-check: Update resource | - | `DELETE` | :lucide-x: Delete resource | - + + | Method | Description | + | :------: | :----------------------------------: | + | `GET` | :lucide-check: Fetch resource | + | `PUT` | :lucide-check-check: Update resource | + | `DELETE` | :lucide-x: Delete resource | +
=== "Right" ``` markdown hl_lines="2" title="Data table, columns aligned to right" - | Method | Description | - | ----------: | -----------------------------------: | - | `GET` | :lucide-check: Fetch resource | - | `PUT` | :lucide-check-check: Update resource | - | `DELETE` | :lucide-x: Delete resource | + | Method | Description | + | -------: | -----------------------------------: | + | `GET` | :lucide-check: Fetch resource | + | `PUT` | :lucide-check-check: Update resource | + | `DELETE` | :lucide-x: Delete resource | ```
- - | Method | Description | - | ----------: | -----------------------------------: | - | `GET` | :lucide-check: Fetch resource | - | `PUT` | :lucide-check-check: Update resource | - | `DELETE` | :lucide-x: Delete resource | - + + | Method | Description | + | -------: | -----------------------------------: | + | `GET` | :lucide-check: Fetch resource | + | `PUT` | :lucide-check-check: Update resource | + | `DELETE` | :lucide-x: Delete resource | +
- [regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables - ## Customization ### Sortable tables @@ -183,11 +174,11 @@ column:
-| Method | Description | -| ----------- | ------------------------------------ | -| `GET` | :material-check: Fetch resource | -| `PUT` | :material-check-all: Update resource | -| `DELETE` | :material-close: Delete resource | +| Method | Description | +| -------- | ------------------------------------ | +| `GET` | :material-check: Fetch resource | +| `PUT` | :material-check-all: Update resource | +| `DELETE` | :material-close: Delete resource |
@@ -196,10 +187,16 @@ numbers, filesizes, dates and month names. See the [tablesort documentation] [tablesort] for more information. + - [tablesort]: https://tristen.ca/tablesort/demo/ - [instant navigation]: ../setup/navigation.md#instant-navigation +[additional JavaScript]: ../customization.md#additional-javascript +[icons and emojis]: icons-emojis.md +[instant navigation]: ../setup/navigation.md#instant-navigation +[regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables +[sortable tables]: #sortable-tables +[Tables]: ../setup/extensions/python-markdown.md#tables +[tablesort]: https://tristen.ca/tablesort/demo/ diff --git a/docs/authoring/diagrams.md b/docs/authoring/diagrams.md index 8acbbf5..63cf72c 100644 --- a/docs/authoring/diagrams.md +++ b/docs/authoring/diagrams.md @@ -12,8 +12,6 @@ different technical components, and are a great addition to project documentation. Zensical integrates with [Mermaid.js], a very popular and flexible solution for drawing diagrams. - [Mermaid.js]: https://mermaid.js.org/ - ## Configuration This configuration enables native support for [Mermaid.js] diagrams. Zensical @@ -47,17 +45,6 @@ No further configuration is necessary. Advantages over a custom integration: - [x] Fonts and colors can be customized with [additional style sheets] - [x] Support for both, light and dark color schemes – _try it on this page!_ - [^1]: - While all [Mermaid.js] features should work out-of-the-box, Zensical - will currently only adjust the fonts and colors for flowcharts, - sequence diagrams, class diagrams, state diagrams and entity relationship - diagrams. See the section on [other diagrams] for more information why this - is currently not implemented for all diagrams. - - [instant navigation]: ../setup/navigation.md#instant-navigation - [additional style sheets]: ../customization.md#additional-css - [other diagrams]: #other-diagram-types - ## Usage ### Use flowcharts @@ -90,8 +77,6 @@ graph LR
- [Flowcharts]: https://mermaid.js.org/syntax/flowchart.html - ### Use sequence diagrams [Sequence diagrams] describe a specific scenario as sequential interactions @@ -130,8 +115,6 @@ sequenceDiagram - [Sequence diagrams]: https://mermaid.js.org/syntax/sequenceDiagram.html - ### Use state diagrams [State diagrams] are a great tool to describe the behavior of a system, @@ -172,8 +155,6 @@ stateDiagram-v2 - [State diagrams]: https://mermaid.js.org/syntax/stateDiagram.html - ### Use class diagrams [Class diagrams] are central to object oriented programming, describing the @@ -244,8 +225,6 @@ classDiagram - [Class diagrams]: https://mermaid.js.org/syntax/classDiagram.html - ### Use entity-relationship diagrams An [entity-relationship diagram] is composed of entity types and specifies @@ -280,8 +259,6 @@ erDiagram - [entity-relationship diagram]: https://mermaid.js.org/syntax/entityRelationshipDiagram.html - ### Other diagram types Besides the diagram types listed above, [Mermaid.js] provides support for [pie @@ -290,12 +267,6 @@ diagrams], all of which are not officially supported by Zensical. Those diagrams should still work as advertised by [Mermaid.js], but we don't consider them a good choice, mostly as they don't work well on mobile. - [pie charts]: https://mermaid.js.org/syntax/pie.html - [gantt charts]: https://mermaid.js.org/syntax/gantt.html - [user journeys]: https://mermaid.js.org/syntax/userJourney.html - [git graphs]: https://mermaid.js.org/syntax/gitgraph.html - [requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html - ## Customization If you want to customize Mermaid.js, e.g. to bring in support for [ELK layouts], @@ -319,14 +290,33 @@ you can do so by adding a custom JavaScript file to your configuration: ``` === "`zensical.toml`" + ``` toml [project] extra_javascript = ["javascripts/mermaid.mjs"] ``` + === "`mkdocs.yml`" + ``` yaml extra_javascript: - javascripts/mermaid.mjs ``` - [ELK layouts]: https://www.npmjs.com/package/@mermaid-js/layout-elk +[^1]: While all [Mermaid.js] features should work out-of-the-box, Zensical will currently only adjust the fonts and colors for flowcharts, sequence diagrams, class diagrams, state diagrams and entity relationship diagrams. See the section on [other diagrams] for more information why this is currently not implemented for all diagrams. + +[additional style sheets]: ../customization.md#additional-css +[Class diagrams]: https://mermaid.js.org/syntax/classDiagram.html +[ELK layouts]: https://www.npmjs.com/package/@mermaid-js/layout-elk +[entity-relationship diagram]: https://mermaid.js.org/syntax/entityRelationshipDiagram.html +[Flowcharts]: https://mermaid.js.org/syntax/flowchart.html +[gantt charts]: https://mermaid.js.org/syntax/gantt.html +[git graphs]: https://mermaid.js.org/syntax/gitgraph.html +[instant navigation]: ../setup/navigation.md#instant-navigation +[Mermaid.js]: https://mermaid.js.org/ +[other diagrams]: #other-diagram-types +[pie charts]: https://mermaid.js.org/syntax/pie.html +[requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html +[Sequence diagrams]: https://mermaid.js.org/syntax/sequenceDiagram.html +[State diagrams]: https://mermaid.js.org/syntax/stateDiagram.html +[user journeys]: https://mermaid.js.org/syntax/userJourney.html diff --git a/docs/authoring/footnotes.md b/docs/authoring/footnotes.md index b567ecc..4fa62ad 100644 --- a/docs/authoring/footnotes.md +++ b/docs/authoring/footnotes.md @@ -33,11 +33,8 @@ See additional configuration options: - [Footnotes] - [Footnotes]: ../setup/extensions/python-markdown.md#footnotes - ### Footnote tooltips - Zensical can render footnotes as inline tooltips, so the user can read the footnote without leaving the context of the document. Footnote tooltips can be enabled with: @@ -59,7 +56,7 @@ enabled with: - content.footnote.tooltips ``` -__Footnote tooltips are enabled on our documentation__, so to try it out, you +**Footnote tooltips are enabled on our documentation**, so to try it out, you can just hover or focus any footnote on this page or any other page of our documentation. @@ -102,8 +99,6 @@ Short footnotes can be written on the same line: - [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. - #### on multiple lines Paragraphs can be written on the next line and must be indented by four spaces: @@ -121,7 +116,7 @@ Paragraphs can be written on the next line and must be indented by four spaces: -[^2]: - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus - auctor massa, nec semper lorem quam in massa. +[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. +[^2]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. + +[Footnotes]: ../setup/extensions/python-markdown.md#footnotes diff --git a/docs/authoring/formatting.md b/docs/authoring/formatting.md index c259b12..e6a062c 100644 --- a/docs/authoring/formatting.md +++ b/docs/authoring/formatting.md @@ -39,9 +39,6 @@ See additional configuration options: - [Caret, Mark & Tilde] - [Keys] - [Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde - [Keys]: ../setup/extensions/python-markdown-extensions.md#keys - ## Usage ### Highlight text @@ -64,10 +61,6 @@ syntax, which is more convenient that directly using the corresponding - [mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark - [ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins - [del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del - ### Sub- and superscripts { #sub-and-superscripts } When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and @@ -86,9 +79,6 @@ using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags: - [sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub - [sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup - ### Add keyboard keys When [Keys] is enabled, keyboard keys can be rendered with a simple syntax. @@ -105,6 +95,13 @@ available shortcodes: ----- +--- - [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index +[Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde +[del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del +[ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins +[Keys]: ../setup/extensions/python-markdown-extensions.md#keys +[mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark +[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index +[sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub +[sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup diff --git a/docs/authoring/frontmatter.md b/docs/authoring/frontmatter.md index 2159acd..bda9962 100644 --- a/docs/authoring/frontmatter.md +++ b/docs/authoring/frontmatter.md @@ -52,8 +52,6 @@ icon: lucide/braces ... ``` -[included icon sets]: icons-emojis.md#included-icon-sets - ## Page status A status can be assigned to each page, which is then displayed as part of the @@ -76,8 +74,8 @@ adding the following to your configuration:: ``` The identifier can only include alphanumeric characters, as well as dashes - and underscores. For example, if you have a status `Recently added`, you can - set `new` as an identifier: +and underscores. For example, if you have a status `Recently added`, you can +set `new` as an identifier: === "`zensical.toml`" @@ -85,6 +83,7 @@ The identifier can only include alphanumeric characters, as well as dashes [project.extra.status] new = "Recently added" ``` + === "`mkdocs.yml`" ``` yaml @@ -115,8 +114,6 @@ You can define a custom page status this way but if you want it to have an icon other than the default one you need to also configure that in your [`extra.css`][extra_css]. -[extra_css]: ../customization.md#additional-css - ## Page template You can use the `template` metadata attribute to set a [custom template] for a @@ -124,9 +121,6 @@ page, which will be used instead of the default `main.html`. Note that you need to place the template you want to use in your [overrides directory], which needs to be configured before you can use it. -[custom template]: ../customization.md#custom-templates -[overrides directory]: ../customization.md#configuring-overrides - For example, to apply the `my_homepage.html` template to the page: ``` yaml @@ -157,12 +151,8 @@ hide: See the section on [hiding sidebars] in the navigation setup guide for more details. -[hiding sidebars]: ../setup/navigation.md#hide-the-sidebars - For more information about controlling search, see the [setup guide for search]. - [setup guide for search]: ../setup/search.md - ## Customization ### Use in templates @@ -172,11 +162,6 @@ overrides] or [custom templates]. A common use case is to add metadata to the HTML `head`. Say you want to control whether a page is indexed by search engines by adding a [meta robots `nofollow` tag][nofollow]. -[template overrides]: ../customization.md#template-overrides -[custom templates]: ../customization.md#custom-templates -[nofollow]: https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag -[block override]: ../customization.md#overriding-blocks - The first thing you would need to do is to copy `main.html` to your [overrides directory] and add a [block override] for the `extrahead` block that adds a robots meta tag: @@ -213,4 +198,14 @@ blog plugin also make extensive use of page metadata. As Zensical approaches [feature parity] with Material for MkDocs, we will be adding modules that implement equivalent functionality and that make use of metadata. +[block override]: ../customization.md#overriding-blocks +[custom template]: ../customization.md#custom-templates +[custom templates]: ../customization.md#custom-templates +[extra_css]: ../customization.md#additional-css [feature parity]: https://zensical.org/about/roadmap/#feature-parity +[hiding sidebars]: ../setup/navigation.md#hide-the-sidebars +[included icon sets]: icons-emojis.md#included-icon-sets +[nofollow]: https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag +[overrides directory]: ../customization.md#configuring-overrides +[setup guide for search]: ../setup/search.md +[template overrides]: ../customization.md#template-overrides diff --git a/docs/authoring/grids.md b/docs/authoring/grids.md index d67200d..83c554e 100644 --- a/docs/authoring/grids.md +++ b/docs/authoring/grids.md @@ -41,29 +41,18 @@ See additional configuration options: - [Attribute Lists] - [Markdown in HTML] - [icons and emojis]: icons-emojis.md - [configured separately]: icons-emojis.md#configuration - [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists - [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html - ## Usage Grids come in two flavors: [card grids], which wrap each element in a card that levitates on hover, and [generic grids], which allow to arrange arbitrary block elements in a rectangular shape. - [card grids]: #use-card-grids - [generic grids]: #use-generic-grids - ### Use card grids Card grids wrap each grid item with a beautiful hover card that levitates on hover. They come in two slightly different syntaxes: [list] and [block syntax], adding support for distinct use cases. - [list]: #list-syntax - [block syntax]: #block-syntax - #### List syntax The list syntax is essentially a shortcut for [card grids], and consists of an @@ -82,14 +71,16 @@ classes: ```
-
- -- :fontawesome-brands-html5: __HTML__ for content and structure -- :fontawesome-brands-js: __JavaScript__ for interactivity -- :fontawesome-brands-css3: __CSS__ for text running out of boxes -- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh? +
+ +- :fontawesome-brands-html5: **HTML** for content and structure +- :fontawesome-brands-js: **JavaScript** for interactivity +- :fontawesome-brands-css3: **CSS** for text running out of boxes +- :fontawesome-brands-internet-explorer: **Internet Explorer** ... huh? +
+
List elements can contain arbitrary Markdown, as long as the surrounding `div` @@ -136,9 +127,10 @@ includes icons and links: ```
-
-- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__ +
+ +- :material-clock-fast:{ .lg .middle } **Set up in 5 minutes** --- @@ -147,7 +139,7 @@ includes icons and links: [:octicons-arrow-right-24: Getting started][getting started] -- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__ +- :fontawesome-brands-markdown:{ .lg .middle } **It's just Markdown** --- @@ -155,7 +147,7 @@ includes icons and links: [:octicons-arrow-right-24: Authoring][authoring] -- :material-format-font:{ .lg .middle } __Made to measure__ +- :material-format-font:{ .lg .middle } **Made to measure** --- @@ -163,15 +155,16 @@ includes icons and links: [:octicons-arrow-right-24: Customization][customization] -- :material-scale-balance:{ .lg .middle } __Open Source, MIT__ +- :material-scale-balance:{ .lg .middle } **Open Source, MIT** --- Zensical is licensed under MIT and available on [GitHub] [:octicons-arrow-right-24: License][license] - +
+
If there's insufficient space to render grid items next to each other, the items @@ -179,19 +172,10 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. If there's more space available, grids will render in items of 3 and more, e.g. when [hiding both sidebars]. - [zensical]: https://zensical.org - [pip]: ../get-started.md#install-with-pip - [getting started]: ../get-started.md - [authoring]: markdown.md - [customization]: ../customization.md - [license]: ../license.md - [GitHub]: https://github.com/zensical/zensical - [hiding both sidebars]: ../setup/navigation.md#hide-the-sidebars - #### Block syntax -The block syntax allows for arranging cards in grids __together with other -elements__, as explained in the section on [generic grids]. Just add the `card` +The block syntax allows for arranging cards in grids **together with other +elements**, as explained in the section on [generic grids]. Just add the `card` class to any block element inside a `grid`: ``` html title="Card grid, blocks" @@ -212,20 +196,22 @@ class to any block element inside a `grid`: ```
-
-:fontawesome-brands-html5: __HTML__ for content and structure +
+ +:fontawesome-brands-html5: **HTML** for content and structure { .card } -:fontawesome-brands-js: __JavaScript__ for interactivity +:fontawesome-brands-js: **JavaScript** for interactivity { .card } -:fontawesome-brands-css3: __CSS__ for text running out of boxes +:fontawesome-brands-css3: **CSS** for text running out of boxes { .card } -> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh? - +> :fontawesome-brands-internet-explorer: **Internet Explorer** ... huh? +
+
While this syntax may seem unnecessarily verbose at first, the previous example @@ -271,13 +257,14 @@ by using a `div` with the `grid` class: ````
-
+
+ === "Unordered list" - * Sed sagittis eleifend rutrum - * Donec vitae suscipit est - * Nulla tempor lobortis orci + - Sed sagittis eleifend rutrum + - Donec vitae suscipit est + - Nulla tempor lobortis orci === "Ordered list" @@ -298,10 +285,27 @@ by using a `div` with the `grid` class: 2. Donec vitae suscipit est 3. Nulla tempor lobortis orci ``` - +
+
- [admonitions]: admonitions.md - [code blocks]: code-blocks.md - [content tabs]: content-tabs.md +[admonitions]: admonitions.md +[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists +[authoring]: markdown.md +[block syntax]: #block-syntax +[card grids]: #use-card-grids +[code blocks]: code-blocks.md +[configured separately]: icons-emojis.md#configuration +[content tabs]: content-tabs.md +[customization]: ../customization.md +[generic grids]: #use-generic-grids +[getting started]: ../get-started.md +[GitHub]: https://github.com/zensical/zensical +[hiding both sidebars]: ../setup/navigation.md#hide-the-sidebars +[icons and emojis]: icons-emojis.md +[license]: ../license.md +[list]: #list-syntax +[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html +[pip]: ../get-started.md#install-with-pip +[zensical]: https://zensical.org diff --git a/docs/authoring/icons-emojis.md b/docs/authoring/icons-emojis.md index bcf5718..32306cb 100644 --- a/docs/authoring/icons-emojis.md +++ b/docs/authoring/icons-emojis.md @@ -11,8 +11,6 @@ icons and thousands of emojis in your project documentation with practically zero additional effort. Moreover, [custom icons can be added] and used in your configuration, documents and templates. - [custom icons can be added]: ../setup/logo-and-icons.md#additional-icons - ## Configuration This configuration enables the use of icons and emojis by using simple @@ -41,15 +39,6 @@ See additional configuration options: - [Emoji] - [Emoji with custom icons] - [Lucide]: https://lucide.dev/ - [Material Design]: https://pictogrammers.com/library/mdi/ - [FontAwesome]: https://fontawesome.com/search?m=free - [Octicons]: https://octicons.github.com/ - [Simple Icons]: https://simpleicons.org/ - [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists - [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji - [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom_icons - ## Included icon sets The following icon sets are bundled with Zensical (links lead to search page for @@ -63,8 +52,6 @@ each): Note that you are not limited to these icons as you can [add your own icons]. - [add your own icons]: ../setup/logo-and-icons.md#additional-icons - ## Usage ### Use emojis @@ -82,8 +69,6 @@ the shortcodes at [Emojipedia]: :smile:
- [Twemoji]: https://github.com/jdecked/twemoji - [Emojipedia]: https://emojipedia.org/twitter/ ### Use icons @@ -101,8 +86,6 @@ a valid path to any icon bundled with the theme, which are located in the
- [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons - #### with colors When [Attribute Lists] is enabled, custom CSS classes can be added to icons. @@ -149,8 +132,6 @@ After applying the customization, add the CSS class to the icon shortcode:
- [additional style sheet]: ../customization.md#additional-css - #### with animations Similar to adding [colors], it's just as easy to add [animations] to icons by @@ -199,9 +180,6 @@ After applying the customization, add the CSS class to the icon shortcode:
- [colors]: #with-colors - [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation - ## Customization ### Use icons in templates @@ -218,6 +196,22 @@ wrap it with the `.twemoji` CSS class: This is exactly what Zensical does in its templates. - [extending the theme]: ../customization.md#extending-the-theme - [available icon]: #included-icon-sets - [include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include +[add your own icons]: ../setup/logo-and-icons.md#additional-icons +[additional style sheet]: ../customization.md#additional-css +[animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation +[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists +[available icon]: #included-icon-sets +[colors]: #with-colors +[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons +[custom icons can be added]: ../setup/logo-and-icons.md#additional-icons +[Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji +[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom_icons +[Emojipedia]: https://emojipedia.org/twitter/ +[extending the theme]: ../customization.md#extending-the-theme +[FontAwesome]: https://fontawesome.com/search?m=free +[include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include +[Lucide]: https://lucide.dev/ +[Material Design]: https://pictogrammers.com/library/mdi/ +[Octicons]: https://octicons.github.com/ +[Simple Icons]: https://simpleicons.org/ +[Twemoji]: https://github.com/jdecked/twemoji diff --git a/docs/authoring/images.md b/docs/authoring/images.md index 5320337..ffcdde5 100644 --- a/docs/authoring/images.md +++ b/docs/authoring/images.md @@ -39,10 +39,6 @@ See additional configuration options: - [Markdown in HTML] - [Caption] - [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists - [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html - [Caption]: ../setup/extensions/python-markdown-extensions.md#caption - ## Usage ### Image alignment @@ -58,13 +54,13 @@ respective alignment directions via the `align` attribute, i.e. `align=left` or ```
- + ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–){ align=left width=300 } Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. - +
=== "Right" @@ -74,13 +70,13 @@ respective alignment directions via the `align` attribute, i.e. `align=left` or ```
- + ![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–){ align=right width=300 } Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. - +
If there's insufficient space to render the text next to the image, the image @@ -92,17 +88,6 @@ will stretch to the full width of the viewport, e.g. on mobile viewports. is why this option is not supported by Zensical.[^1] Instead, the [image captions] syntax can be used, as captions are optional. - [^1]: - You might also realize that the [`align`][align] attribute has been - deprecated as of HTML5, so why use it anyways? The main reason is - portability – it's still supported by all browsers and clients, and is very - unlikely to be completely removed, as many older websites still use it. This - ensures a consistent appearance when a Markdown file with these attributes - is viewed outside of a website generated by Zensical. - - [align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes - [image captions]: #image-captions - ### Image captions Sadly, the Markdown syntax doesn't provide native support for image captions, @@ -143,12 +128,10 @@ browsers without support: ![Image title](https://dummyimage.com/600x400/){ loading=lazy } ``` -
+
placeholder image
- [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr - ### Light and dark mode If you added a [color palette toggle] and want to show different images for @@ -195,16 +178,23 @@ hash fragment to the image URL: Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the name of your scheme. - [color palette toggle]: ../setup/colors.md#color-palette-toggle - [Zelda light world]: ../assets/images/zelda-light-world.png#only-light - [Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark - [color schemes]: ../setup/colors.md#color-scheme - [custom color schemes]: ../setup/colors.md#custom-color-schemes - ### Lightbox and zoom Zensical includes the [GLightbox] extension, which adds lightbox galleries. When enabled, clicking on an image opens it in a full-screen overlay with navigation and zoom controls. To enable lightbox for your images, see the [GLightbox] setup guide. - [GLightbox]: ../setup/extensions/glightbox.md +[^1]: You might also realize that the [`align`][align] attribute has been deprecated as of HTML5, so why use it anyways? The main reason is portability – it's still supported by all browsers and clients, and is very unlikely to be completely removed, as many older websites still use it. This ensures a consistent appearance when a Markdown file with these attributes is viewed outside of a website generated by Zensical. + +[align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes +[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists +[Caption]: ../setup/extensions/python-markdown-extensions.md#caption +[color palette toggle]: ../setup/colors.md#color-palette-toggle +[color schemes]: ../setup/colors.md#color-scheme +[custom color schemes]: ../setup/colors.md#custom-color-schemes +[GLightbox]: ../setup/extensions/glightbox.md +[image captions]: #image-captions +[lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr +[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html +[Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark +[Zelda light world]: ../assets/images/zelda-light-world.png#only-light diff --git a/docs/authoring/lists.md b/docs/authoring/lists.md index 93c334c..dbc0425 100644 --- a/docs/authoring/lists.md +++ b/docs/authoring/lists.md @@ -17,7 +17,6 @@ This configuration enables the use of definition lists and tasks lists, which are both not part of the standard Markdown syntax. Add the following lines to your configuration: - === "`zensical.toml`" ``` toml @@ -40,9 +39,6 @@ See additional configuration options: - [Definition Lists] - [Tasklist] - [Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists - [Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist - ## Usage ### Use unordered lists @@ -63,13 +59,13 @@ of lists can be nested inside each other:
-- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur - accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh - lacinia sed. Aenean in finibus diam. +- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur + accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh + lacinia sed. Aenean in finibus diam. - * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. - * Nam vulputate tincidunt fringilla. - * Nullam dignissim ultrices urna non auctor. + - Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. + - Nam vulputate tincidunt fringilla. + - Nullam dignissim ultrices urna non auctor.
@@ -109,9 +105,9 @@ be re-numbered when rendered: 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. - 1. Mauris dictum mi lacus - 2. Ut sit amet placerat ante - 3. Suspendisse ac eros arcu + 1. Mauris dictum mi lacus + 2. Ut sit amet placerat ante + 3. Suspendisse ac eros arcu
@@ -171,13 +167,16 @@ for the definition of task lists:
-- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit -- [ ] Vestibulum convallis sit amet nisi a tincidunt - * [x] In hac habitasse platea dictumst - * [x] In scelerisque nibh non dolor mollis congue sed et metus - * [ ] Praesent sed risus massa -- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque +- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit +- [ ] Vestibulum convallis sit amet nisi a tincidunt + - [x] In hac habitasse platea dictumst + - [x] In scelerisque nibh non dolor mollis congue sed et metus + - [ ] Praesent sed risus massa +- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
--- + +[Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists +[Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist diff --git a/docs/authoring/markdown.md b/docs/authoring/markdown.md index 20d1169..1ad9708 100644 --- a/docs/authoring/markdown.md +++ b/docs/authoring/markdown.md @@ -18,9 +18,8 @@ Gruber's original Markdown syntax][gruber]. For the most part, it is fully compa with the original specification, supporting the core features like headings, lists, links, blockquotes, and inline formatting (e.g., bold and italics). -[gruber]: https://daringfireball.net/projects/markdown/ - !!! note "Differences between Markdown dialects" + There are [differences] in how implementers of Markdown have interpreted the original specification. @@ -33,9 +32,6 @@ lists, links, blockquotes, and inline formatting (e.g., bold and italics). list symbol changes, for example, from "*" to "-". CommonMark, for example, would [start a new list]. -[differences]: https://python-markdown.github.io/#differences -[start a new list]: https://spec.commonmark.org/0.31.2/#lists - !!! warning "README files" `README.md` files in the `docs_dir` are converted to `index.html` just @@ -43,8 +39,6 @@ lists, links, blockquotes, and inline formatting (e.g., bold and italics). in a directory the behavior is currently undefined, so it is better to avoid having both. We have a [backlog item][bl_readme] to review this. -[bl_readme]: https://github.com/zensical/backlog/issues/135 - Both Python Markdown itself and the [Python Markdown Extensions] that Zensical also supports provide extensions to the core Markdown language to cater for the needs of technical writers who want to produce clear, compelling, and visually @@ -54,12 +48,8 @@ Supporting the same syntax for content is a key component in our approach to ensure compatibility with Material for MkDocs and to then evolve Zensical from that point of departure. See [our roadmap] and [compatibility pages] for details. -[Python Markdown]: https://python-markdown.github.io/ -[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/ -[our roadmap]: https://zensical.org/about/roadmap/ -[compatibility pages]: https://zensical.org/compatibility/ - !!! info "Future development" + We are currently actively exploring the possibility of adding support for [CommonMark] with GitHub-flavored Markdown extensions as well as extended authoring options using a component system. @@ -72,16 +62,12 @@ that point of departure. See [our roadmap] and [compatibility pages] for details to CommonMark when Zensical's support for it has matured and when your team is ready to migrate. -[CommonMark]: https://commonmark.org/ - ## Learning Markdown The [original description of Markdown][gruber] by John Gruber is still a good starting point if you are unfamiliar with Markdown syntax. The [Markdown Guide] is another great resource. -[Markdown Guide]: https://www.markdownguide.org/ - ## Linking between pages When adding links to other pages always use related links to the corresponding @@ -90,8 +76,6 @@ will translate them to the correct links to the target. Crucially, it will produce the correct link to an HTML file or a link ending with a directory if [`use_directory_urls`][dirurls] is being used. -[dirurls]: ../setup/basics.md#use_directory_urls - In the future, Zensical will support output formats other than HTML and when this happens, links that point to the Markdown pages will still work, while links entered into the content that point directly to a HTML page will not. @@ -125,4 +109,15 @@ fallback. We're currently redesigning navigation, and will address this issue as part of that work. [ZAP 001] outlines behavior of page titles and their use cases. In particular, we are looking to preserve markup in the title, which MkDocs strips out. Any re-design will include migration paths that avoid costly re-work. - [ZAP 001]: https://zensical.org/spark/proposals/zap-001-page-titles/ +[bl_readme]: https://github.com/zensical/backlog/issues/135 +[CommonMark]: https://commonmark.org/ +[compatibility pages]: https://zensical.org/compatibility/ +[differences]: https://python-markdown.github.io/#differences +[dirurls]: ../setup/basics.md#use_directory_urls +[gruber]: https://daringfireball.net/projects/markdown/ +[Markdown Guide]: https://www.markdownguide.org/ +[our roadmap]: https://zensical.org/about/roadmap/ +[Python Markdown]: https://python-markdown.github.io/ +[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/ +[start a new list]: https://spec.commonmark.org/0.31.2/#lists +[ZAP 001]: https://zensical.org/spark/proposals/zap-001-page-titles/ diff --git a/docs/authoring/math.md b/docs/authoring/math.md index b3d74d0..bab3cce 100644 --- a/docs/authoring/math.md +++ b/docs/authoring/math.md @@ -12,13 +12,6 @@ content in browsers. Although both libraries offer similar functionality, they use different syntaxes and have different configuration options. This page provides information on how to integrate them with Zensical. - [MathJax]: https://www.mathjax.org/ - [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics - [MathML]: https://en.wikipedia.org/wiki/MathML - [AsciiMath]: https://asciimath.org/ - [KaTeX]: https://katex.org/ - - ## Configuration ### MathJax @@ -87,10 +80,8 @@ See additional configuration options: - [Arithmatex] - [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex - [instant navigation]: ../setup/navigation.md#instant-navigation - + ``` - 1. As an example, this variable receives the value set in `mkdocs.yml`, - which is `"foobar"` for `property`. - 2. If you're using [instant navigation], you can use the `location$` - observable to listen for navigation events, which always emits the - current `URL`. + 1. As an example, this variable receives the value set in `mkdocs.yml`, + which is `"foobar"` for `property`. + 2. If you're using [instant navigation], you can use the `location$` + observable to listen for navigation events, which always emits the + current `URL`. === "`zensical.toml`" + ``` toml [project.extra.analytics] provider = "custom" property = "foobar" ``` + === "`mkdocs.yml`" ``` yaml @@ -288,9 +271,6 @@ You can add arbitrary key-value combinations to configure your custom integration. This is especially useful if you're sharing the custom integration across multiple repositories. -[theme extension]: ../customization.md#extending-the-theme -[instant navigation]: navigation.md#instant-navigation - ### Custom site feedback A custom feedback widget integration just needs to process the events that are @@ -325,20 +305,21 @@ generated by users interacting with the feedback widget with the help of some } ``` - 1. The feedback widget is hidden by default so that it does not appear when - people have JavaScript turned off. So, it needs to be turned on here. + 1. The feedback widget is hidden by default so that it does not appear when + people have JavaScript turned off. So, it needs to be turned on here. - 2. Retrieve page and feedback value. + 2. Retrieve page and feedback value. - 3. Replace this with the code that sends the data off to your analytics - provider. + 3. Replace this with the code that sends the data off to your analytics + provider. - 4. Disable the form after submission. + 4. Disable the form after submission. - 5. Show the configured notes. Which one is shown depends on the user - feedback. + 5. Show the configured notes. Which one is shown depends on the user + feedback. === "`zensical.toml`" + ``` toml [project] extra_javascript = ["javascripts/feedback.js"] @@ -354,4 +335,18 @@ generated by users interacting with the feedback widget with the help of some   { #feedback style="margin: 0; height: 0" } - [additional JavaScript]: ../customization.md#additional-javascript +[^3]: Note that for Google Analytics, the data value must be an integer. + +[additional JavaScript]: ../customization.md#additional-javascript +[analytics]: #google-analytics +[cookie consent]: data-privacy.md#cookie-consent +[custom feedback integration]: #custom-site-feedback +[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons +[feedback widget]: #feedback +[Google Analytics]: https://developers.google.com/analytics +[Google Forms]: https://www.google.com/forms/about/ +[instant navigation]: navigation.md#instant-navigation +[newsletter]: https://zensical.org/about/newsletter/ +[site search]: search.md +[theme extension]: ../customization.md#extending-the-theme +[widget]: #was-this-page-helpful diff --git a/docs/setup/basics.md b/docs/setup/basics.md index 00ef188..822fc84 100644 --- a/docs/setup/basics.md +++ b/docs/setup/basics.md @@ -11,25 +11,21 @@ project using the [`new` command][new], this file will be automatically created for you, and include an example configuration with comments describing the available settings. -[new]: ../usage/new.md - ??? info "Why Zensical uses TOML" The [TOML file format] is specifically designed to be easy to scan and understand. We've chosen TOML over YAML, since it avoids a number of problems that YAML suffers from: - * YAML uses indentation to express structure, which makes it particularly + - YAML uses indentation to express structure, which makes it particularly error prone to indentation mistakes that are hard to locate. In TOML, whitespace is mostly a stylistic choice. - * In YAML, values do not need to be escaped, which can cause ambiguities if + - In YAML, values do not need to be escaped, which can cause ambiguities if a value can be interpreted as different types, such as `no` or `off`, which would both be interpreted as a boolean by YAML, when they could be intended as strings. TOML requires all strings to be quoted. -[TOML file format]: https://toml.io/ - ## Transition from MkDocs To ease transition from [Material for MkDocs], Zensical can natively read @@ -45,8 +41,6 @@ both configuration file formats in content tabs. for configuration with `mkdocs.yml` will always be supported, but eventually move out of the core. -[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/ - ## The `project` scope A `zensical.toml` configuration begins with a line declaring a scope for the @@ -133,8 +127,6 @@ HTML header and should be set unless you're building for [offline usage]. site_url: https://example.com ``` - [offline usage]: offline.md - ### `site_description` A `site_description` is used in the HTML head if the page itself does not @@ -154,8 +146,6 @@ to describe the page content. site_description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. ``` -[description in the page metadata]: ../authoring/frontmatter.md - ### `site_author` The `site_author` setting is used in the HTML `head` element to indicate the @@ -216,8 +206,6 @@ configuration file. This is a temporary limitation. We're working on increasing flexibility. As a workaround, please set `docs_dir` to a subdirectory, such as `docs`, and move your source files there. You can subscribe to the [backlog item] for this feature if you want to be notified when it's available. - [backlog item]: https://github.com/zensical/backlog/issues/101 - ### `site_dir` The `site_dir` specifies the path to the directory your site will be written to. @@ -281,19 +269,19 @@ server. The default value is `true`. === "`true`" - Source file | Generated File | URL Format - ---------------- | ------------------ | ------------------- - index.md | index.html | / - usage.md | usage.html | /usage/ - about/license.md | about/license.html | /about/license/ + | Source file | Generated File | URL Format | + | ---------------- | ------------------ | --------------- | + | index.md | index.html | / | + | usage.md | usage.html | /usage/ | + | about/license.md | about/license.html | /about/license/ | === "`false`" - Source file | Generated File | URL Format - ---------------- | ------------------ | ------------------- - index.md | index.html | /index.html - usage.md | usage.html | /usage.html - about/license.md | about/license.html | /about/license.html + | Source file | Generated File | URL Format | + | ---------------- | ------------------ | ------------------- | + | index.md | index.html | /index.html | + | usage.md | usage.html | /usage.html | + | about/license.md | about/license.html | /about/license.html | ### `dev_addr` @@ -350,15 +338,6 @@ configuration: - fragments ``` - [preview]: ../usage/preview.md - [Snippets]: extensions/python-markdown-extensions.md#snippets - [Macros]: extensions/macros.md - [macros-module]: extensions/macros.md#module_name - [macros-modules]: extensions/macros.md#modules - [macros-include_yaml]: extensions/macros.md#include_yaml - [macros-include_dir]: extensions/macros.md#include_dir - [mkdocstrings]: extensions/mkdocstrings.md - ## Unsupported settings The following `mkdocs.yml` settings are not (yet) supported in Zensical, as @@ -370,3 +349,18 @@ we're rethinking how configuration and customization should work: - `draft_docs` - `not_in_nav` - `hooks` + +[backlog item]: https://github.com/zensical/backlog/issues/101 +[description in the page metadata]: ../authoring/frontmatter.md +[Macros]: extensions/macros.md +[macros-include_dir]: extensions/macros.md#include_dir +[macros-include_yaml]: extensions/macros.md#include_yaml +[macros-module]: extensions/macros.md#module_name +[macros-modules]: extensions/macros.md#modules +[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/ +[mkdocstrings]: extensions/mkdocstrings.md +[new]: ../usage/new.md +[offline usage]: offline.md +[preview]: ../usage/preview.md +[Snippets]: extensions/python-markdown-extensions.md#snippets +[TOML file format]: https://toml.io/ diff --git a/docs/setup/colors.md b/docs/setup/colors.md index c6d5e8e..752beb3 100644 --- a/docs/setup/colors.md +++ b/docs/setup/colors.md @@ -11,16 +11,14 @@ Zensical allows to change the color palette of your documentation site through configuration to fit your brand's identity. If you want to go beyond that, you can also define [custom colors]. - [custom colors]: #custom-colors - ## Configuration ### Color palette #### Color scheme -Zensical supports two color schemes: a __light mode__, which is called `default`, -and a __dark mode__, which is called `slate`. The color scheme can be set via +Zensical supports two color schemes: a **light mode**, which is called `default`, +and a **dark mode**, which is called `slate`. The color scheme can be set via configuration: === "`zensical.toml`" @@ -192,7 +190,7 @@ following lines to allow users to switch between light and dark mode: toggle.name = "Switch to light mode" ``` - 1. Note that the `theme.palette` setting is defined as a list. + 1. Note that the `theme.palette` setting is defined as a list. === "`mkdocs.yml`" @@ -213,12 +211,10 @@ following lines to allow users to switch between light and dark mode: name: Switch to light mode ``` - 1. Note that the `theme.palette` setting is now defined as a list. + 1. Note that the `theme.palette` setting is now defined as a list. You can use any icon from an [available icon set] for the toggle icon. - [available icon set]: ../authoring/icons-emojis.md#included-icon-sets - This configuration will render a color palette toggle next to the search bar. Note that you can also define separate settings for [`primary`][palette.primary] and [`accent`][palette.accent] per color palette. @@ -227,22 +223,18 @@ The following properties must be set for each toggle: `icon` -: This property must point to a valid icon path referencing any icon -bundled with the theme, or the build will not succeed. Some popular combinations -in addition to the ones above: +: This property must point to a valid icon path referencing any icon + bundled with the theme, or the build will not succeed. Some popular combinations + in addition to the ones above: - * :lucide-sun: + :lucide-moon: – `lucide/sun` + `lucide/moon` - * :lucide-toggle-left: + :lucide-toggle-right: – `lucide/toggle-left` + `lucide/toggle-right` + - :lucide-sun: + :lucide-moon: – `lucide/sun` + `lucide/moon` + - :lucide-toggle-left: + :lucide-toggle-right: – `lucide/toggle-left` + `lucide/toggle-right` `name` + : This property is used as the toggle's `title` attribute and should be set to a discernable name to improve accessibility. It's rendered as a [tooltip]. - [palette.scheme]: #color-scheme - [palette.primary]: #primary-color - [palette.accent]: #accent-color - [tooltip]: ../authoring/tooltips.md - ### System preference Each color palette can be linked to the user's system preference for light and @@ -348,9 +340,9 @@ selection to the user's operating system. Add the following lines to your config name: Switch to system preference ``` - 1. You can also define separate settings for [`primary`][palette.primary] and - [`accent`][palette.accent] per color palette, i.e. different colors for - light and dark mode. + 1. You can also define separate settings for [`primary`][palette.primary] and + [`accent`][palette.accent] per color palette, i.e. different colors for + light and dark mode. Zensical will now change the color palette each time the operating system switches between light and dark appearance, even when the user doesn't @@ -365,8 +357,6 @@ want to customize the colors beyond the palette (e.g. to use your brand-specific colors), you can add an [additional style sheet] and tweak the values of the CSS variables. - [additional style sheet]: ../customization.md#additional-css - First, set the [`primary`][palette.primary] or [`accent`][palette.accent] values in `mkdocs.yml` to `custom`, to signal to the theme that you want to define custom colors, e.g., when you want to override the `primary` color: @@ -387,7 +377,7 @@ custom colors, e.g., when you want to override the `primary` color: ``` Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" } -__YouTube__, and want to set the primary color to your brand's palette. Just +**YouTube**, and want to set the primary color to your brand's palette. Just add this CSS and make sure that it is included in the `extra_css` setting in your configuration: @@ -415,8 +405,6 @@ your configuration: - stylesheets/extra.css ``` - [CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties - ### Custom color schemes Besides overriding specific colors, you can create your own, named color scheme @@ -462,6 +450,14 @@ can tune the `slate` theme with: } ``` -1. The `hue` value must be in the range of `[0, 360]` - - [attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors +1. The `hue` value must be in the range of `[0, 360]` + +[additional style sheet]: ../customization.md#additional-css +[attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors +[available icon set]: ../authoring/icons-emojis.md#included-icon-sets +[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties +[custom colors]: #custom-colors +[palette.accent]: #accent-color +[palette.primary]: #primary-color +[palette.scheme]: #color-scheme +[tooltip]: ../authoring/tooltips.md diff --git a/docs/setup/comment-system.md b/docs/setup/comment-system.md index f713233..431b89d 100644 --- a/docs/setup/comment-system.md +++ b/docs/setup/comment-system.md @@ -11,18 +11,17 @@ the footer of any page by using [theme extension]. As an example, we'll be integrating [Giscus], which is Open Source, free, and uses GitHub discussions as a backend. - [Giscus]: https://giscus.app/ - ## Customization ### Giscus integration Before you can use [Giscus], you need to complete the following steps: -1. __Install the [Giscus GitHub App]__ and grant access to the repository +1. **Install the [Giscus GitHub App]** and grant access to the repository that should host comments as GitHub discussions. Note that this can be a repository different from your documentation. -2. __Visit [Giscus] and generate the snippet__ through their configuration tool + +2. **Visit [Giscus] and generate the snippet** through their configuration tool to load the comment system. Copy the snippet for the next step. The resulting snippet should look similar to this: @@ -91,9 +90,9 @@ and [override the `comments.html` partial][overriding partials] with: {% endif %} ``` -1. This code block ensures that [Giscus] renders with a dark theme when the - palette is set to `slate`. Note that multiple dark themes are available, - so you can change it to your liking. +1. This code block ensures that [Giscus] renders with a dark theme when the + palette is set to `slate`. Note that multiple dark themes are available, + so you can change it to your liking. Replace the highlighted line with the snippet you generated with the [Giscus] configuration tool in the previous step. If you copied the snippet from above, @@ -109,7 +108,8 @@ comments: true ... ``` - [Giscus GitHub App]: https://github.com/apps/giscus - [theme extension]: ../customization.md#extending-the-theme - [comments]: https://github.com/zensical/ui/blob/master/dist/partials/comments.html - [overriding partials]: ../customization.md#overriding-partials +[comments]: https://github.com/zensical/ui/blob/master/dist/partials/comments.html +[Giscus]: https://giscus.app/ +[Giscus GitHub App]: https://github.com/apps/giscus +[overriding partials]: ../customization.md#overriding-partials +[theme extension]: ../customization.md#extending-the-theme diff --git a/docs/setup/data-privacy.md b/docs/setup/data-privacy.md index 239097e..99b5261 100644 --- a/docs/setup/data-privacy.md +++ b/docs/setup/data-privacy.md @@ -11,9 +11,6 @@ Zensical offers features to comply with data privacy regulations, as it offers a native [cookie consent] solution to seek explicit consent from users before setting up [site analytics]. - [cookie consent]: #cookie-consent - [site analytics]: analytics.md - ## Configuration ### Cookie consent @@ -35,8 +32,8 @@ following to your configuration: """ # (1)! ``` - 1. You can add arbitrary HTML tags in the `description`, e.g. to link to your - terms of service or other parts of the site. + 1. You can add arbitrary HTML tags in the `description`, e.g. to link to your + terms of service or other parts of the site. === "`mkdocs.yml`" @@ -51,8 +48,8 @@ following to your configuration: make our documentation better. ``` - 1. You can add arbitrary HTML tags in the `description`, e.g. to link to your - terms of service or other parts of the site. + 1. You can add arbitrary HTML tags in the `description`, e.g. to link to your + terms of service or other parts of the site. The following properties are available: @@ -73,8 +70,8 @@ The following properties are available: state and name of built-in cookies. Currently, the following cookies are built-in: - - __Google Analytics__ – `analytics` (enabled by default) - - __GitHub__ – `github` (enabled by default) + - **Google Analytics** – `analytics` (enabled by default) + - **GitHub** – `github` (enabled by default) Each cookie must receive a unique identifier which is used as a key in the `cookies` map, and can be either set to a string, or to a map defining @@ -129,9 +126,9 @@ The following properties are available: custom = "Custom cookie" ``` - 1. If you define a custom cookie as part of the `cookies` property, - the `analytics` cookie must be added back explicitly, or analytics - won't be triggered. + 1. If you define a custom cookie as part of the `cookies` property, + the `analytics` cookie must be added back explicitly, or analytics + won't be triggered. === "`mkdocs.yml`" @@ -143,9 +140,9 @@ The following properties are available: custom: Custom cookie ``` - 1. If you define a custom cookie as part of the `cookies` property, - the `analytics` cookie must be added back explicitly, or analytics - won't be triggered. + 1. If you define a custom cookie as part of the `cookies` property, + the `analytics` cookie must be added back explicitly, or analytics + won't be triggered. If Google Analytics was configured, the cookie consent will automatically include a setting for the user to disable it. [Custom cookies] @@ -157,6 +154,7 @@ The following properties are available: allow the user to accept cookies and manage settings: === "`zensical.toml`" + ``` toml [project.extra.consent] actions = [ @@ -165,10 +163,11 @@ The following properties are available: ] ``` - 1. If the `manage` settings button is omitted from the `actions` property, - the settings are always shown. + 1. If the `manage` settings button is omitted from the `actions` property, + the settings are always shown. === "`mkdocs.yml`" + ``` yaml extra: consent: @@ -177,8 +176,8 @@ The following properties are available: - manage # (1)! ``` - 1. If the `manage` settings button is omitted from the `actions` property, - the settings are always shown. + 1. If the `manage` settings button is omitted from the `actions` property, + the settings are always shown. The cookie consent form includes three types of buttons: @@ -191,10 +190,6 @@ When a user first visits your site, a cookie consent form is rendered: ![Cookie consent enabled] ![Cookie consent enabled dark] - [Custom cookies]: #custom-cookies - [Cookie consent enabled]: ../assets/screenshots/consent.png#gh-light-mode-only - [Cookie consent enabled dark]: ../assets/screenshots/consent-dark.png#gh-dark-mode-only - #### Change cookie settings In order to comply with GDPR, users must be able to change their cookie settings @@ -202,6 +197,7 @@ at any time. This can be done by adding a simple link to your [copyright notice] in the footer below the copyright message: === "`zensical.toml`" + ``` toml [project] copyright = """ @@ -211,14 +207,13 @@ in the footer below the copyright message: ``` === "`mkdocs.yml`" + ``` yaml copyright: > Copyright © Zensical LLC – Change cookie settings ``` - [copyright notice]: footer.md#copyright-notice - ## Customization ### Custom cookies @@ -228,13 +223,6 @@ will be prompted to accept or reject your custom cookie. Once the user accepts or rejects the cookie consent, or [changes the settings], the page reloads[^1]. Use [additional JavaScript] to query the result: - [^1]: - We reload the page to make interop with custom cookies simpler. If Zensical - was to implement a callback-based approach, the author would need - to make sure to correctly update all scripts that use cookies. Additionally, - the cookie consent is only answered initially, which is why we consider this - to be a good trade-off of DX and UX. - === "`docs/javascripts/consent.js`" ``` js @@ -247,10 +235,12 @@ Use [additional JavaScript] to query the result: ``` === "`zensical.toml`" + ``` toml [project] extra_javascript = ["javascripts/consent.js"] ``` + === "`mkdocs.yml`" ``` yaml @@ -258,5 +248,13 @@ Use [additional JavaScript] to query the result: - javascripts/consent.js ``` - [additional JavaScript]: ../customization.md#additional-javascript - [changes the settings]: #change-cookie-settings +[^1]: We reload the page to make interop with custom cookies simpler. If Zensical was to implement a callback-based approach, the author would need to make sure to correctly update all scripts that use cookies. Additionally, the cookie consent is only answered initially, which is why we consider this to be a good trade-off of DX and UX. + +[additional JavaScript]: ../customization.md#additional-javascript +[changes the settings]: #change-cookie-settings +[cookie consent]: #cookie-consent +[Cookie consent enabled]: ../assets/screenshots/consent.png#gh-light-mode-only +[Cookie consent enabled dark]: ../assets/screenshots/consent-dark.png#gh-dark-mode-only +[copyright notice]: footer.md#copyright-notice +[Custom cookies]: #custom-cookies +[site analytics]: analytics.md diff --git a/docs/setup/extensions/about.md b/docs/setup/extensions/about.md index 5fe6531..0d8fa0f 100644 --- a/docs/setup/extensions/about.md +++ b/docs/setup/extensions/about.md @@ -9,7 +9,7 @@ Markdown is a very small language with an [initial implementation by John Gruber][gruber] that has long served as the reference for Markdown implementations. Its minimal functionality makes it easy to learn but also limits what it can express. Zensical currently uses [Python Markdown], -which supports additional syntax elements provided by __Markdown extensions__. +which supports additional syntax elements provided by **Markdown extensions**. These enrich Python Markdown and make it suitable for technical writing. !!! info "We'll be moving to CommonMark soon" @@ -19,17 +19,14 @@ These enrich Python Markdown and make it suitable for technical writing. [components] in the future. Of course, we will provide tools to automatically migrate your existing content when the time comes. -[CommonMark]: https://zensical.org/about/roadmap/#compatibility -[components]: https://zensical.org/about/roadmap/#component-system - ## Zensical extensions Zensical itself provides support for a number of extensions in addition to the Python Markdown extensions described below. -* [GLightbox](glightbox.md) -* [Macros](macros.md) -* [mkdocstrings](mkdocstrings.md) +- [GLightbox](glightbox.md) +- [Macros](macros.md) +- [mkdocstrings](mkdocstrings.md) ## Python Markdown Extensions @@ -41,12 +38,6 @@ Most of the extensions are enabled [by default] and are included explicitly in the template generated by the `zensical new` command. You can [turn off the defaults] if they do not suit your project. - [gruber]: https://daringfireball.net/projects/markdown/ - [by default]: #default-configuration - [turn off the defaults]: #turning-off-the-defaults - [Python Markdown]: python-markdown.md - [Python Markdown Extensions]: python-markdown-extensions.md - The following extensions are all supported by Zensical and therefore strongly recommended. Click on each extension to learn about its purpose and configuration: @@ -75,26 +66,6 @@ configuration: - [Abbreviations]: python-markdown.md#abbreviations - [Admonition]: python-markdown.md#admonition - [Arithmatex]: python-markdown-extensions.md#arithmatex - [Attribute Lists]: python-markdown.md#attribute-lists - [Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde - [Definition Lists]: python-markdown.md#definition-lists - [Details]: python-markdown-extensions.md#details - [Emoji]: python-markdown-extensions.md#emoji - [Footnotes]: python-markdown.md#footnotes - [Highlight]: python-markdown-extensions.md#highlight - [Keys]: python-markdown-extensions.md#keys - [Markdown in HTML]: python-markdown.md#markdown-in-html - [SmartSymbols]: python-markdown-extensions.md#smartsymbols - [Snippets]: python-markdown-extensions.md#snippets - [SuperFences]: python-markdown-extensions.md#superfences - [Tabbed]: python-markdown-extensions.md#tabbed - [Table of Contents]: python-markdown.md#table-of-contents - [Tables]: python-markdown.md#tables - [Tasklist]: python-markdown-extensions.md#tasklist - ## Default configuration If your configuration file contains no definitions for the extensions then @@ -103,8 +74,6 @@ commonly used and are unlikely to cause any issues. We recommend that you use 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. -[Authoring]: ../../authoring/markdown.md - If you bootstrap your project with [`zensical new`][new command], the following extensions are enabled by default: @@ -198,13 +167,11 @@ extensions are enabled by default: project, turn off the defaults, as shown below. !!! note "Presets are on the roadmap" + We are working on a [preset mechanism] that simplifies configuration and will allow you to add extensions to a set of defaults, customize extensions included in the defaults, as well as remove them. - [preset mechanism]: https://zensical.org/about/roadmap/#configuration - [new command]: ../../usage/new.md - ## Turning off the defaults If you want to reset the behavior to the default behavior of MkDocs, create a @@ -222,3 +189,33 @@ configuration with an empty list of extensions: ``` yaml markdown_extensions: {} ``` + +[Abbreviations]: python-markdown.md#abbreviations +[Admonition]: python-markdown.md#admonition +[Arithmatex]: python-markdown-extensions.md#arithmatex +[Attribute Lists]: python-markdown.md#attribute-lists +[Authoring]: ../../authoring/markdown.md +[by default]: #default-configuration +[Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde +[CommonMark]: https://zensical.org/about/roadmap/#compatibility +[components]: https://zensical.org/about/roadmap/#component-system +[Definition Lists]: python-markdown.md#definition-lists +[Details]: python-markdown-extensions.md#details +[Emoji]: python-markdown-extensions.md#emoji +[Footnotes]: python-markdown.md#footnotes +[gruber]: https://daringfireball.net/projects/markdown/ +[Highlight]: python-markdown-extensions.md#highlight +[Keys]: python-markdown-extensions.md#keys +[Markdown in HTML]: python-markdown.md#markdown-in-html +[new command]: ../../usage/new.md +[preset mechanism]: https://zensical.org/about/roadmap/#configuration +[Python Markdown]: python-markdown.md +[Python Markdown Extensions]: python-markdown-extensions.md +[SmartSymbols]: python-markdown-extensions.md#smartsymbols +[Snippets]: python-markdown-extensions.md#snippets +[SuperFences]: python-markdown-extensions.md#superfences +[Tabbed]: python-markdown-extensions.md#tabbed +[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 a1fcecf..14b303e 100644 --- a/docs/setup/extensions/glightbox.md +++ b/docs/setup/extensions/glightbox.md @@ -81,7 +81,6 @@ Width of the lightbox overlay (default: `auto`). Accepts CSS units (`px`, `%`, ` width: "800px" ``` - #### `height` Height of the lightbox overlay (default: `auto`). Accepts CSS units (`px`, `%`, `vw`, `vh`) or `auto`. @@ -161,13 +160,12 @@ Default caption position for images (default: `bottom`). Valid values: `bottom`, ## Adding attributes to images -- [Attribute Lists] — Enables adding data attributes to images for customizing lightbox behavior: +- [Attribute Lists] — Enables adding data attributes to images for customizing lightbox behavior: - `data-src` — Alternative image source for the lightbox - `data-title` — Custom caption text - `data-description` — Additional description text - `data-caption-position` — Override global caption position - `data-gallery` — Manual gallery grouping - [Attribute Lists]: python-markdown.md#attribute-lists - [light and dark mode images]: ../../authoring/images.md#light-and-dark-mode - +[Attribute Lists]: python-markdown.md#attribute-lists +[light and dark mode images]: ../../authoring/images.md#light-and-dark-mode diff --git a/docs/setup/extensions/macros.md b/docs/setup/extensions/macros.md index 515bf28..ff3af97 100644 --- a/docs/setup/extensions/macros.md +++ b/docs/setup/extensions/macros.md @@ -22,14 +22,10 @@ The Macros extension, included with Zensical, enables [Jinja2] templating in Mar - zensical.extensions.macros ``` - [Jinja2]: https://jinja.palletsprojects.com - !!! tip "Macros in Python docstrings" When using [mkdocstrings] to generate API documentation from Python docstrings, Jinja2 expressions in docstrings are rendered natively, so macros and template variables can be used directly in docstrings. - [mkdocstrings]: https://mkdocstrings.github.io - !!! warning "Keep files in project folder" Zensical watches files to be able to re-build the project when they change. @@ -326,8 +322,6 @@ List of [Jinja2 extensions] to be loaded into the template environment. The defa - jinja2.ext.do ``` - [Jinja2 extensions]: https://jinja.palletsprojects.com/en/stable/extensions/ - ## Defining a module Variables, macros, and filters are registered via a `define_env(env)` function in the configured module: @@ -360,49 +354,47 @@ def define_env(env): The following variables are available in all templates without any additional configuration: -| Variable | Description | -| -------- | ----------- | -| `config` | Project configuration object | -| `environment` | System info: `system`, `system_version`, `python_version` | -| `filters` | Registered Jinja2 filters | -| `filters_builtin` | Built-in Jinja2 filters | -| `git` | Git repository metadata (see below) | -| `macros` | Registered macros | -| `now()` | Current date and time (`datetime.now()`) | -| `page` | Current page object | -| `plugin` | Current extension configuration | -| `context()` | Macro for displaying the full template context | -| `macros_info()` | Macro for displaying environment info, useful for debugging | -| `pd_read_*` | Read a file and return a pandas DataFrame — see [Reading tabular data] | -| `read_*` | Read a file and return it as a Markdown table — see [Reading tabular data] | +| Variable | Description | +| ----------------- | -------------------------------------------------------------------------- | +| `config` | Project configuration object | +| `environment` | System info: `system`, `system_version`, `python_version` | +| `filters` | Registered Jinja2 filters | +| `filters_builtin` | Built-in Jinja2 filters | +| `git` | Git repository metadata (see below) | +| `macros` | Registered macros | +| `now()` | Current date and time (`datetime.now()`) | +| `page` | Current page object | +| `plugin` | Current extension configuration | +| `context()` | Macro for displaying the full template context | +| `macros_info()` | Macro for displaying environment info, useful for debugging | +| `pd_read_*` | Read a file and return a pandas DataFrame — see [Reading tabular data] | +| `read_*` | Read a file and return it as a Markdown table — see [Reading tabular data] | The `git` variable exposes the following fields when a Git repository is detected: -| Field | Description | -| ----- | ----------- | -| `git.commit` | Full commit hash | -| `git.short_commit` | Short commit hash | -| `git.tag` | Full tag name from `git describe` | -| `git.short_tag` | Nearest tag name without suffix | -| `git.author` | Commit author name | -| `git.author_email` | Commit author email | -| `git.committer` | Committer name | -| `git.committer_email` | Committer email | -| `git.date` | Commit date as a `datetime` object | -| `git.date_ISO` | Commit date in ISO 8601 format | -| `git.message` | Commit message | -| `git.status` | `true` if Git information was successfully retrieved | +| Field | Description | +| --------------------- | ---------------------------------------------------- | +| `git.commit` | Full commit hash | +| `git.short_commit` | Short commit hash | +| `git.tag` | Full tag name from `git describe` | +| `git.short_tag` | Nearest tag name without suffix | +| `git.author` | Commit author name | +| `git.author_email` | Commit author email | +| `git.committer` | Committer name | +| `git.committer_email` | Committer email | +| `git.date` | Commit date as a `datetime` object | +| `git.date_ISO` | Commit date in ISO 8601 format | +| `git.message` | Commit message | +| `git.status` | `true` if Git information was successfully retrieved | The following filters are registered and available in all templates: -| Filter | Description | -| ------ | ----------- | -| `add_indentation` | Indents every line of a string by a given number of `spaces` or `tabs` | -| `convert_to_md_table` | Converts a pandas DataFrame to a Markdown table string | -| `fix_url` | Prepends `../` to relative URLs, correcting links generated in macro context | -| `pretty` | Formats `context()` output as a Markdown table, useful for debugging | - - [Reading tabular data]: #reading-tabular-data +| Filter | Description | +| --------------------- | ---------------------------------------------------------------------------- | +| `add_indentation` | Indents every line of a string by a given number of `spaces` or `tabs` | +| `convert_to_md_table` | Converts a pandas DataFrame to a Markdown table string | +| `fix_url` | Prepends `../` to relative URLs, correcting links generated in macro context | +| `pretty` | Formats `context()` output as a Markdown table, useful for debugging | ## Reading tabular data @@ -410,52 +402,46 @@ Tabular data from external files can be read and rendered directly as Markdown t === "with `pip`" - ```sh + ``` sh pip install pandas tabulate ``` === "with `uv`" - ```sh + ``` sh uv add pandas tabulate ``` File paths are resolved relative to the directory containing the configuration file. A `read_*` macro is provided for each supported format. Each macro reads the file, converts it to a pandas DataFrame internally, and returns a Markdown table string ready to be embedded into content: -```jinja +``` jinja {{ read_csv("data/team.csv") }} ``` Keyword arguments are split between the underlying pandas reader and the [`DataFrame.to_markdown()`][to_markdown] method: -```jinja +``` jinja {{ read_csv("data/releases.csv", sep=";", index=True) }} ``` The following formats are supported: -| Macro | Description | Extra dependency | -| ----- | ----------- | ---------------- | -| `read_csv` | Comma-separated values | — | -| `read_fwf` | Fixed-width formatted text | — | -| `read_yaml` | YAML | — | -| `read_json` | JSON | — | -| `read_table` | Generic delimited text | — | -| `read_excel` | Excel (`.xlsx`, `.xls`) | [`openpyxl`][openpyxl] | -| `read_feather` | Apache Feather | [`pyarrow`][pyarrow] | +| Macro | Description | Extra dependency | +| -------------- | -------------------------- | ---------------------- | +| `read_csv` | Comma-separated values | — | +| `read_fwf` | Fixed-width formatted text | — | +| `read_yaml` | YAML | — | +| `read_json` | JSON | — | +| `read_table` | Generic delimited text | — | +| `read_excel` | Excel (`.xlsx`, `.xls`) | [`openpyxl`][openpyxl] | +| `read_feather` | Apache Feather | [`pyarrow`][pyarrow] | When the data needs to be processed before rendering, the `pd_read_*` variants return a pandas DataFrame instead of a Markdown string. A `pd_read_*` macro is available for each format listed above: -```jinja +``` jinja {{ pd_read_csv("data/team.csv") | convert_to_md_table }} ``` - [pandas]: https://pandas.pydata.org - [tabulate]: https://pypi.org/project/tabulate/ - [openpyxl]: https://pypi.org/project/openpyxl/ - [pyarrow]: https://pypi.org/project/pyarrow/ - [to_markdown]: https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html - ## Per-page overrides Rendering behavior can be overridden on a per-page basis via front matter. Setting `render_macros: false` disables Jinja2 rendering for a page, even when [`render_by_default`](#render_by_default) is `true`: @@ -487,5 +473,14 @@ include_yaml: When macros or filters read from external files — such as CSV data files or Markdown fragments — modifications to those files will not trigger a rebuild during [preview] unless the paths are registered via the [`watch`][watch] configuration option. - [preview]: ../../usage/preview.md - [watch]: ../basics.md#watch +[Jinja2]: https://jinja.palletsprojects.com +[Jinja2 extensions]: https://jinja.palletsprojects.com/en/stable/extensions/ +[mkdocstrings]: https://mkdocstrings.github.io +[openpyxl]: https://pypi.org/project/openpyxl/ +[pandas]: https://pandas.pydata.org +[preview]: ../../usage/preview.md +[pyarrow]: https://pypi.org/project/pyarrow/ +[Reading tabular data]: #reading-tabular-data +[tabulate]: https://pypi.org/project/tabulate/ +[to_markdown]: https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html +[watch]: ../basics.md#watch diff --git a/docs/setup/extensions/markdown-exec.md b/docs/setup/extensions/markdown-exec.md index 9652d58..d4a213e 100644 --- a/docs/setup/extensions/markdown-exec.md +++ b/docs/setup/extensions/markdown-exec.md @@ -9,8 +9,6 @@ status: new [Markdown Exec] executes code blocks in your Markdown files at build time and renders their output in place of the code, instead of just displaying it. It supports Python, shell (`bash`, `sh`, `console`), Pyodide, and directory trees (`tree`), and can render results as Markdown or raw HTML. -[Markdown Exec]: https://pawamoy.github.io/markdown-exec/ - !!! warning "Executes arbitrary code at build time" Markdown Exec runs the code in your fenced code blocks when the site is @@ -23,13 +21,13 @@ Markdown Exec is not included with Zensical by default, so it needs to be instal === "with `pip`" - ```sh + ``` sh pip install "markdown-exec[ansi]" ``` === "with `uv`" - ```sh + ``` sh uv add "markdown-exec[ansi]" ``` @@ -39,19 +37,15 @@ The `ansi` extra adds the pieces needed to render ANSI colors in HTML code block Markdown Exec relies on the [SuperFences] extension, which is [enabled by default] in Zensical. Configure Markdown Exec as a plugin: -[SuperFences]: python-markdown-extensions.md#superfences -[enabled by default]: about.md#default-configuration - - === "`zensical.toml`" - ```toml + ``` toml [project.plugins.markdown-exec] ``` === "`mkdocs.yml`" - ```yaml + ``` yaml plugins: - markdown-exec ``` @@ -62,7 +56,7 @@ Enabling it via the plugin, rather than by hand-listing custom fences under `pym Add the `exec="on"` option to a fenced code block to run it and render its output instead of the source: -````markdown +```` markdown ```python exec="on" print("Hello Markdown!") ``` @@ -70,7 +64,7 @@ print("Hello Markdown!") The `exec` option is true for any value except `0`, `no`, `off`, and `false` (case insensitive). To run every code block of a given language without adding `exec="on"` to each one, set the `MARKDOWN_EXEC_AUTO` environment variable before building the site: -```sh +``` sh MARKDOWN_EXEC_AUTO=python,bash ``` @@ -80,7 +74,7 @@ By default, printed output is treated as Markdown and rendered accordingly. Set To render both the code and its output, add the `source` option: -````markdown +```` markdown ```python exec="on" source="above" print("I'm the result!") ``` @@ -88,19 +82,13 @@ print("I'm the result!") Accepted values are `above`, `below`, `tabbed-left`, `tabbed-right`, `block`, and `console`. The tabbed and block styles depend on the [Tabbed] and [Markdown in HTML] extensions, both of which are on by default in Zensical. -[Tabbed]: python-markdown-extensions.md#tabbed -[Markdown in HTML]: python-markdown.md#markdown-in-html - ### Interactive code blocks Markdown Exec can generate interactive Python code blocks that can be edited and executed by the readers of your documentation. These code blocks are not executed at build time: they run on your reader's devices, client-side. The editing capabilities are provided thanks to the [Ace] editor. The Python code runs on the client device thanks to [Pyodide]. -[Ace]: https://ace.c9.io/ -[Pyodide]: https://pyodide.org/en/stable/ - To create such interactive Python code blocks, create `pyodide` fences: -````md +```` md ```pyodide print("Hello world!") ``` @@ -108,7 +96,7 @@ print("Hello world!") This example will generate the following interactive code block. Try editing the code, then running it with ++ctrl+enter++ or by clicking "Run" in the top-right corner. -```pyodide +``` pyodide print("Hello world!") ``` @@ -123,3 +111,11 @@ Markdown Exec has additional options for naming and prefixing generated HTML ids - [Python usage](https://pawamoy.github.io/markdown-exec/usage/python/) - [Shell usage](https://pawamoy.github.io/markdown-exec/usage/shell/) - [Gallery of examples](https://pawamoy.github.io/markdown-exec/gallery/) + +[Ace]: https://ace.c9.io/ +[enabled by default]: about.md#default-configuration +[Markdown Exec]: https://pawamoy.github.io/markdown-exec/ +[Markdown in HTML]: python-markdown.md#markdown-in-html +[Pyodide]: https://pyodide.org/en/stable/ +[SuperFences]: python-markdown-extensions.md#superfences +[Tabbed]: python-markdown-extensions.md#tabbed diff --git a/docs/setup/extensions/mkdocstrings.md b/docs/setup/extensions/mkdocstrings.md index e4fc968..603b84d 100644 --- a/docs/setup/extensions/mkdocstrings.md +++ b/docs/setup/extensions/mkdocstrings.md @@ -15,10 +15,6 @@ months, making it much more flexible and powerful. not yet supported, specifically backlinks. We're working on bringing these features into Zensical. - [mkdocstrings]: https://mkdocstrings.github.io - [0.0.11]: https://github.com/zensical/zensical/releases/tag/v0.0.11 - [API reference documentation]: https://zensical.org/about/roadmap/#api-documentation - ## Installation [mkdocstrings] is not included with Zensical by default, so it needs to be @@ -74,9 +70,6 @@ The complete list of options can be found here: - [mkdocstrings documentation] - [mkdocstrings Python handler documentation]. - [mkdocstrings documentation]: https://mkdocstrings.github.io/usage/ - [mkdocstrings Python handler documentation]: https://mkdocstrings.github.io/python/usage/ - !!! warning "Watching source files" While it is possible to configure search paths that are external to the @@ -91,3 +84,9 @@ The complete list of options can be found here: - [Proposal: Configuration](https://github.com/zensical/backlog/issues/47) - [Allow use of `..` in `docs_dir` and `site_dir`](https://github.com/zensical/backlog/issues/56) - [Symbolic links pointing outside of `docs_dir`](https://github.com/zensical/backlog/issues/55) + +[0.0.11]: https://github.com/zensical/zensical/releases/tag/v0.0.11 +[API reference documentation]: https://zensical.org/about/roadmap/#api-documentation +[mkdocstrings]: https://mkdocstrings.github.io +[mkdocstrings documentation]: https://mkdocstrings.github.io/usage/ +[mkdocstrings Python handler documentation]: https://mkdocstrings.github.io/python/usage/ diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 53a7a91..039110e 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -9,8 +9,6 @@ additional extensions perfectly suited for advanced technical writing. Zensical lists this package as an explicit dependency, so it's automatically installed with a supported version. - [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/ - ## Supported extensions In general, all extensions that are part of [Python Markdown Extensions] should @@ -23,10 +21,6 @@ The [Arithmatex] extension allows for rendering of block and inline block equations and integrates seamlessly with [MathJax][^1] – a library for mathematical typesetting. Enable it via: -[^1]: Other libraries like [KaTeX] are also supported and can be integrated - with some additional effort. See the [Arithmatex documentation on KaTeX] - for further guidance, as this is beyond the scope of Zensical. - === "`zensical.toml`" ``` toml @@ -104,15 +98,6 @@ See these authoring guides for usage: - [Using block syntax] - [Using inline block syntax] - [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ - [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex - [MathJax]: https://www.mathjax.org/ - [KaTeX]: https://github.com/Khan/KaTeX - [additional JavaScript]: ../../customization.md#additional-javascript - [instant navigation]: ../navigation.md#instant-navigation - [Using block syntax]: ../../authoring/math.md#use-block-syntax - [Using inline block syntax]: ../../authoring/math.md#use-inline-block-syntax - ### Caption The [Caption] extension adds the ability to add captions to any Markdown block, @@ -135,8 +120,6 @@ The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. See the [Caption documentation][Caption] for more information. - [Caption]: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/ - ### Caret, Mark & Tilde { #caret-mark-tilde } The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text @@ -169,12 +152,6 @@ See these authoring guides for usage: - [Highlighting text] - [Sub- and superscripts] - [Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/ - [Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ - [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ - [Highlighting text]: ../../authoring/formatting.md#highlight-text - [Sub- and superscripts]: ../../authoring/formatting.md#sub-and-superscripts - ### Details The [Details] extension supercharges the [Admonition] extension, making the @@ -198,10 +175,6 @@ No configuration options are available. See this authoring guide for usage: - [Collapsible blocks] - [Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ - [Admonition]: python-markdown.md#admonition - [Collapsible blocks]: ../../authoring/admonitions.md#collapsible-blocks - ### Emoji The [Emoji] extension automatically inlines bundled and custom icons and emojis @@ -215,9 +188,9 @@ in `*.svg` file format into the resulting HTML page. Enable it via: emoji_generator = "zensical.extensions.emoji.to_svg" ``` - 1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to - support the inlining of icons, the `zensical` namespace must be used, as it - extends the functionality of `pymdownx`. + 1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to + support the inlining of icons, the `zensical` namespace must be used, as it + extends the functionality of `pymdownx`. === "`mkdocs.yml`" @@ -228,13 +201,14 @@ in `*.svg` file format into the resulting HTML page. Enable it via: emoji_generator: !!python/name:zensical.extensions.emoji.to_svg ``` - 1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to - support the inlining of icons, the `zensical` namespace must be used, as it - extends the functionality of `pymdownx`. + 1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to + support the inlining of icons, the `zensical` namespace must be used, as it + extends the functionality of `pymdownx`. The following configuration options are supported: #### `emoji_index` + This option defines which set of emojis is used for rendering. Note that the use of `emojione` is not recommended due to [restrictions in licensing][Emoji index]: @@ -310,13 +284,6 @@ See usage: - [Using icons] - [Using icons in templates] - [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ - [Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes - [icon customization guide]: ../logo-and-icons.md#additional-icons - [Using emojis]: ../../authoring/icons-emojis.md#use-emojis - [Using icons]: ../../authoring/icons-emojis.md#use-icons - [Using icons in templates]: ../../authoring/icons-emojis.md#use-icons-in-templates - ### Highlight The [Highlight] extension adds support for syntax highlighting of code blocks @@ -331,9 +298,9 @@ The [Highlight] extension adds support for syntax highlighting of code blocks [project.markdown_extensions.pymdownx.superfences] ``` - 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to - perform syntax highlighting on code blocks, not the other way round, which - is why this extension also needs to be enabled. + 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to + perform syntax highlighting on code blocks, not the other way round, which + is why this extension also needs to be enabled. === "`mkdocs.yml`" @@ -344,9 +311,9 @@ The [Highlight] extension adds support for syntax highlighting of code blocks - pymdownx.superfences # (1)! ``` - 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to - perform syntax highlighting on code blocks, not the other way round, which - is why this extension also needs to be enabled. + 1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to + perform syntax highlighting on code blocks, not the other way round, which + is why this extension also needs to be enabled. The following configuration options are supported: @@ -436,6 +403,7 @@ line itself: ``` !!! note "Avoid including line numbers in copy-and-paste" + Note that `inline` will put line numbers next to the actual code, which means that they will be included when selecting text with the cursor or copying a code block to the clipboard. Thus, the usage of either `table` @@ -493,17 +461,6 @@ See these authoring guides for usage: - [Highlighting specific lines] - [Custom syntax theme] - [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/ - [pymdownx.superfences]: #superfences - [pymdownx.inlinehilite]: #inlinehilite - [Pygments]: https://pygments.org - [title]: ../../authoring/code-blocks.md#add-a-title - [Adding line numbers]: ../../authoring/code-blocks.md#add-line-numbers - [Using code blocks]: ../../authoring/code-blocks.md#usage - [Adding a title]: ../../authoring/code-blocks.md#add-a-title - [Highlighting specific lines]: ../../authoring/code-blocks.md#highlight-specific-lines - [Custom syntax theme]: ../../authoring/code-blocks.md#custom-syntax-theme - ### InlineHilite The [InlineHilite] extension add support for syntax highlighting of inline code @@ -534,11 +491,6 @@ See this authoring guide for usage: - [Highlighting inline code blocks] - [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ - [InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options - [pymdownx.highlight]: #highlight - [Highlighting inline code blocks]: ../../authoring/code-blocks.md#highlight-inline-code-blocks - ### Keys The [Keys] extension adds a simple syntax to allow for the rendering of keyboard @@ -566,10 +518,6 @@ See this authoring guide for usage: - [Adding keyboard keys] - [Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/ - [Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options - [Adding keyboard keys]: ../../authoring/formatting.md#add-keyboard-keys - ### SmartSymbols The [SmartSymbols] extension converts some sequences of characters into their @@ -592,8 +540,6 @@ The configuration options of this extension are not specific to Zensical as they only impact the Markdown parsing stage. See the [SmartSymbols documentation][SmartSymbols] for guidance. - [SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ - ### Snippets The [Snippets] extension adds the ability to embed content from arbitrary files @@ -622,10 +568,6 @@ See these authoring guides for usage: - [Adding a glossary] - [Embedding external files] - [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ - [Adding a glossary]: ../../authoring/tooltips.md#add-a-glossary - [Embedding external files]: ../../authoring/code-blocks.md#embed-external-files - ### SuperFences The [SuperFences] extension allows for arbitrary nesting of code and content @@ -648,6 +590,7 @@ elements. Enable it via: The following configuration options are supported: #### `custom_fences` + This option allows to define a handler for custom fences, e.g. to preserve the definitions of [Mermaid.js] diagrams to be interpreted in the browser: @@ -689,16 +632,6 @@ See these authoring guides for usage: - [Using class diagrams] - [Using entity-relationship diagrams] - [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ - [Mermaid.js]: https://mermaid-js.github.io/mermaid/ - [diagrams]: ../../authoring/diagrams.md - [Using content tabs]: ../../authoring/content-tabs.md#usage - [Using flowcharts]: ../../authoring/diagrams.md#use-flowcharts - [Using sequence diagrams]: ../../authoring/diagrams.md#use-sequence-diagrams - [Using state diagrams]: ../../authoring/diagrams.md#use-state-diagrams - [Using class diagrams]: ../../authoring/diagrams.md#use-class-diagrams - [Using entity-relationship diagrams]: ../../authoring/diagrams.md#use-entity-relationship-diagrams - ### Tabbed The [Tabbed] extension allows the usage of content tabs, a simple way to group @@ -724,7 +657,7 @@ The following configuration options are supported: #### `alternate_style` This option enables the content tabs [alternate style], which has [better - behavior on mobile viewports], and is the only supported style: +behavior on mobile viewports], and is the only supported style: === "`zensical.toml`" @@ -762,6 +695,7 @@ prepends the id of the header to the `id` of the tab: ``` #### `slugify` + This option allows for customization of the slug function. For some languages, the default may not produce good and readable identifiers – consider using another slug function like for example those from [Python @@ -812,14 +746,6 @@ See these authoring guides for usage: - [Grouping other content] - [Embedded content] - [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ - [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style - [better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214 - [Grouping code blocks]: ../../authoring/content-tabs.md#group-code-blocks - [Grouping other content]: ../../authoring/content-tabs.md#group-other-content - [Embedded content]: ../../authoring/content-tabs.md#embed-content - [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ - ### Tasklist The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown] @@ -892,11 +818,6 @@ See this authoring guide for usage: - [Using task lists] - [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ - [GitHub Flavored Markdown]: https://github.github.com/gfm/ - [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension- - [Using task lists]: ../../authoring/lists.md#use-task-lists - ## Other extensions Did not find what you are looking for? The Markdown extensions listed above are @@ -905,3 +826,71 @@ work but we are not advertising their use as we believe there are better alternatives. The `critic` extension, for example, is quite difficult to use in projects of any significant size and we would advise users to work with Git to track changes instead. + +[^1]: Other libraries like [KaTeX] are also supported and can be integrated with some additional effort. See the [Arithmatex documentation on KaTeX] for further guidance, as this is beyond the scope of Zensical. + +[Adding a glossary]: ../../authoring/tooltips.md#add-a-glossary +[Adding a title]: ../../authoring/code-blocks.md#add-a-title +[Adding keyboard keys]: ../../authoring/formatting.md#add-keyboard-keys +[Adding line numbers]: ../../authoring/code-blocks.md#add-line-numbers +[additional JavaScript]: ../../customization.md#additional-javascript +[Admonition]: python-markdown.md#admonition +[alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style +[Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ +[Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex +[better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214 +[Caption]: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/ +[Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/ +[Collapsible blocks]: ../../authoring/admonitions.md#collapsible-blocks +[Custom syntax theme]: ../../authoring/code-blocks.md#custom-syntax-theme +[Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ +[diagrams]: ../../authoring/diagrams.md +[Embedded content]: ../../authoring/content-tabs.md#embed-content +[Embedding external files]: ../../authoring/code-blocks.md#embed-external-files +[Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ +[Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes +[GitHub Flavored Markdown]: https://github.github.com/gfm/ +[Grouping code blocks]: ../../authoring/content-tabs.md#group-code-blocks +[Grouping other content]: ../../authoring/content-tabs.md#group-other-content +[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/ +[Highlighting inline code blocks]: ../../authoring/code-blocks.md#highlight-inline-code-blocks +[Highlighting specific lines]: ../../authoring/code-blocks.md#highlight-specific-lines +[Highlighting text]: ../../authoring/formatting.md#highlight-text +[icon customization guide]: ../logo-and-icons.md#additional-icons +[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ +[InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options +[instant navigation]: ../navigation.md#instant-navigation +[KaTeX]: https://github.com/Khan/KaTeX +[Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/ +[Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options +[Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ +[MathJax]: https://www.mathjax.org/ +[Mermaid.js]: https://mermaid-js.github.io/mermaid/ +[Pygments]: https://pygments.org +[pymdownx.highlight]: #highlight +[pymdownx.inlinehilite]: #inlinehilite +[pymdownx.superfences]: #superfences +[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/ +[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ +[SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ +[Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ +[Sub- and superscripts]: ../../authoring/formatting.md#sub-and-superscripts +[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ +[Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ +[Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ +[Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension- +[Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ +[title]: ../../authoring/code-blocks.md#add-a-title +[Using block syntax]: ../../authoring/math.md#use-block-syntax +[Using class diagrams]: ../../authoring/diagrams.md#use-class-diagrams +[Using code blocks]: ../../authoring/code-blocks.md#usage +[Using content tabs]: ../../authoring/content-tabs.md#usage +[Using emojis]: ../../authoring/icons-emojis.md#use-emojis +[Using entity-relationship diagrams]: ../../authoring/diagrams.md#use-entity-relationship-diagrams +[Using flowcharts]: ../../authoring/diagrams.md#use-flowcharts +[Using icons]: ../../authoring/icons-emojis.md#use-icons +[Using icons in templates]: ../../authoring/icons-emojis.md#use-icons-in-templates +[Using inline block syntax]: ../../authoring/math.md#use-inline-block-syntax +[Using sequence diagrams]: ../../authoring/diagrams.md#use-sequence-diagrams +[Using state diagrams]: ../../authoring/diagrams.md#use-state-diagrams +[Using task lists]: ../../authoring/lists.md#use-task-lists diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 3814c65..5d66bce 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -9,14 +9,11 @@ of what makes it so attractive for technical writing. Following is a list of all supported extensions, linking to the relevant sections of the authoring guide for which features they need to be enabled. - [Python Markdown]: https://python-markdown.github.io/ - !!! tip "Defaults" + Zensical has [sensible defaults] for the Markdown extensions settings. Make sure to check these out before you begin to configure things manually. -[sensible defaults]: about.md#default-configuration - ## Supported extensions ### Abbreviations @@ -44,10 +41,6 @@ usage: - [Adding abbreviations] - [Adding a glossary] - [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/ - [Adding abbreviations]: ../../authoring/tooltips.md#add-abbreviations - [Adding a glossary]: ../../authoring/tooltips.md#add-a-glossary - ### Admonition The [Admonition] extension adds support for admonitions, more commonly known as @@ -75,12 +68,6 @@ usage: - [Removing the title] - [Supported types] - [Admonition]: https://python-markdown.github.io/extensions/admonition/ - [Adding admonitions]: ../../authoring/admonitions.md#usage - [Changing the title]: ../../authoring/admonitions.md#change-the-title - [Removing the title]: ../../authoring/admonitions.md#remove-the-title - [Supported types]: ../../authoring/admonitions.md#supported-types - ### Attribute Lists The [Attribute Lists] extension allows to add HTML attributes and CSS classes @@ -111,16 +98,6 @@ usage: - [Image alignment] - [Image lazy-loading] - [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/ - [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations - [Using grids]: ../../authoring/grids.md#usage - [Adding buttons]: ../../authoring/buttons.md#add-a-button - [Adding tooltips]: ../../authoring/tooltips.md#add-a-tooltip - [Using icons with colors]: ../../authoring/icons-emojis.md#with-colors - [Using icons with animations]: ../../authoring/icons-emojis.md#with-animations - [Image alignment]: ../../authoring/images.md#image-alignment - [Image lazy-loading]: ../../authoring/images.md#image-lazy-loading - ### Definition Lists The [Definition Lists] extension adds the ability to add definition lists (more @@ -145,10 +122,6 @@ usage: - [Using definition lists] - [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/ - [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl - [Using definition lists]: ../../authoring/lists.md#use-definition-lists - ### Footnotes The [Footnotes] extension allows to define inline footnotes, which are then @@ -173,10 +146,6 @@ usage: - [Adding footnote references] - [Adding footnote content] - [Footnotes]: https://python-markdown.github.io/extensions/footnotes/ - [Adding footnote references]: ../../authoring/footnotes.md#adding-footnote-references - [Adding footnote content]: ../../authoring/footnotes.md#add-footnote-content - ### Markdown in HTML The [Markdown in HTML] extension allows for writing Markdown inside of HTML, @@ -208,9 +177,6 @@ can be used: - [Using grids] - [Image captions] - [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/ - [Image captions]: ../../authoring/images.md#image-captions - ### Table of Contents The [Table of Contents] extension automatically generates a table of contents @@ -281,6 +247,7 @@ or string like so: ``` #### `toc.permalink_title` + This option sets the title of the anchor link which is shown on hover and read by screen readers. For accessibility reasons, it might be beneficial to change it to a more discernable name, stating that the anchor links to the @@ -302,6 +269,7 @@ section itself: ``` #### `toc.slugify` + This option allows for customization of the slug function. For some languages, the default may not produce good and readable identifiers – consider using another slug function like for example [those from @@ -326,6 +294,7 @@ Python Markdown Extensions][Slugs]: ``` #### `toc.toc_depth` + Define the range of levels to be included in the table of contents (default: 6). This may be useful for project documentation with deeply structured headings to decrease the length of the table of contents: @@ -363,14 +332,11 @@ To remove the table of contents altogether: ``` !!! warn "Other options" + The other configuration options of this extension are not officially supported by Zensical, which is why they may yield unexpected results. Use them at your own risk. - [Table of Contents]: https://python-markdown.github.io/extensions/toc/ - [site language]: ../language.md#site-language - [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ - ### Tables The [Tables] extension adds the ability to create tables in Markdown by using a @@ -395,7 +361,36 @@ usage: - [Using data tables] - [Column alignment] - [Tables]: https://python-markdown.github.io/extensions/tables/ - [Using data tables]: ../../authoring/data-tables.md#usage - [Column alignment]: ../../authoring/data-tables.md#column-alignment - +[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/ +[Adding a glossary]: ../../authoring/tooltips.md#add-a-glossary +[Adding abbreviations]: ../../authoring/tooltips.md#add-abbreviations +[Adding admonitions]: ../../authoring/admonitions.md#usage +[Adding buttons]: ../../authoring/buttons.md#add-a-button +[Adding footnote content]: ../../authoring/footnotes.md#add-footnote-content +[Adding footnote references]: ../../authoring/footnotes.md#adding-footnote-references +[Adding tooltips]: ../../authoring/tooltips.md#add-a-tooltip +[Admonition]: https://python-markdown.github.io/extensions/admonition/ +[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/ +[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations +[Changing the title]: ../../authoring/admonitions.md#change-the-title +[Column alignment]: ../../authoring/data-tables.md#column-alignment +[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/ +[description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl +[Footnotes]: https://python-markdown.github.io/extensions/footnotes/ +[Image alignment]: ../../authoring/images.md#image-alignment +[Image captions]: ../../authoring/images.md#image-captions +[Image lazy-loading]: ../../authoring/images.md#image-lazy-loading +[Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/ +[Python Markdown]: https://python-markdown.github.io/ +[Removing the title]: ../../authoring/admonitions.md#remove-the-title +[sensible defaults]: about.md#default-configuration +[site language]: ../language.md#site-language +[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ +[Supported types]: ../../authoring/admonitions.md#supported-types +[Table of Contents]: https://python-markdown.github.io/extensions/toc/ +[Tables]: https://python-markdown.github.io/extensions/tables/ +[Using data tables]: ../../authoring/data-tables.md#usage +[Using definition lists]: ../../authoring/lists.md#use-definition-lists +[Using grids]: ../../authoring/grids.md#usage +[Using icons with animations]: ../../authoring/icons-emojis.md#with-animations +[Using icons with colors]: ../../authoring/icons-emojis.md#with-colors diff --git a/docs/setup/fonts.md b/docs/setup/fonts.md index e583a78..177ca0e 100644 --- a/docs/setup/fonts.md +++ b/docs/setup/fonts.md @@ -12,8 +12,6 @@ since it directly integrates with [Google Fonts]. Alternatively, fonts can be custom-loaded if self-hosting is preferred for data privacy reasons or if another destination should be used. - [Google Fonts]: https://fonts.google.com - ## Configuration ### Regular font @@ -23,12 +21,14 @@ everything that does not need to be monospaced. It can be set to any valid [Google Font][Google Fonts] via your configuration: === "`zensical.toml`" + ``` toml [project.theme] font.text = "Inter" ``` === "`mkdocs.yml`" + ``` yaml theme: font: @@ -42,19 +42,20 @@ Just like the regular font, it can be set to any valid [Google Font] [Google Fonts] via your configuration: === "`zensical.toml`" + ``` toml [project.theme] font.code = "JetBrains Mono" ``` === "`mkdocs.yml`" + ``` yaml theme: font: code: JetBrains Mono ``` - ### Autoloading If you want to prevent typefaces from being loaded from [Google Fonts], e.g. @@ -62,19 +63,19 @@ to adhere to [data privacy] regulations, and fall back to system fonts, add the following lines to your configuration: === "`zensical.toml`" + ``` toml [project.theme] font = false ``` === "`mkdocs.yml`" + ``` yaml theme: font: false ``` - [data privacy]: https://developers.google.com/fonts/faq/privacy - ## Customization ### Additional fonts @@ -93,6 +94,7 @@ corresponding `@font-face` definition: ``` === "`zensical.toml`" + ``` toml [project] extra_css = ["stylesheets/extra.css"] @@ -116,8 +118,8 @@ globally to be used as the site-wide regular or monospaced font: } ``` - 1. Always define fonts through CSS variables and not `font-family`, as - this would disable the system font fallback. + 1. Always define fonts through CSS variables and not `font-family`, as + this would disable the system font fallback. === "Monospaced font" @@ -127,4 +129,6 @@ globally to be used as the site-wide regular or monospaced font: } ``` - [additional style sheet]: ../customization.md#additional-css +[additional style sheet]: ../customization.md#additional-css +[data privacy]: https://developers.google.com/fonts/faq/privacy +[Google Fonts]: https://fonts.google.com diff --git a/docs/setup/footer.md b/docs/setup/footer.md index 581ba2f..e234758 100644 --- a/docs/setup/footer.md +++ b/docs/setup/footer.md @@ -62,22 +62,21 @@ configuration with: The following properties are available for each link: `social.icon` + : This property must contain a valid path to any [icon bundled with the theme], or the build will not succeed. Some popular choices: - * :fontawesome-brands-github: – `fontawesome/brands/github` - * :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab` - * :fontawesome-brands-x-twitter: – `fontawesome/brands/x-twitter` - * :fontawesome-brands-mastodon: – `fontawesome/brands/mastodon` + - :fontawesome-brands-github: – `fontawesome/brands/github` + - :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab` + - :fontawesome-brands-x-twitter: – `fontawesome/brands/x-twitter` + - :fontawesome-brands-mastodon: – `fontawesome/brands/mastodon` automatically adds [`rel=me`][rel=me] - * :fontawesome-brands-docker: – `fontawesome/brands/docker` - * :fontawesome-brands-facebook: – `fontawesome/brands/facebook` - * :fontawesome-brands-instagram: – `fontawesome/brands/instagram` - * :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin` - * :fontawesome-brands-slack: – `fontawesome/brands/slack` - * :fontawesome-brands-discord: – `fontawesome/brands/discord` - -[icon bundled with the theme]: ../authoring/icons-emojis.md + - :fontawesome-brands-docker: – `fontawesome/brands/docker` + - :fontawesome-brands-facebook: – `fontawesome/brands/facebook` + - :fontawesome-brands-instagram: – `fontawesome/brands/instagram` + - :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin` + - :fontawesome-brands-slack: – `fontawesome/brands/slack` + - :fontawesome-brands-discord: – `fontawesome/brands/discord` `social.link` @@ -87,6 +86,7 @@ The following properties are available for each link: add this: === "`zensical.toml`" + ``` toml [[project.extra.social]] icon = "fontawesome/solid/paper-plane" @@ -94,6 +94,7 @@ The following properties are available for each link: ``` === "`mkdocs.yml`" + ``` yaml extra: social: @@ -108,6 +109,7 @@ The following properties are available for each link: name from the link, if available. === "`zensical.toml`" + ``` toml [[project.extra.social]] icon = "fontawesome/brands/x" @@ -116,6 +118,7 @@ The following properties are available for each link: ``` === "`mkdocs.yml`" + ``` yaml extra: social: @@ -124,8 +127,6 @@ The following properties are available for each link: name: Zensical on Mastodon ``` - [rel=me]: https://docs.joinmastodon.org/user/profile/#verification - ### Copyright notice A custom copyright banner can be rendered as part of the footer, which is @@ -166,7 +167,7 @@ generated. The notice can be removed with the following option: !!! info "Please read this before removing the generator notice" - The subtle __Made with Zensical__ hint in the footer is a great way to + The subtle **Made with Zensical** hint in the footer is a great way to spread the word about Zensical. We offer Zensical as Free and Open Source software under the permissive MIT license. This is one of the ways you can help ensure that the Zensical community grows and thrives, ultimately @@ -181,7 +182,6 @@ with the front matter `hide` property. Use this when the content of the page that is adjacent to the current page is not really related. Add the following lines at the top of a Markdown file: - ``` yaml --- hide: @@ -191,3 +191,6 @@ hide: # Page title ... ``` + +[icon bundled with the theme]: ../authoring/icons-emojis.md +[rel=me]: https://docs.joinmastodon.org/user/profile/#verification diff --git a/docs/setup/header.md b/docs/setup/header.md index 0ef706c..c15590b 100644 --- a/docs/setup/header.md +++ b/docs/setup/header.md @@ -11,9 +11,6 @@ The header can be customized to show an announcement bar that disappears upon sc the [search bar] and a place to display your project's [git repository], as explained in those dedicated guides. - [search bar]: search.md - [git repository]: repository.md - ## Configuration ### Automatic hiding @@ -55,9 +52,6 @@ block][overriding blocks], which is empty by default: {% endblock %} ``` - [extend the theme]: ../customization.md#extending-the-theme - [overriding blocks]: ../customization.md#overriding-blocks - #### Mark as read For temporary announcements that can be marked as read by the user, a button to @@ -83,3 +77,8 @@ your configuration: When the user clicks the button, the current announcement is dismissed and not displayed again until the content of the announcement changes. + +[extend the theme]: ../customization.md#extending-the-theme +[git repository]: repository.md +[overriding blocks]: ../customization.md#overriding-blocks +[search bar]: search.md diff --git a/docs/setup/language.md b/docs/setup/language.md index beb8555..8402bae 100644 --- a/docs/setup/language.md +++ b/docs/setup/language.md @@ -38,8 +38,6 @@ The following languages are supported: --8<-- "includes/languages.html" - [single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes - ### Site language selector If your documentation is available in multiple languages, a language selector @@ -78,12 +76,11 @@ The following properties are required for each alternate language: `alternate.link` -: This property must be set to an absolute link, which might also point to - another domain or subdomain not necessarily generated with Zensical. - If it includes a domain part, it's used as defined. Otherwise the domain - part of the [`site_url`][site_url] as set in your configuration is - prepended to the link. - +: This property must be set to an absolute link, which might also point to + another domain or subdomain not necessarily generated with Zensical. + If it includes a domain part, it's used as defined. Otherwise the domain + part of the [`site_url`][site_url] as set in your configuration is + prepended to the link. `alternate.lang` @@ -91,9 +88,6 @@ The following properties are required for each alternate language: the `hreflang` attribute of the link, improving discoverability via search engines. - [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url - [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes - ### Directionality While many languages are read `ltr` (left-to-right), Zensical also @@ -101,12 +95,14 @@ supports `rtl` (right-to-left) directionality which is deduced from the selected language, but can also be set with: === "`zensical.toml`" + ``` toml [project.theme] direction = "ltr" ``` === "`mkdocs.yml`" + ``` yaml theme: direction: ltr @@ -159,23 +155,29 @@ adjust the ones you want to override: }}{% endmacro %} ``` - 1. Note that `en` must always be used as a fallback language, as it's the - default theme language. + 1. Note that `en` must always be used as a fallback language, as it's the + default theme language. - 2. Check the [list of available languages], pick the translation you want - to override for your language and add them here. + 2. Check the [list of available languages], pick the translation you want + to override for your language and add them here. === "`zensical.toml`" + ``` toml [project.theme] language = "custom" ``` + === "`mkdocs.yml`" + ``` yaml theme: language: custom ``` - [theme extension]: ../customization.md#extending-the-theme - [translations]: https://github.com/zensical/ui/tree/master/dist/partials/languages - [list of available languages]: https://github.com/zensical/ui/tree/master/dist/partials/languages +[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes +[list of available languages]: https://github.com/zensical/ui/tree/master/dist/partials/languages +[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes +[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url +[theme extension]: ../customization.md#extending-the-theme +[translations]: https://github.com/zensical/ui/tree/master/dist/partials/languages diff --git a/docs/setup/logo-and-icons.md b/docs/setup/logo-and-icons.md index f886542..9428164 100644 --- a/docs/setup/logo-and-icons.md +++ b/docs/setup/logo-and-icons.md @@ -12,8 +12,6 @@ to be used for customization of specific parts of the theme and when writing your documentation in Markdown. Not enough? You can also add [additional icons] with minimal effort. - [additional icons]: #additional-icons - ## Configuration ### Logo @@ -24,6 +22,7 @@ Add the following lines to your configuration to set you own logo from an image file: === "`zensical.toml`" + ``` toml [project.theme] logo = "images/logo.png" @@ -40,32 +39,33 @@ To set the logo to use one of the bundled icons, [find a suitable icon] and add it to the configuration: === "`zensical.toml`" + ``` toml [project.theme.icon] logo = "lucide/smile" ``` === "`mkdocs.yml`" + ``` yaml theme: icon: logo: lucide/smile ``` - -[find a suitable icon]: ../authoring/icons-emojis.md#included-icon-sets - Normally, the logo in the header and sidebar links to the homepage of the documentation, which is the same as `site_url`. This behavior can be changed with the following configuration: === "`zensical.toml`" + ``` toml [project.extra] homepage = "https://example.com" ``` === "`mkdocs.yml`" + ``` yaml extra: homepage: https://example.com @@ -78,12 +78,14 @@ must be located in the `docs` folder. Add the following lines to you configuration: === "`zensical.toml`" + ``` toml [project.theme] favicon = "images/favicon.png" ``` === "`mkdocs.yml`" + ``` yaml theme: favicon: images/favicon.png @@ -95,6 +97,7 @@ Most icons you see on your site, such as navigation icons, can also be changed. to change the navigation arrows in the footer, add the following lines to your configuration: === "`zensical.toml`" + ``` toml [project.theme.icon] previous = "fontawesome/solid/angle-left" @@ -102,6 +105,7 @@ to change the navigation arrows in the footer, add the following lines to your c ``` === "`mkdocs.yml`" + ``` yaml theme: icon: @@ -111,22 +115,22 @@ to change the navigation arrows in the footer, add the following lines to your c The following is a complete list of customizable icons used by the theme: -| Icon name | Purpose | -|:-------------|:------------------------------------------------------------------------------| -| `logo` | See [Logo](#logo) | -| `menu` | Open drawer | -| `alternate` | Change language | -| `search` | Search icon | -| `share` | Share search | -| `close` | Reset search, dismiss announcements | -| `top` | Back-to-top button | -| `edit` | Edit current page | -| `view` | View page source | -| `repo` | Repository icon | -| `admonition` | See [Admonition icons](../authoring/admonitions.md#admonition-icons) | -| `tag` | See [Tag icons and identifiers](tags.md#tag-icons-and-identifiers) | -| `previous` | Previous page in footer, hide search on mobile | -| `next` | Next page in footer | +| Icon name | Purpose | +| :----------- | :------------------------------------------------------------------- | +| `logo` | See [Logo](#logo) | +| `menu` | Open drawer | +| `alternate` | Change language | +| `search` | Search icon | +| `share` | Share search | +| `close` | Reset search, dismiss announcements | +| `top` | Back-to-top button | +| `edit` | Edit current page | +| `view` | View page source | +| `repo` | Repository icon | +| `admonition` | See [Admonition icons](../authoring/admonitions.md#admonition-icons) | +| `tag` | See [Tag icons and identifiers](tags.md#tag-icons-and-identifiers) | +| `previous` | Previous page in footer, hide search on mobile | +| `next` | Next page in footer | ## Customization @@ -139,6 +143,7 @@ you downloaded and unpacked the [Bootstrap] icon set, and want to add it to your project documentation. The structure of your project should look like this: === "`zensical.toml`" + ``` { .sh .no-copy } . ├─ overrides/ @@ -161,6 +166,7 @@ your project documentation. The structure of your project should look like this: ``` === "`mkdocs.yml`" + ``` { .sh .no-copy } . ├─ overrides/ @@ -189,26 +195,28 @@ You can now use all :fontawesome-brands-bootstrap: Bootstrap icons anywhere in Markdown files, as well as everywhere icons can be used in your configuration. However, note that the syntaxes are slightly different: -- __Use icons in configuration__: take the path of the `*.svg` icon file - starting at the `.icons` folder and drop the file extension, e.g. for - `.icons/bootstrap/envelope-paper.svg`, use: +- **Use icons in configuration**: take the path of the `*.svg` icon file + starting at the `.icons` folder and drop the file extension, e.g. for + `.icons/bootstrap/envelope-paper.svg`, use: === "`zensical.toml`" + ``` toml [project.theme.icon] logo = "bootstrap/envelope-paper" ``` === "`mkdocs.yml`" + ``` yaml theme: icon: logo: bootstrap/envelope-paper ``` -- __Use icons in Markdown files__: additionally to taking the path from the - `.icons` folder as noted above, replace all `/` with `-` and enclose the icon - shortcode in two colons: +- **Use icons in Markdown files**: additionally to taking the path from the + `.icons` folder as noted above, replace all `/` with `-` and enclose the icon + shortcode in two colons: ``` :bootstrap-envelope-paper: @@ -216,7 +224,9 @@ However, note that the syntaxes are slightly different: For further notes on icon usage, please consult the [icon reference]. - [extend the theme]: ../customization.md#extending-the-theme - [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir - [Bootstrap]: https://icons.getbootstrap.com/ - [icon reference]: ../authoring/icons-emojis.md#use-icons +[additional icons]: #additional-icons +[Bootstrap]: https://icons.getbootstrap.com/ +[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir +[extend the theme]: ../customization.md#extending-the-theme +[find a suitable icon]: ../authoring/icons-emojis.md#included-icon-sets +[icon reference]: ../authoring/icons-emojis.md#use-icons diff --git a/docs/setup/navigation.md b/docs/setup/navigation.md index 613eea4..2dde032 100644 --- a/docs/setup/navigation.md +++ b/docs/setup/navigation.md @@ -13,15 +13,8 @@ documentation. Zensical provides several options to configure the behavior of navigational elements, including [tabs] and [sections], as well as features such as [instant navigation] and [instant previews]. - [tabs]: #navigation-tabs - [sections]: #navigation-sections - [instant navigation]: #instant-navigation - [instant previews]: #instant-previews - Additional navigation can be configured [in the footer]. -[in the footer]: footer.md#navigation - ## Configuration By default, Zensical creates the navigation sidebar on the basis of the folder @@ -36,8 +29,6 @@ configuration file. In the simplest case, you simply list the paths to your content files, leaving it to Zensical to extract a title for each of them from the content itself. The paths need to be relative to the [`docs_dir`][docs_dir]. - [docs_dir]: basics.md#docs_dir - === "`zensical.toml`" ``` toml @@ -84,28 +75,28 @@ your users to the information they require. === "`zensical.toml`" - ``` toml - [project] - nav = [ - {"Home" = "index.md"}, - {"About" = [ - "about/index.md", - "about/vision.md", - "about/team.md" - ]} - ] - ``` + ``` toml + [project] + nav = [ + {"Home" = "index.md"}, + {"About" = [ + "about/index.md", + "about/vision.md", + "about/team.md" + ]} + ] + ``` === "`mkdocs.yml`" - ``` yaml - nav: - - Home: index.md - - About: - - about/index.md - - about/vision.md - - about/team.md - ``` + ``` yaml + nav: + - Home: index.md + - About: + - about/index.md + - about/vision.md + - about/team.md + ``` #### External links @@ -114,19 +105,19 @@ string that cannot be resolved to a Markdown page is treated as a URL. === "`zensical.toml`" - ``` toml - [project] - nav = [ - {"GitHub Repo" = "https://github.com/zensical/docs"} - ] - ``` + ``` toml + [project] + nav = [ + {"GitHub Repo" = "https://github.com/zensical/docs"} + ] + ``` === "`mkdocs.yml`" - ``` yaml - nav: - - GitHub Repo: https://github.com/zensical/docs - ``` + ``` yaml + nav: + - GitHub Repo: https://github.com/zensical/docs + ``` The "GitHub Repo" navigation entry takes the user to the repository for the Zensical Documentation. @@ -145,6 +136,7 @@ the following lines to your configuration: "navigation.instant" ] ``` + === "`mkdocs.yml`" ``` yaml @@ -154,8 +146,8 @@ the following lines to your configuration: ``` The resulting page is parsed and injected and all event handlers and components -are rebound automatically, i.e., __Zensical now behaves like a Single -Page Application__. Also, the search index is persisted through navigation, +are rebound automatically, i.e., **Zensical now behaves like a Single +Page Application**. Also, the search index is persisted through navigation, which is especially useful for large documentation sites. !!! info "The [`site_url`][site_url] setting must be set" @@ -164,9 +156,6 @@ which is especially useful for large documentation sites. navigation, as instant navigation relies on the generated `sitemap.xml` which will be empty if this setting is omitted. - [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest - [site_url]: basics.md#site_url - #### Instant prefetching Instant prefetching is a new experimental feature that will start to fetch a @@ -183,6 +172,7 @@ immediately upon navigation. Enable it with: "navigation.instant.prefetch" ] ``` + === "`mkdocs.yml`" ``` yaml @@ -200,6 +190,7 @@ the top of the page and will be hidden once the page has fully loaded. You can enable it in your configuration with: === "`zensical.toml`" + ``` toml [project.theme] features = [ @@ -209,6 +200,7 @@ enable it in your configuration with: ``` === "`mkdocs.yml`" + ``` yaml theme: features: @@ -282,6 +274,7 @@ extensions in the setup guide. ??? example "Full configuration example" === "`zensical.toml`" + ``` toml [[project.markdown_extensions.zensical.extensions.preview.configurations]] sources.include = [...] @@ -291,6 +284,7 @@ extensions in the setup guide. ``` === "`mkdocs.yml`" + ``` yaml markdown_extensions: - material.extensions.preview: @@ -319,6 +313,7 @@ extensions in the setup guide. 2. Targets specify the pages _to_ which instant previews should be enabled. This is the recommended way to enable instant previews. + --- !!! info "The [`site_url`][site_url] setting must be set" @@ -383,11 +378,6 @@ following lines to your configuration: ![Navigation tabs disabled] ![Navigation tabs disabled dark] - [Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png#gh-light-mode-only - [Navigation tabs enabled dark]: ../assets/screenshots/navigation-tabs-dark.png#gh-dark-mode-only - [Navigation tabs disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only - [Navigation tabs disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only - #### Sticky navigation tabs When sticky tabs are enabled, navigation tabs will lock below the header and @@ -446,11 +436,6 @@ following lines to your configuration: ![Navigation sections disabled] ![Navigation sections disabled dark] - [Navigation sections enabled]: ../assets/screenshots/navigation-sections.png#gh-light-mode-only - [Navigation sections enabled dark]: ../assets/screenshots/navigation-sections-dark.png#gh-dark-mode-only - [Navigation sections disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only - [Navigation sections disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only - Both feature flags, [`navigation.tabs`][tabs] and [`navigation.sections`][sections], can be combined with each other. If both feature flags are enabled, sections are rendered for level 2 navigation items. @@ -469,6 +454,7 @@ Add the following lines to your configuration: "navigation.expand" ] ``` + === "`mkdocs.yml`" ``` yaml @@ -487,11 +473,6 @@ Add the following lines to your configuration: ![Navigation expansion disabled] ![Navigation expansion disabled dark] - [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png#gh-light-mode-only - [Navigation expansion enabled dark]: ../assets/screenshots/navigation-expand-dark.png#gh-dark-mode-only - [Navigation expansion disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only - [Navigation expansion disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only - ### Navigation path Breadcrumbs { #navigation-path data-toc-label="Navigation path" } When navigation paths are activated, a breadcrumb navigation is rendered above @@ -526,15 +507,10 @@ your configuration: ![Navigation path disabled] ![Navigation path disabled dark] - [Navigation path enabled]: ../assets/screenshots/navigation.png#gh-light-mode-only - [Navigation path enabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only - [Navigation path disabled]: ../assets/screenshots/navigation-path.png#gh-light-mode-only - [Navigation path disabled dark]: ../assets/screenshots/navigation-path-dark.png#gh-dark-mode-only - ### Navigation pruning When pruning is enabled, only the visible navigation items are included in the -rendered HTML, __reducing the size of the built site by 33% or more__. Add the +rendered HTML, **reducing the size of the built site by 33% or more**. Add the following lines to your configuration: === "`zensical.toml`" @@ -546,9 +522,9 @@ following lines to your configuration: ] ``` - 1. This feature flag is not compatible with - [`navigation.expand`][navigation.expand], as navigation expansion requires - the complete navigation structure. + 1. This feature flag is not compatible with + [`navigation.expand`][navigation.expand], as navigation expansion requires + the complete navigation structure. === "`mkdocs.yml`" @@ -558,17 +534,15 @@ following lines to your configuration: - navigation.prune # (1)! ``` - 1. This feature flag is not compatible with - [`navigation.expand`][navigation.expand], as navigation expansion requires - the complete navigation structure. + 1. This feature flag is not compatible with + [`navigation.expand`][navigation.expand], as navigation expansion requires + the complete navigation structure. This feature flag is especially useful for documentation sites with thousands of pages, as the navigation makes up a significant fraction of the HTML. Navigation pruning will replace all expandable sections with links to the first page in that section (or the section index page). - [navigation.expand]: #navigation-expansion - ### Section index pages When section index pages are enabled, documents can be directly attached to @@ -584,8 +558,8 @@ following lines to your configuration: ] ``` - 1. This feature flag is not compatible with [`toc.integrate`][toc.integrate], - as sections cannot host the table of contents due to missing space. + 1. This feature flag is not compatible with [`toc.integrate`][toc.integrate], + as sections cannot host the table of contents due to missing space. === "`mkdocs.yml`" @@ -595,8 +569,8 @@ following lines to your configuration: - navigation.indexes # (1)! ``` - 1. This feature flag is not compatible with [`toc.integrate`][toc.integrate], - as sections cannot host the table of contents due to missing space. + 1. This feature flag is not compatible with [`toc.integrate`][toc.integrate], + as sections cannot host the table of contents due to missing space. In order to link a page to a section, create a new document with the name `index.md` in the respective folder, and add it to the beginning of your @@ -617,7 +591,7 @@ navigation section: ] ``` - 1. `README.md` is also considered an index page. + 1. `README.md` is also considered an index page. === "`mkdocs.yml`" @@ -630,9 +604,7 @@ navigation section: - Page n: section/page-n.md ``` - 1. `README.md` is also considered an index page. - - [toc.integrate]: #navigation-integration + 1. `README.md` is also considered an index page. ### Table of contents @@ -650,6 +622,7 @@ following lines to your configuration: "toc.follow" ] ``` + === "`mkdocs.yml`" ``` yaml @@ -673,9 +646,9 @@ to your configuration: ] ``` - 1. This feature flag is not compatible with - [`navigation.indexes`][navigation.indexes], as sections cannot host the - table of contents due to missing space. + 1. This feature flag is not compatible with + [`navigation.indexes`][navigation.indexes], as sections cannot host the + table of contents due to missing space. === "`mkdocs.yml`" @@ -685,10 +658,9 @@ to your configuration: - toc.integrate # (1)! ``` - 1. This feature flag is not compatible with - [`navigation.indexes`][navigation.indexes], as sections cannot host the - table of contents due to missing space. - + 1. This feature flag is not compatible with + [`navigation.indexes`][navigation.indexes], as sections cannot host the + table of contents due to missing space. ===! "With navigation integration" @@ -700,13 +672,6 @@ to your configuration: ![Navigation integration disabled] ![Navigation integration disabled dark] - [table of contents]: extensions/python-markdown.md#table-of-contents - [Navigation integration enabled]: ../assets/screenshots/toc-integrate.png#gh-light-mode-only - [Navigation integration enabled dark]: ../assets/screenshots/toc-integrate-dark.png#gh-dark-mode-only - [Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png#gh-light-mode-only - [Navigation integration disabled dark]: ../assets/screenshots/navigation-tabs-dark.png#gh-dark-mode-only - [navigation.indexes]: #section-index-pages - ### Back-to-top button A back-to-top button can be shown when the user, after scrolling down, starts @@ -765,8 +730,6 @@ hide: ... ``` - [navigation path]: #navigation-path - ## Customization ### Content area width @@ -788,8 +751,8 @@ of CSS: } ``` - 1. If you want the content area to always stretch to the available screen - space, reset `max-width` with the following CSS: + 1. If you want the content area to always stretch to the available screen + space, reset `max-width` with the following CSS: ``` css .md-grid { @@ -811,4 +774,37 @@ of CSS: - stylesheets/extra.css ``` - [additional style sheet]: ../customization.md#additional-css +[additional style sheet]: ../customization.md#additional-css +[docs_dir]: basics.md#docs_dir +[in the footer]: footer.md#navigation +[instant navigation]: #instant-navigation +[instant previews]: #instant-previews +[Navigation expansion disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only +[Navigation expansion disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only +[Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png#gh-light-mode-only +[Navigation expansion enabled dark]: ../assets/screenshots/navigation-expand-dark.png#gh-dark-mode-only +[Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png#gh-light-mode-only +[Navigation integration disabled dark]: ../assets/screenshots/navigation-tabs-dark.png#gh-dark-mode-only +[Navigation integration enabled]: ../assets/screenshots/toc-integrate.png#gh-light-mode-only +[Navigation integration enabled dark]: ../assets/screenshots/toc-integrate-dark.png#gh-dark-mode-only +[navigation path]: #navigation-path +[Navigation path disabled]: ../assets/screenshots/navigation-path.png#gh-light-mode-only +[Navigation path disabled dark]: ../assets/screenshots/navigation-path-dark.png#gh-dark-mode-only +[Navigation path enabled]: ../assets/screenshots/navigation.png#gh-light-mode-only +[Navigation path enabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only +[Navigation sections disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only +[Navigation sections disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only +[Navigation sections enabled]: ../assets/screenshots/navigation-sections.png#gh-light-mode-only +[Navigation sections enabled dark]: ../assets/screenshots/navigation-sections-dark.png#gh-dark-mode-only +[Navigation tabs disabled]: ../assets/screenshots/navigation.png#gh-light-mode-only +[Navigation tabs disabled dark]: ../assets/screenshots/navigation-dark.png#gh-dark-mode-only +[Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png#gh-light-mode-only +[Navigation tabs enabled dark]: ../assets/screenshots/navigation-tabs-dark.png#gh-dark-mode-only +[navigation.expand]: #navigation-expansion +[navigation.indexes]: #section-index-pages +[sections]: #navigation-sections +[site_url]: basics.md#site_url +[table of contents]: extensions/python-markdown.md#table-of-contents +[tabs]: #navigation-tabs +[toc.integrate]: #navigation-integration +[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest diff --git a/docs/setup/offline.md b/docs/setup/offline.md index b17eb20..019976d 100644 --- a/docs/setup/offline.md +++ b/docs/setup/offline.md @@ -37,9 +37,6 @@ the following lines to your configuration: `plugins` is a carry-over from Material for MkDocs and will be automatically replaced in a future version. - [site search]: search.md - [site directory]: basics.md#site_dir - The following settings are available: `config.enabled` @@ -58,9 +55,6 @@ The following settings are available: working towards [feature parity] and will be providing a more comprehensive system for managing [variants] in due course. - [feature parity]: https://zensical.org/compatibility/features/ - [variants]: https://zensical.org/about/roadmap/#configuration - === "`mkdocs.yml`" ``` yaml @@ -79,11 +73,6 @@ Thus, when building for offline usage, make sure to disable the following configuration settings: [instant navigation], [site analytics], [git repository], and [comment systems]. - [instant navigation]: navigation.md#instant-navigation - [Site analytics]: analytics.md - [Git repository]: repository.md - [Comment systems]: comment-system.md - ### `file://` scheme support Offline mode requires Javascript code to support the `file://` @@ -120,4 +109,12 @@ Here it is assumed the asset is in a `js/` folder in your configured `docs/` dir The file name **must** contain the `iframe-worker` substring, otherwise Zensical will fetch it again from unpkg.com. - [fetched from unpkg.com]: https://unpkg.com/iframe-worker/shim +[Comment systems]: comment-system.md +[feature parity]: https://zensical.org/compatibility/features/ +[fetched from unpkg.com]: https://unpkg.com/iframe-worker/shim +[Git repository]: repository.md +[instant navigation]: navigation.md#instant-navigation +[Site analytics]: analytics.md +[site directory]: basics.md#site_dir +[site search]: search.md +[variants]: https://zensical.org/about/roadmap/#configuration diff --git a/docs/setup/repository.md b/docs/setup/repository.md index f007c72..f8c1134 100644 --- a/docs/setup/repository.md +++ b/docs/setup/repository.md @@ -21,12 +21,14 @@ documentation, set `repo_url` in your configuration to the public URL of your repository, e.g.: === "`zensical.toml`" + ``` toml [project] repo_url = "https://github.com/zensical/zensical" ``` === "`mkdocs.yml`" + ``` yaml repo_url: https://github.com/zensical/zensical ``` @@ -36,20 +38,6 @@ screens. Additionally, for public repositories hosted on [GitHub] or [GitLab], the latest release tag[^1], as well as the number of stars and forks, are automatically requested and rendered. - [^1]: - Unfortunately, GitHub only provides an API endpoint to obtain the [latest - release] - not the latest tag. Thus, make sure to [create a release] (not - pre-release) for the latest tag you want to display next to the number of - stars and forks. For GitLab, although it is possible to get a [list of tags - sorted by update time], the [equivalent API endpoint] is used. So, make sure - you also [create a release for GitLab repositories]. - - [latest release]: https://docs.github.com/en/rest/releases/releases#get-the-latest-release - [create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release - [list of tags sorted by update time]: https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags - [equivalent API endpoint]: https://docs.gitlab.com/ee/api/releases/#get-the-latest-release - [create a release for GitLab repositories]: https://docs.gitlab.com/ee/user/project/releases/#create-a-release - ### Repository name Zensical will infer the repository provider by examining the URL and set @@ -94,8 +82,6 @@ the configuration: You can use icons from any of the [available icon sets] or use one of these popular choices: - [available icon sets]: ../authoring/icons-emojis.md#included-icon-sets - - :fontawesome-brands-git: – `fontawesome/brands/git` - :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt` - :fontawesome-brands-github: – `fontawesome/brands/github` @@ -156,6 +142,7 @@ Markdown file in the `docs_dir`. ``` !!! tip "Docs in a different repository" + If your project and its docs reside in different directories, you can make the `edit_uri` an absolute URL, so it does not rely on `repo_url` to form a valid URL. The `repo_url` would point to your project repository, @@ -182,6 +169,14 @@ The icon of the edit and view buttons can be changed with the following lines: view: material/eye ``` - [repo_url]: #repository - [GitHub]: https://github.com/ - [GitLab]: https://about.gitlab.com/ +[^1]: Unfortunately, GitHub only provides an API endpoint to obtain the [latest release] - not the latest tag. Thus, make sure to [create a release] (not pre-release) for the latest tag you want to display next to the number of stars and forks. For GitLab, although it is possible to get a [list of tags sorted by update time], the [equivalent API endpoint] is used. So, make sure you also [create a release for GitLab repositories]. + +[available icon sets]: ../authoring/icons-emojis.md#included-icon-sets +[create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release +[create a release for GitLab repositories]: https://docs.gitlab.com/ee/user/project/releases/#create-a-release +[equivalent API endpoint]: https://docs.gitlab.com/ee/api/releases/#get-the-latest-release +[GitHub]: https://github.com/ +[GitLab]: https://about.gitlab.com/ +[latest release]: https://docs.github.com/en/rest/releases/releases#get-the-latest-release +[list of tags sorted by update time]: https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags +[repo_url]: #repository diff --git a/docs/setup/search.md b/docs/setup/search.md index 1fdcc06..7ca56e4 100644 --- a/docs/setup/search.md +++ b/docs/setup/search.md @@ -27,9 +27,6 @@ documentation as a download. This does not impact multi-lingual search. - [offline]: offline.md - [standalone Open Source project]: https://zensical.org/about/roadmap/#search-and-discovery - ## Configuration The built-in search module is seamlessly integrated with Zensical, @@ -97,8 +94,6 @@ The content of this section is included The content of this section is excluded ``` - [Attribute Lists]: extensions/python-markdown.md#attribute-lists - #### Exclude a block When [Attribute Lists] is enabled, specific sections of pages can be excluded @@ -113,3 +108,7 @@ The content of this block is included The content of this block is excluded { data-search-exclude } ``` + +[Attribute Lists]: extensions/python-markdown.md#attribute-lists +[offline]: offline.md +[standalone Open Source project]: https://zensical.org/about/roadmap/#search-and-discovery diff --git a/docs/setup/social-cards.md b/docs/setup/social-cards.md index 8b224dd..c0471e4 100644 --- a/docs/setup/social-cards.md +++ b/docs/setup/social-cards.md @@ -18,5 +18,5 @@ provide even more powerful social cards functionality for Zensical soon. new features in our pipeline, and what we have planned next. We'll also share exclusive behind-the-scenes insights and invites to workshops. - [feature parity]: https://zensical.org/compatibility/features/ - [newsletter]: https://zensical.org/about/newsletter/ +[feature parity]: https://zensical.org/compatibility/features/ +[newsletter]: https://zensical.org/about/newsletter/ diff --git a/docs/setup/tags.md b/docs/setup/tags.md index 2b287cd..bd7dc1f 100644 --- a/docs/setup/tags.md +++ b/docs/setup/tags.md @@ -11,9 +11,6 @@ Zensical adds first-class support for categorizing pages with tags, which allows users to discover related pages via the [search]. If your documentation is large, tags can help to discover relevant information faster. - [search]: search.md - [feature parity]: https://zensical.org/compatibility/features - ## Configuration The built-in tags functionality lets you categorize any page with tags @@ -21,12 +18,11 @@ as part of the [metadata] of the page. Tags are supported by default, no configuration needed. !!! info "Tag listings are currently not supported" + As we are working towards [feature parity] with Material for MkDocs, we will be adding features such as tag indexes that are implemented as part of the tags plugin in Material for MkDocs. - [metadata]: ../authoring/frontmatter.md - ### Tag icons and identifiers Each tag can be associated with an icon, which is rendered inside the tag. @@ -35,7 +31,7 @@ by adding the following to your configuration: === "`zensical.toml`" - ```toml + ``` toml [project.extra.tags] = "" ``` @@ -77,7 +73,7 @@ setting: === "`zensical.toml`" - ```toml + ``` toml [project.theme.icon.tag] default = "" = "" @@ -96,7 +92,8 @@ setting: ??? example "Expand to see an example" === "`zensical.toml`" - ```toml + + ``` toml [project.theme.icon.tag] default = "lucide/hash" html = "fontawesome/brands/html5" @@ -110,6 +107,7 @@ setting: ``` === "`mkdocs.yml`" + ``` yaml theme: icon: @@ -125,8 +123,6 @@ setting: CSS: css ``` - [custom icon]: logo-and-icons.md#additional-icons - ## Usage ### Add tags @@ -165,3 +161,8 @@ hide: # Page title ... ``` + +[custom icon]: logo-and-icons.md#additional-icons +[feature parity]: https://zensical.org/compatibility/features +[metadata]: ../authoring/frontmatter.md +[search]: search.md diff --git a/docs/setup/validation.md b/docs/setup/validation.md index 9f3c166..7bd8cf5 100644 --- a/docs/setup/validation.md +++ b/docs/setup/validation.md @@ -13,6 +13,7 @@ Broken links are easy to miss – pages get renamed or moved, and references sil Additionally, the build can be aborted when issues are found by enabling [strict mode].
+ !!! tip "Zensical Studio" With [Zensical Studio], we are delivering in-editor support for link @@ -27,13 +28,8 @@ Additionally, the build can be aborted when issues are found by enabling [strict especially navigation and refactorings. We will publish the parser as Open Source in the coming months and integrate into Zensical as the new basis for validation during builds. -
- - [Zensical Studio]: https://zensical.org/studio/ - -[strict mode]: #strict-mode -[unresolved references]: #unresolved_references + ## Configuration @@ -101,7 +97,7 @@ Warn when a link points to a page that does not exist. invalid_links: true ``` -__Example__ +**Example** ``` markdown title="index.md" Oh no, [this page] does not exit. @@ -110,6 +106,7 @@ Oh no, [this page] does not exit. ```
+ ``` console $ zensical build ... @@ -121,6 +118,7 @@ Warning: page does not exist │ ╰───────── page does not exist ───╯ ``` +
--- @@ -143,7 +141,7 @@ Warn when a link points to an anchor that does not exist. invalid_link_anchors: true ``` -__Example__ +**Example** ``` markdown title="index.md" Oh no, [this section] does not exit. @@ -152,6 +150,7 @@ Oh no, [this section] does not exit. ```
+ ``` console $ zensical build ... @@ -163,6 +162,7 @@ Warning: anchor does not exist │ ╰─────── anchor does not exist ───╯ ``` +
### Deprecated checks @@ -195,7 +195,7 @@ Warn when a link or image reference has no matching definition. unresolved_references: true ``` -__Example__ +**Example** ``` markdown title="index.md" This is an [unresolved reference][id]. @@ -237,7 +237,7 @@ Warn when a footnote reference has no matching definition. unresolved_footnotes: true ``` -__Example__ +**Example** ``` markdown title="index.md" This is an unresolved footnote[^id]. @@ -279,13 +279,14 @@ Warn when a link definition is never referenced. unused_definitions: true ``` -__Example__ +**Example** ``` markdown title="index.md" [id]: https://example.com ```
+ ``` console $ zensical build ... @@ -297,6 +298,7 @@ Warning: unused link definition │ ╰── unused link definition ───╯ ``` +
--- @@ -319,13 +321,14 @@ Warn when a footnote definition is never referenced. unused_footnotes: true ``` -__Example__ +**Example** ``` markdown title="index.md" [^id]: This footnote is never referenced. ```
+ ``` console $ zensical build ... @@ -337,6 +340,7 @@ Warning: unused footnote definition │ ╰── unused footnote definition ───╯ ``` +
--- @@ -359,7 +363,7 @@ Warn when a link definition is declared more than once. shadowed_definitions: true ``` -__Example__ +**Example** ``` markdown title="index.md" This [reference][id] has two definitions. @@ -369,6 +373,7 @@ This [reference][id] has two definitions. ```
+ ``` console $ zensical build ... @@ -380,6 +385,7 @@ Warning: shadowed link definition │ ╰── shadowed link definition ───╯ ``` +
--- @@ -402,7 +408,7 @@ Warn when a footnote definition is declared more than once. shadowed_footnotes: true ``` -__Example__ +**Example** ``` markdown title="index.md" This footnote[^id] has two definitions. @@ -412,6 +418,7 @@ This footnote[^id] has two definitions. ```
+ ``` console $ zensical build ... @@ -423,6 +430,7 @@ Warning: shadowed footnote definition │ ╰── shadowed footnote definition ───╯ ``` +
--- @@ -472,3 +480,6 @@ Aborted because --strict flag is set The build is aborted after reporting all issues, and the exit code is set to `1` to indicate failure. This can be useful in CI/CD pipelines to ensure that all links are valid before deploying the site. + +[strict mode]: #strict-mode +[Zensical Studio]: https://zensical.org/studio/ diff --git a/docs/setup/versioning.md b/docs/setup/versioning.md index 45210c9..31443fa 100644 --- a/docs/setup/versioning.md +++ b/docs/setup/versioning.md @@ -9,10 +9,6 @@ documentation on [GitHub Pages] by integrating with our fork of [mike], a tool that was originally designed for MkDocs which we adapted for Zensical – a bridge solution until we introduce [native versioning support]. - [GitHub Pages]: ../publish-your-site.md#github-pages - [mike]: https://github.com/squidfunk/mike - [native versioning support]: https://zensical.org/about/roadmap/#versioning - ## Installation We provide a fork of [mike] that you can install with `pip`: @@ -66,11 +62,11 @@ you can [override the `outdated` block][overriding blocks]: {% endblock %} ``` -1. Given this value for the `href` attribute, the link will always redirect to - the root of your site, which will then redirect to the latest version. This - ensures that older versions of your site do not depend on a specific alias, - e.g. `latest`, to allow for changing the alias later on without breaking - earlier versions. +1. Given this value for the `href` attribute, the link will always redirect to + the root of your site, which will then redirect to the latest version. This + ensures that older versions of your site do not depend on a specific alias, + e.g. `latest`, to allow for changing the alias later on without breaking + earlier versions. This will render a version warning above the header. @@ -85,8 +81,8 @@ to your configuration: default = "stable" # (1)! ``` - 1. You can also define multiple aliases as the default version, e.g. `stable` - and `development`. + 1. You can also define multiple aliases as the default version, e.g. `stable` + and `development`. ``` toml [project.extra.version] @@ -104,8 +100,8 @@ to your configuration: default: stable # (1)! ``` - 1. You can also define multiple aliases as the default version, e.g. `stable` - and `development`. + 1. You can also define multiple aliases as the default version, e.g. `stable` + and `development`. ``` yaml extra: @@ -121,10 +117,6 @@ to your configuration: Make sure one alias matches the [default version], as this is where users are redirected to. - [theme extension]: ../customization.md#extending-the-theme - [overriding blocks]: ../customization.md#overriding-blocks - [default version]: #setting-a-default-version - ### Version alias If you're using aliases for versioning, and want to show the version alias @@ -152,8 +144,6 @@ While this section outlines the basic workflow for publishing new versions, it's best to check out [mike's documentation] to make yourself familiar with its mechanics. - [mike's documentation]: https://github.com/jimporter/mike - ### Publishing a new version If you want to publish a new version of your project documentation, choose a @@ -199,3 +189,11 @@ When publishing a new version, [mike] will create a redirect in the root of your project documentation to the version associated with the alias: _docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_ + +[default version]: #setting-a-default-version +[GitHub Pages]: ../publish-your-site.md#github-pages +[mike]: https://github.com/squidfunk/mike +[mike's documentation]: https://github.com/jimporter/mike +[native versioning support]: https://zensical.org/about/roadmap/#versioning +[overriding blocks]: ../customization.md#overriding-blocks +[theme extension]: ../customization.md#extending-the-theme diff --git a/docs/upgrade.md b/docs/upgrade.md index 234cfb9..032cdae 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -11,10 +11,6 @@ Remember that Zensical uses [semantic versioning], so if you are upgrading from one major release version to another, please carefully study the information provided on [versioning] of Zensical. -[changelog]: https://github.com/zensical/zensical/releases -[semantic versioning]: https://semver.org/ -[versioning]: #versioning - Once you are ready to proceed, follow the instructions according to how you installed Zensical: @@ -49,11 +45,14 @@ installed Zensical: uv pip show zensical ``` -[stick to previous versions]: https://docs.astral.sh/uv/concepts/projects/sync/#upgrading-locked-package-versions - ## Versioning Zensical follows [semantic versioning] and currently uses **0.0.x versioning** (alpha / development releases). We're approaching a **beta release**, after which we'll transition to **0.x** versioning. Once we reach a stable 1.0 release, the standard semantic versioning rules will apply more strictly. + +[changelog]: https://github.com/zensical/zensical/releases +[semantic versioning]: https://semver.org/ +[stick to previous versions]: https://docs.astral.sh/uv/concepts/projects/sync/#upgrading-locked-package-versions +[versioning]: #versioning diff --git a/docs/usage/build.md b/docs/usage/build.md index fe208e0..a5b80b6 100644 --- a/docs/usage/build.md +++ b/docs/usage/build.md @@ -8,11 +8,9 @@ tags: To build your documentation site, run `zensical build`. -[site_dir]: ../setup/basics.md#site_dir - ## Usage -```sh +``` sh zensical build [OPTIONS] ``` @@ -31,4 +29,5 @@ command. It supports the following options: | --strict | -s | Enable [strict mode]. | | --help | | Show a help message and exit. | +[site_dir]: ../setup/basics.md#site_dir [strict mode]: ../setup/validation.md#strict-mode diff --git a/docs/usage/cli.md b/docs/usage/cli.md index fde846e..bd9e6a8 100644 --- a/docs/usage/cli.md +++ b/docs/usage/cli.md @@ -3,12 +3,12 @@ icon: lucide/play tags: - Usage --- -# Usage +# Usage The general command line syntax for Zensical is: -```sh +``` sh zensical COMMAND [OPTIONS] [ARGS]... ``` diff --git a/docs/usage/new.md b/docs/usage/new.md index 117ff26..83a8407 100644 --- a/docs/usage/new.md +++ b/docs/usage/new.md @@ -8,7 +8,7 @@ tags: # New project You can create a new project from the command line using the `zensical new` -command. Provide a path as an argument to create the project in that directory, +command. Provide a path as an argument to create the project in that directory, or omit it to use the current working directory. If you specify a path that does not yet exist, it will be created for you. @@ -31,7 +31,7 @@ The directory structure created within the project directory consists of: ``` - The `zensical.toml` file serves as the project's configuration and can be -customized following the instructions in the [setup guides]. + customized following the instructions in the [setup guides]. - The `docs` directory contains your documentation's sources. The provided `index.md` and `markdown.md` files are included as starting points. The @@ -42,12 +42,8 @@ customized following the instructions in the [setup guides]. You can modify the workflow to suit your own CI/CD needs, or remove the folder entirely if you use a different platform. -[setup guides]: ../setup/basics.md -[docs_dir]: ../setup/basics.md#docs_dir -[publish your documentation]: ../publish-your-site.md -[GitHub Pages]: ../publish-your-site.md#github-pages - !!! note "Use in existing projects" + Note that the `zensical new` command will not overwrite existing files. It will return with an error if a `zensical.toml` file already exists. If other files to be written already exist then the command will simply @@ -58,3 +54,8 @@ customized following the instructions in the [setup guides]. You can run `zensical new --help` to get command-line help for the `new` command. Apart from this, the `new` command does not have any additional options at the moment. + +[docs_dir]: ../setup/basics.md#docs_dir +[GitHub Pages]: ../publish-your-site.md#github-pages +[publish your documentation]: ../publish-your-site.md +[setup guides]: ../setup/basics.md diff --git a/docs/usage/preview.md b/docs/usage/preview.md index 8cb380e..1ad6bdb 100644 --- a/docs/usage/preview.md +++ b/docs/usage/preview.md @@ -19,7 +19,7 @@ remote server. ## Usage -```sh +``` sh zensical serve [OPTIONS] ``` @@ -27,15 +27,15 @@ This starts a local web server that serves your documentation site on [localhost:8000][live preview]. As you make changes to source files, the browser will automatically reload the page you're on. - [live preview]: http://localhost:8000 - ## Options The `serve` command accepts the following options: -| Option | Short | Description | +| Option | Short | Description | | -------------------------- | ----- | --------------------------------------------- | | --config-file | -f | Path to the config file to use. | | --open | -o | Open preview in default browser | | --dev-addr <IP:PORT> | -a | IP address and port (default: localhost:8000) | | --help | | Show a help message and exit. | + +[live preview]: http://localhost:8000