### Install and Serve Zensical

Source: https://github.com/zensical/docs/blob/master/README.md

Installs the Zensical package using pip and starts the preview server.

```bash
pip install zensical
zensical serve
```

--------------------------------

### Install mkdocstrings with uv

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/mkdocstrings.md

Install the mkdocstrings Python handler using uv.

```bash
uv add mkdocstrings-python
```

--------------------------------

### Start Local Preview Server

Source: https://github.com/zensical/docs/blob/master/docs/usage/preview.md

Use this command to start a local web server for previewing your documentation. The browser will automatically reload as you make changes.

```sh
zensical serve [OPTIONS]
```

--------------------------------

### Install mkdocstrings with pip

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/mkdocstrings.md

Install the mkdocstrings Python handler using pip.

```bash
pip install mkdocstrings-python
```

--------------------------------

### Full Tag Icon and Identifier Configuration Example (mkdocs.yml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/tags.md

A comprehensive example demonstrating the configuration of default and specific tag icons, along with tag-to-identifier mappings in mkdocs.yml.

```yaml
theme:
  icon:
    tag:
      default: lucide/hash
      html: fontawesome/brands/html5
      js: fontawesome/brands/js
      css:  fontawesome/brands/css3
extra:
  tags:
    HTML5: html
    JavaScript: js
    CSS: css

```

--------------------------------

### Start Zensical Development Server

Source: https://github.com/zensical/docs/blob/master/docs/create-your-site.md

Run this command to start a local web server that rebuilds the site automatically on file changes. Access your site at http://localhost:8000.

```sh
zensical serve
```

--------------------------------

### Full Tag Icon and Identifier Configuration Example (zensical.toml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/tags.md

A comprehensive example demonstrating the configuration of default and specific tag icons, along with tag-to-identifier mappings in zensical.toml.

```toml
[project.theme.icon.tag]
default = "lucide/hash"
html = "fontawesome/brands/html5"
js = "fontawesome/brands/js"
css = "fontawesome/brands/css3"

[project.extra.tags]
HTML5 = "html"
JavaScript = "js"
CSS = "cs"

```

--------------------------------

### Install pandas and tabulate with uv

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Install the necessary Python packages for reading and processing tabular data using uv.

```sh
uv add pandas tabulate
```

--------------------------------

### Example Admonition

Source: https://github.com/zensical/docs/blob/master/docs/authoring/admonitions.md

Displays an 'example' type admonition, useful for providing illustrative examples.

```markdown
!!! example

    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.
```

--------------------------------

### Example Tag Identifier Mapping in mkdocs.yml

Source: https://github.com/zensical/docs/blob/master/docs/setup/tags.md

Example of mapping a 'Compatibility' tag to the 'compat' identifier in mkdocs.yml.

```yaml
extra:
  tags:
    Compatibility: compat

```

--------------------------------

### Definition List Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/lists.md

Illustrates the syntax for creating definition lists when the extension is enabled.

```markdown
`Lorem ipsum dolor sit amet`

:   Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
    tellus non sem sollicitudin, quis rutrum leo facilisis.

`Cras arcu libero`

:   Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
    ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

    Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
    Nam vulputate tincidunt fringilla.
    Nullam dignissim ultrices urna non auctor.

```

--------------------------------

### Example Tag Identifier Mapping in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/setup/tags.md

Example of mapping a 'Compatibility' tag to the 'compat' identifier in zensical.toml.

```toml
[project.extra.tags]
Compatibility = "compat"

```

--------------------------------

### Show installed Zensical version with uv

Source: https://github.com/zensical/docs/blob/master/docs/upgrade.md

Check the currently installed version of Zensical when managed by uv.

```bash
uv pip show zensical
```

--------------------------------

### Install Zensical on Windows with pip

Source: https://github.com/zensical/docs/blob/master/docs/get-started.md

Installs Zensical into a Python virtual environment on Windows using pip. Ensure Python and pip are installed. Note potential variations in the Python binary name.

```powershell
python -m venv .venv
.venv\Scripts\activate
pip install zensical
```

--------------------------------

### Install Mike Fork

Source: https://github.com/zensical/docs/blob/master/docs/setup/versioning.md

Install the Zensical fork of Mike directly from GitHub using pip. This method requires Git and is a temporary solution as the package is not published on PyPI.

```bash
pip install git+https://github.com/squidfunk/mike.git
```

--------------------------------

### Full Instant Preview Configuration Example (Zensical)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

A comprehensive Zensical TOML configuration for the preview extension, demonstrating how to include and exclude sources and targets for instant previews.

```toml
[[project.markdown_extensions.zensical.extensions.preview.configurations]]
sources.include = [...]
sources.exclude = [...]
targets.include = [...]
targets.exclude = [...]
```

--------------------------------

### Full Instant Preview Configuration Example (MkDocs)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

A comprehensive MkDocs YAML configuration for the preview extension, showing detailed settings for including and excluding sources and targets for instant previews.

```yaml
markdown_extensions:
  - material.extensions.preview:
      configurations:
        - sources: # (1)!
            include:
              - ...
            exclude:
              - ...
          targets: # (2)!
            include:
              - ...
            exclude:
              - ...

        1.  Sources specify the pages _on_ which instant previews should be enabled.
            If this setting is omitted, instant previews will be enabled on all
            pages. You can use patterns to include or exclude pages. Exclusion is
            evaluated on top of inclusion, so if a page is matched by both, it will
            be excluded.

            Note that you can define multiple items under the `configurations`
            setting, which allows to precisely control where instant previews are
            shown.

        2.  Targets specify the pages _to_ which instant previews should be enabled.
            This is the recommended way to enable instant previews.
```

--------------------------------

### Unordered List Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/lists.md

Demonstrates the syntax for creating nested unordered lists using '-', '*', or '+'.

```markdown
- 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.

```

--------------------------------

### Install Zensical on macOS with pip

Source: https://github.com/zensical/docs/blob/master/docs/get-started.md

Installs Zensical into a Python virtual environment on macOS using pip. Ensure Python and pip are installed.

```shell
python3 -m venv .venv
source .venv/bin/activate
pip install zensical
```

--------------------------------

### Install pandas and tabulate with pip

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Install the necessary Python packages for reading and processing tabular data using pip.

```sh
pip install pandas tabulate
```

--------------------------------

### Add Zensical as a development dependency with uv

Source: https://github.com/zensical/docs/blob/master/docs/get-started.md

Initializes a project with uv, adds Zensical as a development dependency, and prepares to run it. Requires uv to be installed.

```shell
uv init
uv add --dev zensical
uv run zensical
```

--------------------------------

### Command-Specific Zensical Help

Source: https://github.com/zensical/docs/blob/master/docs/usage/cli.md

How to get help for a particular Zensical command.

```bash
zensical <command> --help
```

--------------------------------

### Show installed Zensical version with pip

Source: https://github.com/zensical/docs/blob/master/docs/upgrade.md

Check the currently installed version of Zensical using pip.

```bash
pip show zensical
```

--------------------------------

### Example of Wide Annotation Tooltip

Source: https://github.com/zensical/docs/blob/master/docs/authoring/code-blocks.md

Demonstrates how annotations render with an increased tooltip width, allowing for more content.

```yaml
# (1)!
1. Muuuuuuuuuuuuuuuch more space for content
```

--------------------------------

### Install Zensical with Conda/Mamba

Source: https://github.com/zensical/docs/blob/master/docs/get-started.md

Use these commands to create a new environment named 'zensical', activate it, and install Zensical from the conda-forge channel. This method is applicable across macOS, Windows, and Linux.

```bash
conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical
```

--------------------------------

### Ordered List Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/lists.md

Shows how to create nested ordered lists. Numbers do not need to be consecutive and will be re-numbered on render.

```markdown
1.  Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
    sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
    nulla. Vivamus a pharetra leo.

    1.  Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
        quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
        ultricies libero efficitur sed.

    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

```

--------------------------------

### Build UI Themes

Source: https://github.com/zensical/docs/blob/master/docs/community/guides/develop.md

Installs Node.js dependencies and builds the UI themes. The build artifacts are automatically picked up by Zensical due to the symlink.

```bash
npm install
npm run build
```

--------------------------------

### Clone Zensical Repository

Source: https://github.com/zensical/docs/blob/master/docs/community/guides/develop.md

Clone the Zensical project from its GitHub repository to start development.

```bash
git clone https://github.com/zensical/zensical.git
```

--------------------------------

### Class Diagram Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/diagrams.md

Defines classes, their properties, methods, and relationships like inheritance and association. Use this to model the structure of your system.

```mermaid
classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()
  }
```

--------------------------------

### Example of Pre-filled GitHub Issue Title

Source: https://github.com/zensical/docs/blob/master/docs/setup/analytics.md

This shows an example of how the GitHub issue title will appear after the placeholders are replaced with actual page information. It helps visualize the feedback collection process.

```text
[Feedback] Setting up site analytics – /setup/setting-up-site-analytics/
```

--------------------------------

### State Diagram Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/diagrams.md

Use the 'mermaid' code block to create state diagrams that describe system behavior by decomposing it into states and transitions.

```mermaid
stateDiagram-v2
  state fork_state <<fork>>
    [*] --> fork_state
    fork_state --> State2
    fork_state --> State3

    state join_state <<join>>
    State2 --> join_state
    State3 --> join_state
    join_state --> State4
    State4 --> [*]
```

--------------------------------

### GitHub Actions Workflow for Zensical Deployment

Source: https://github.com/zensical/docs/blob/master/docs/publish-your-site.md

This YAML workflow automates the build and deployment of a Zensical site to GitHub Pages. It checks out the code, sets up Python, installs Zensical, builds the site, and uploads the artifacts for deployment. Ensure your repository branches (e.g., master, main) are correctly configured.

```yaml
name: Documentation
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/configure-pages@v5
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install zensical
      - run: zensical build --clean # (1)!
      - uses: actions/upload-pages-artifact@v4
        with:
          path: site
      - uses: actions/deploy-pages@v4
        id: deployment
```

--------------------------------

### MathJax Block Syntax Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/math.md

Render mathematical equations using block syntax enclosed in $$...$$ or \[...\] for display on separate lines.

```latex
$$
\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
$$
```

--------------------------------

### Configure Feedback Widget in mkdocs.yml

Source: https://github.com/zensical/docs/blob/master/docs/setup/analytics.md

Integrate the feedback widget by adding this configuration to your mkdocs.yml file. This example uses Google Analytics as the provider.

```yaml
extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: >-
            Thanks for your feedback! Help us improve this page by
            using our <a href=\"...\" target=\"_blank\" rel=\"noopener\">feedback form</a>.

```

--------------------------------

### Use a basic icon

Source: https://github.com/zensical/docs/blob/master/docs/authoring/icons-emojis.md

When emoji support is enabled, icons can be used like emojis by referencing their path. This example uses a FontAwesome icon.

```markdown
:fontawesome-regular-face-laugh-wink:

```

--------------------------------

### Build Documentation Site

Source: https://github.com/zensical/docs/blob/master/docs/usage/build.md

Run this command to generate the static site in the configured site directory. The default output directory is 'site'.

```sh
zensical build [OPTIONS]
```

--------------------------------

### GitLab CI Configuration for Zensical Deployment

Source: https://github.com/zensical/docs/blob/master/docs/publish-your-site.md

This `.gitlab-ci.yml` file configures GitLab CI to build and deploy a Zensical site to GitLab Pages. It uses a Python image, installs Zensical, builds the site, and specifies the publish directory. The deployment is triggered on commits to the default branch.

```yaml
pages:
  stage: deploy
  image: python:latest
  script:
    - pip install zensical
    - zensical build --clean # (1)!
  pages:
    publish: site # (2)!
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

--------------------------------

### General Zensical Help

Source: https://github.com/zensical/docs/blob/master/docs/usage/cli.md

How to access the main help documentation for Zensical.

```bash
zensical --help
```

--------------------------------

### Create a New Zensical Project

Source: https://github.com/zensical/docs/blob/master/docs/create-your-site.md

Use this command to bootstrap a new project in the current directory. It generates a standard project structure.

```sh
zensical new .
```

--------------------------------

### Enable Instant Prefetching (mkdocs.yml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Enable instant prefetching in mkdocs.yml by adding 'navigation.instant.prefetch' to the theme features, along with 'navigation.instant'. This improves perceived loading times by fetching pages on hover.

```yaml
theme:
  features:
    - navigation.instant
    - navigation.instant.prefetch
```

--------------------------------

### Package Metadata and Entry Point Configuration

Source: https://github.com/zensical/docs/blob/master/docs/customization.md

Defines package metadata, dependencies, and the theme entry point for Zensical discovery using pyproject.toml.

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-theme"
version = "0.1.0"
description = "My theme extension"
authors = [
  { name = "Jane Doe", email = "jane@example.com" }
]
license = "MIT"
requires-python = ">=3.9"
dependencies = ["zensical>=0.0.37"]

[tool.hatch.build.targets.wheel]
include = ["my_theme"]

[project.entry-points."mkdocs.themes"]
my_theme = "my_theme"
```

--------------------------------

### Enable GLightbox Extension

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/glightbox.md

Enable the GLightbox extension by adding its configuration to your zensical.toml or mkdocs.yml file.

```yaml
markdown_extensions:
  - zensical.extensions.glightbox
```

--------------------------------

### Create and Navigate to New Zensical Project

Source: https://github.com/zensical/docs/blob/master/docs/community/guides/create-a-reproduction.md

Use this command to create a new, minimal Zensical project for your reproduction. This ensures no existing customizations interfere with bug isolation.

```bash
zensical new reproduction
cd reproduction
```

--------------------------------

### Enable Instant Prefetching (zensical.toml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Enable instant prefetching in zensical.toml by adding 'navigation.instant.prefetch' alongside 'navigation.instant' to the theme features. This proactively fetches pages on hover.

```toml
[project.theme]
features = [
    "navigation.instant",
    "navigation.instant.prefetch"
]
```

--------------------------------

### Example of shadowed footnote definition warning

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

When `shadowed_footnotes` validation is enabled, Zensical will warn if a footnote definition like `[^id]: 1st definition` is repeated, as shown in the example with two definitions for `[^id]`.

```markdown
This footnote[^id] has two definitions.

[^id]: 1st definition
[^id]: 2nd definition

```

--------------------------------

### Example of shadowed link definition warning

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

When `shadowed_definitions` validation is enabled, Zensical will warn if a link definition like `[id]: https://example.com/shadowed` is repeated, as shown in the example with two definitions for `[id]`.

```markdown
This [reference][id] has two definitions.

[id]: https://example.com/shadowed
[id]: https://example.com

```

--------------------------------

### Publish New Version with Mike

Source: https://github.com/zensical/docs/blob/master/docs/setup/versioning.md

Publish a new version of your project documentation and update aliases using the 'mike deploy' command. Ensure your 'site_url' is explicitly set in your configuration.

```bash
mike deploy --push --update-aliases 0.1 latest
```

--------------------------------

### Enable GLightbox Extension

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/glightbox.md

Enable the GLightbox extension by adding its configuration to your zensical.toml or mkdocs.yml file.

```toml
[project.markdown_extensions.zensical.extensions.glightbox]
```

--------------------------------

### Build Static Zensical Site

Source: https://github.com/zensical/docs/blob/master/docs/create-your-site.md

Use this command to generate a static version of your documentation site. The output is a self-contained set of files ready for hosting.

```sh
zensical build
```

--------------------------------

### Markdown Table Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/data-tables.md

A standard Markdown table that can be made sortable with the Tablesort library.

```markdown
| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
```

--------------------------------

### Configure Definition and Task Lists

Source: https://github.com/zensical/docs/blob/master/docs/authoring/lists.md

Add these lines to your zensical.toml or mkdocs.yml to enable definition and task lists.

```toml
[project.markdown_extensions.def_list]
[project.markdown_extensions.pymdownx.tasklist]
custom_checkbox = true

```

```yaml
markdown_extensions:
  - def_list
  - pymdownx.tasklist:
      custom_checkbox: true

```

--------------------------------

### Recommended Package Directory Layout

Source: https://github.com/zensical/docs/blob/master/docs/customization.md

Illustrates the recommended file and directory structure for a packaged Zensical theme extension.

```sh
.\n├─ pyproject.toml
└─ my_theme/
   ├─ __init__.py #(1)!
   ├─ ... #(2)!
   ├─ main.html
   └─ mkdocs_theme.yml
```

--------------------------------

### Create a New Project

Source: https://github.com/zensical/docs/blob/master/docs/usage/new.md

Use the 'zensical new' command followed by the desired project directory path to create a new Zensical project. The command will create the directory if it doesn't exist.

```sh
zensical new [OPTIONS] PROJECT_DIRECTORY
```

--------------------------------

### MathJax Inline Syntax Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/math.md

Render mathematical expressions inline using $...$ or \(...\) within text.

```latex
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
```

--------------------------------

### Configure Documentation Directory

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

Set the relative path to the directory containing source files.

```toml
[project]
docs_dir = "docs"

```

--------------------------------

### Configure Include Directory in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Enable the use of `{% include %}` tags in pages by specifying a directory for Jinja2 templates relative to the project root in zensical.toml.

```toml
[project.markdown_extensions.zensical.extensions.macros]
include_dir = "includes"
```

--------------------------------

### JSON Code Block with Annotation

Source: https://github.com/zensical/docs/blob/master/docs/authoring/code-blocks.md

Example of a JSON code block where a code annotation is used within a string value.

```json
{
  "key": "value (1)"
}
```

--------------------------------

### Use a basic emoji

Source: https://github.com/zensical/docs/blob/master/docs/authoring/icons-emojis.md

Integrate emojis into Markdown by placing their shortcodes between two colons. This example uses the 'smile' emoji.

```markdown
:smile:

```

--------------------------------

### Enable Instant Navigation Progress Indicator (MkDocs)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Configure MkDocs theme features to enable the progress indicator for instant navigation. This is an alternative to the Zensical TOML configuration.

```yaml
theme:
  features:
    - navigation.instant
    - navigation.instant.progress
```

--------------------------------

### Referencing a Packaged Theme in mkdocs.yml

Source: https://github.com/zensical/docs/blob/master/docs/customization.md

Specifies the name of a locally installed or PyPI-published theme extension in the MkDocs configuration file.

```yaml
theme:
  name: my_theme
```

--------------------------------

### Referencing a Packaged Theme in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/customization.md

Specifies the name of a locally installed or PyPI-published theme extension in the Zensical configuration file.

```toml
[project.theme]
name = "my_theme"
```

--------------------------------

### Enable Keys Extension

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown-extensions.md

Enable the Keys extension to render keyboard keys and combinations. Use either zensical.toml or mkdocs.yml.

```toml
[project.markdown_extensions.pymdownx.keys]

```

```yaml
markdown_extensions:
  - pymdownx.keys

```

--------------------------------

### Define Abbreviations in Markdown

Source: https://github.com/zensical/docs/blob/master/docs/authoring/tooltips.md

Define abbreviations using a special Markdown syntax starting with '*' followed by the term in brackets and its definition.

```markdown
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

```

--------------------------------

### Entity-Relationship Diagram Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/diagrams.md

Illustrates entities and their relationships, specifying cardinality. Useful for database schema design and understanding data interactions.

```mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  LINE-ITEM {
    string name
    int pricePerUnit
  }
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

--------------------------------

### Configure Jinja2 Comment Start String in YAML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Set a custom opening delimiter for Jinja2 comments in mkdocs.yml. This changes the default `{#` to `<#`.

```yaml
markdown_extensions:
  - zensical.extensions.macros:
      j2_comment_start_string: "<#"

```

--------------------------------

### Configure Jinja2 Comment Start String in TOML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Set a custom opening delimiter for Jinja2 comments in zensical.toml. This changes the default `{#` to `<#`.

```toml
    [project.markdown_extensions.zensical.extensions.macros]
    j2_comment_start_string = "<#"

```

--------------------------------

### URL Format with `use_directory_urls = true`

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

Illustrates URL generation when directory URLs are enabled.

```text
Source file      | Generated File     | URL Format
---------------- | ------------------ | -------------------
index.md         | index.html         | /
usage.md         | usage.html         | /usage/
about/license.md | about/license.html | /about/license/

```

--------------------------------

### Enable Instant Navigation (zensical.toml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Enable instant navigation in zensical.toml by adding 'navigation.instant' to the theme features. This allows for XHR-based navigation without full page reloads.

```toml
[project.theme]
features = [
    "navigation.instant"
]
```

--------------------------------

### Configure Emoji Generator for Emoji Extension

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown-extensions.md

Configure the emoji_generator option for the Emoji Markdown extension. This example sets the generator to output SVGs.

```toml
[project.markdown_extensions.pymdownx.emoji]
emoji_generator = "zensical.extensions.emoji.to_svg"

```

```yaml
markdown_extensions:
  - pymdownx.emoji:
      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg

```

--------------------------------

### Configure Emoji Index for Emoji Extension

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown-extensions.md

Configure the emoji_index option for the Emoji Markdown extension. This example sets the index to use Twemoji.

```toml
[project.markdown_extensions.pymdownx.emoji]
emoji_index = "zensical.extensions.emoji.twemoji"

```

```yaml
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:zensical.extensions.emoji.twemoji

```

--------------------------------

### Project Structure for Custom Icons

Source: https://github.com/zensical/docs/blob/master/docs/setup/logo-and-icons.md

Illustrates the directory structure required for custom icons, including the `.icons` folder within the `custom_dir`.

```sh
. 
├─ overrides/ 
│  └─ .icons/ 
│     └─ bootstrap/ 
│        └─ *.svg 
└─ zensical.toml
```

```sh
. 
├─ overrides/ 
│  └─ .icons/ 
│     └─ bootstrap/ 
│        └─ *.svg 
└─ mkdocs.yml
```

--------------------------------

### Example of invalid link warning

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

When `invalid_links` validation is enabled, Zensical will warn if a link like `[this page]: non-existent.md` points to a page that does not exist.

```markdown
Oh no, [this page] does not exit.

[this page]: non-existent.md

```

--------------------------------

### Example of Unused Link Definition

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

This Markdown snippet shows an unused link definition. The build output will include a warning about this unused definition.

```markdown
[id]: https://example.com
```

--------------------------------

### Configure mkdocstrings in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/mkdocstrings.md

Configure the mkdocstrings Python handler in zensical.toml, specifying inventories and source paths.

```toml
[project.plugins.mkdocstrings.handlers.python]
inventories = ["https://docs.python.org/3/objects.inv"]
paths = ["src"]

[project.plugins.mkdocstrings.handlers.python.options]
docstring_style = "google"
inherited_members = true
show_source = false
```

--------------------------------

### Configure Documentation Directory (YAML)

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

Set the relative path to the directory containing source files.

```yaml
docs_dir: docs

```

--------------------------------

### Example of Unresolved Footnote

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

This Markdown snippet demonstrates an unresolved footnote reference. The build output will show a warning indicating the unresolved footnote.

```markdown
This is an unresolved footnote[^id].
```

--------------------------------

### Configure Site Output Directory

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

Set the relative path to the directory where the site will be written.

```toml
[project]
site_dir = "site"

```

--------------------------------

### Example of Unresolved Reference

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

This Markdown snippet demonstrates an unresolved link reference. The build output will show a warning indicating the unresolved reference.

```markdown
This is an [unresolved reference][id].
```

--------------------------------

### Enable Instant Navigation (mkdocs.yml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Enable instant navigation in mkdocs.yml by adding 'navigation.instant' to the theme features. This enhances user experience by avoiding full page reloads.

```yaml
theme:
  features:
    - navigation.instant
```

--------------------------------

### Configure Automatic Instant Previews (Zensical)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Use Zensical's Markdown extension to automatically enable instant previews on specified pages or sections. This configuration targets specific files and directories for preview functionality.

```toml
[project.markdown_extensions.zensical.extensions.preview]
configurations = [
    { targets.include = [
        "customization.md",
        "setup/extensions/*"
    ]}
]
```

--------------------------------

### Define custom CSS for icons

Source: https://github.com/zensical/docs/blob/master/docs/authoring/icons-emojis.md

Add custom CSS classes to icons for styling. This example defines a 'youtube' class with a specific color.

```css
.youtube {
  color: #EE0F0F;
}

```

--------------------------------

### Link UI Dist Directory on Windows (cmd.exe)

Source: https://github.com/zensical/docs/blob/master/docs/community/guides/develop.md

Creates a symbolic link for the UI dist directory in the Zensical project templates on Windows using cmd.exe. Requires permissions to create symbolic links.

```bash
git clone https://github.com/zensical/ui.git
mklink zensical\python\zensical\templates ui\dist
```

--------------------------------

### Upgrade Zensical with pip

Source: https://github.com/zensical/docs/blob/master/docs/upgrade.md

Use this command to upgrade Zensical when installed via pip. It forces a reinstall to ensure the latest version is applied.

```bash
pip install --upgrade --force-reinstall zensical
```

--------------------------------

### Enable Sticky Navigation Tabs (TOML)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Add 'navigation.tabs.sticky' alongside 'navigation.tabs' in zensical.toml to make navigation tabs sticky.

```toml
[project.theme]
features = [
    "navigation.tabs",
    "navigation.tabs.sticky"
]
```

--------------------------------

### Configure Jinja2 Variable Start String in YAML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Set a custom opening delimiter for Jinja2 variable expressions in mkdocs.yml. This changes the default `{{` to `<<`.

```yaml
markdown_extensions:
  - zensical.extensions.macros:
      j2_variable_start_string: "<<"

```

--------------------------------

### Basic Zensical Project Structure

Source: https://github.com/zensical/docs/blob/master/docs/create-your-site.md

This is the default directory and file structure created by the `zensical new` command.

```sh
. 
├─ .github/workflows
│  └─ docs.yml
├─ docs/
│  ├─ index.md
│  └─ markdown.md
└─ zensical.toml
```

--------------------------------

### Configure YouTube Color Scheme in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/setup/colors.md

Sets the project's color scheme to 'youtube' and includes the custom CSS file.

```toml
[project]
theme.palette.scheme = "youtube"
extra_css = ["stylesheets/extra.css"]
```

--------------------------------

### Configure Jinja2 Variable Start String in TOML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Set a custom opening delimiter for Jinja2 variable expressions in zensical.toml. This changes the default `{{` to `<<`.

```toml
    [project.markdown_extensions.zensical.extensions.macros]
    j2_variable_start_string = "<<"

```

--------------------------------

### Configure Jinja2 Block Start String in YAML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Set a custom opening delimiter for Jinja2 block tags in mkdocs.yml. This changes the default `{%` to `<%`.

```yaml
markdown_extensions:
  - zensical.extensions.macros:
      j2_block_start_string: "<em class=\"language-yaml\">%</em>"

```

--------------------------------

### Generic Grid with Content Tabs

Source: https://github.com/zensical/docs/blob/master/docs/authoring/grids.md

Demonstrates creating a generic grid that contains content tabs, each with different list types. This is useful for organizing related but distinct content sections.

```html
<div class="grid" markdown>

=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci

``` title="Content tabs"
=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci
```

</div>
```

--------------------------------

### Configure Jinja2 Block Start String in TOML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Set a custom opening delimiter for Jinja2 block tags in zensical.toml. This changes the default `{%` to `<%`.

```toml
    [project.markdown_extensions.zensical.extensions.macros]
    j2_block_start_string = "<em class=\"language-toml\">%</em>"

```

--------------------------------

### Enable Back-to-top Button (MkDocs)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Configure MkDocs by adding 'navigation.top' to the 'theme.features' list in your mkdocs.yml file to enable the back-to-top button.

```yaml
theme:
  features:
    - navigation.top
```

--------------------------------

### KaTeX Configuration YAML

Source: https://github.com/zensical/docs/blob/master/docs/authoring/math.md

Configure MkDocs to include KaTeX JavaScript and CSS, and enable Arithmatex markdown extension.

```yaml
markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/katex.js
  - https://unpkg.com/katex@0/dist/katex.min.js
  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

extra_css:
  - https://unpkg.com/katex@0/dist/katex.min.css
```

--------------------------------

### Add Social Link with Custom Name (MkDocs)

Source: https://github.com/zensical/docs/blob/master/docs/setup/footer.md

Configure a social media link with a custom 'name' property for accessibility. This example uses Mastodon.

```yaml
extra:
  social:
    - icon: fontawesome/brands/mastodon
      link: https://fosstodon.org/@squidfunk
      name: Zensical on Mastodon

```

--------------------------------

### Apply an animation class to an icon

Source: https://github.com/zensical/docs/blob/master/docs/authoring/icons-emojis.md

Add a custom CSS class to an icon shortcode to apply animations. This example applies the 'heart' animation class.

```markdown
:octicons-heart-fill-24:{ .heart }

```

--------------------------------

### Enable Grid Configuration in MkDocs

Source: https://github.com/zensical/docs/blob/master/docs/authoring/grids.md

Add these lines to your mkdocs.yml file to enable grid functionality.

```yaml
markdown_extensions:
  - attr_list
  - md_in_html

```

--------------------------------

### Define CSS animation for icons

Source: https://github.com/zensical/docs/blob/master/docs/authoring/icons-emojis.md

Define CSS keyframe animations and apply them to icons using custom classes. This example creates a 'heart' animation.

```css
@keyframes heart {
  0%, 40%, 80%, 100% {
    transform: scale(1);
  }
  20%, 60% {
    transform: scale(1.15);
  }
}
.heart {
  animation: heart 1000ms infinite;
}

```

--------------------------------

### Sequence Diagram Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/diagrams.md

Use the 'mermaid' code block to create sequence diagrams illustrating interactions between objects or actors. Autonumbering can be enabled for clarity.

```mermaid
sequenceDiagram
  autonumber
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

--------------------------------

### Flowchart Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/diagrams.md

Use the 'mermaid' code block to create flowcharts representing workflows or processes. Nodes are connected by edges to show the order of steps.

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

--------------------------------

### Specify Additional Paths to Watch

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

List additional file or directory paths to monitor for changes during preview.

```toml
[project]
watch = ["data.csv", "fragments"]

```

--------------------------------

### Set Page Status (YAML)

Source: https://github.com/zensical/docs/blob/master/docs/authoring/frontmatter.md

Associate a status identifier with a page by adding the `status` property to the front matter. Example uses a `new` identifier.

```yaml
extra:
  status:
    new: Recently added
```

--------------------------------

### Configure Mike Provider

Source: https://github.com/zensical/docs/blob/master/docs/setup/versioning.md

Enable the version selector by setting the 'provider' option to 'mike' in your Zensical or MkDocs configuration file.

```toml
[project.extra.version]
provider = "mike"
```

```yaml
extra:
  version:
    provider: mike
```

--------------------------------

### Set Page Status (TOML)

Source: https://github.com/zensical/docs/blob/master/docs/authoring/frontmatter.md

Associate a status identifier with a page by adding the `status` property to the front matter. Example uses a `new` identifier.

```toml
[project.extra.status]
new = "Recently added"
```

--------------------------------

### Configure Site URL

Source: https://github.com/zensical/docs/blob/master/docs/setup/versioning.md

Set the 'site_url' in your Zensical or MkDocs configuration. A trailing slash is recommended for correct URL generation when publishing documentation to subdirectories.

```toml
[project]
site_url = "https://docs.example.com/"  # Trailing slash is recommended
```

```yaml
site_url: 'https://docs.example.com/'  # Trailing slash is recommended
```

--------------------------------

### Enable Highlight and SuperFences Extensions

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown-extensions.md

Enable the Highlight and SuperFences markdown extensions in mkdocs.yml.

```yaml
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences # (1)!
```

--------------------------------

### Set Content Area Max Width

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Customize the maximum width of the content area by adding a CSS rule to 'extra.css'. This example sets the max-width to 1440px.

```css
.md-grid {
  max-width: 1440px; /* (1)! */
}
```

--------------------------------

### Example of unused footnote warning

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

When `unused_footnotes` validation is enabled, Zensical will warn if a footnote definition like `[^id]: This footnote is never referenced.` is not used in the document.

```markdown
[^id]: This footnote is never referenced.

```

--------------------------------

### Enable Highlight and SuperFences Extensions

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown-extensions.md

Enable the Highlight and SuperFences markdown extensions in zensical.toml.

```toml
[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
[project.markdown_extensions.pymdownx.superfences]
```

--------------------------------

### Configure Jinja2 Extensions in TOML

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Specify a list of Jinja2 extensions to load in zensical.toml. Includes the `jinja2.ext.do` extension.

```toml
    [project.markdown_extensions.zensical.extensions.macros]
    j2_extensions = ["jinja2.ext.do"]

```

--------------------------------

### Add Social Link with Custom Name

Source: https://github.com/zensical/docs/blob/master/docs/setup/footer.md

Configure a social media link with a custom 'name' property for accessibility. This example uses the X (Twitter) platform.

```toml
[[project.extra.social]]
icon = "fontawesome/brands/x"
link = "https://x.com/zensical"
name = "Zensical on X"

```

--------------------------------

### Apply a CSS class to an icon

Source: https://github.com/zensical/docs/blob/master/docs/authoring/icons-emojis.md

Add a custom CSS class to an icon shortcode to apply styles like color. This example applies the 'youtube' class.

```markdown
:fontawesome-brands-youtube:{ .youtube }

```

--------------------------------

### Configure Site Output Directory (YAML)

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

Set the relative path to the directory where the site will be written.

```yaml
site_dir: site

```

--------------------------------

### Enable Sticky Navigation Tabs (YAML)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Add 'navigation.tabs.sticky' alongside 'navigation.tabs' in mkdocs.yml to make navigation tabs sticky.

```yaml
theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky
```

--------------------------------

### Configure Slugify Function (mkdocs.yml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown.md

Customize the slugify function for Table of Contents identifiers using YAML syntax in mkdocs.yml. This example applies 'pymdownx.slugs.slugify' with lowercase conversion.

```yaml
markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
```

--------------------------------

### Configure Slugify Function (zensical.toml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/python-markdown.md

Customize the slugify function for Table of Contents identifiers by specifying the object and keywords in zensical.toml. This example uses 'pymdownx.slugs.slugify' with lowercase conversion.

```toml
[project.markdown_extensions.toc.slugify]
object = "pymdownx.slugs.slugify"
kwds = { case = "lower" }
```

--------------------------------

### Enable Admonitions and Related Features

Source: https://github.com/zensical/docs/blob/master/docs/authoring/admonitions.md

Add these lines to your configuration file to enable admonitions, collapsible details, and superfences for nesting content.

```toml
[project.markdown_extensions.admonition]
[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.pymdownx.superfences]

```

--------------------------------

### Example of invalid link anchor warning

Source: https://github.com/zensical/docs/blob/master/docs/setup/validation.md

When `invalid_link_anchors` validation is enabled, Zensical will warn if a link like `[this section]: page.md#non-existent` points to an anchor that does not exist on the specified page.

```markdown
Oh no, [this section] does not exit.

[this section]: page.md#non-existent

```

--------------------------------

### Basic Python Code Block

Source: https://github.com/zensical/docs/blob/master/docs/authoring/code-blocks.md

Demonstrates a basic Python code block with syntax highlighting.

```py
import tensorflow as tf

```

--------------------------------

### Add Line Numbers to Python Code Block

Source: https://github.com/zensical/docs/blob/master/docs/authoring/code-blocks.md

Illustrates adding line numbers to a Python code block, starting from line 1. This helps in referencing specific lines.

```py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

--------------------------------

### Configure Additional Macros Modules in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Load additional Python modules (pluglets) for macros by listing their names under the 'modules' option in zensical.toml.

```toml
[project.markdown_extensions.zensical.extensions.macros]
modules = ["my_package.macros"]
```

--------------------------------

### Configure Repository Name in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/setup/repository.md

Customize the displayed repository name in zensical.toml if Zensical cannot infer it correctly from the URL.

```toml
[project]
repo_name = "zensical/zensical"

```

--------------------------------

### Configure Include Directory in mkdocs.yml

Source: https://github.com/zensical/docs/blob/master/docs/setup/extensions/macros.md

Enable the use of `{% include %}` tags in pages by specifying a directory for Jinja2 templates relative to the project root in mkdocs.yml.

```yaml
markdown_extensions:
  - zensical.extensions.macros:
      include_dir: includes
```

--------------------------------

### Set Robots Meta Tag from Front Matter

Source: https://github.com/zensical/docs/blob/master/docs/authoring/frontmatter.md

Specify the `robots` property in the front matter to control search engine indexing for a page, using the `robots: noindex, nofollow` example.

```yaml
---
robots: noindex, nofollow
---

# Page title
...
```

--------------------------------

### Complex Card Grid with Icons and Links

Source: https://github.com/zensical/docs/blob/master/docs/authoring/grids.md

This example demonstrates a more advanced card grid, incorporating icons, links, and dividers within list items. Ensure the surrounding div has the 'markdown' attribute.

```html
<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`zensical`](#) with [`pip`](#) and get up
    and running in minutes

    [:octicons-arrow-right-24: Getting started](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

    Focus on your content and generate a responsive and searchable static site

    [:octicons-arrow-right-24: Reference](#)

-   :material-format-font:{ .lg .middle } __Made to measure__

    ---

    Change the colors, fonts, language, icons, logo and more with a few lines

    [:octicons-arrow-right-24: Customization](#)

-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__

    ---

    Zensical is licensed under MIT and available on [GitHub]

    [:octicons-arrow-right-24: License](#)

</div>
```

--------------------------------

### Markdown Task List Example

Source: https://github.com/zensical/docs/blob/master/docs/authoring/lists.md

Demonstrates how to define an unchecked or checked checkbox using `[ ]` or `[x]` respectively within an unordered list. This syntax renders interactive checkboxes in supported Markdown renderers.

```markdown
- [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
```

--------------------------------

### Link UI Dist Directory on Windows (Powershell)

Source: https://github.com/zensical/docs/blob/master/docs/community/guides/develop.md

Creates a symbolic link for the UI dist directory in the Zensical project templates on Windows using Powershell. Requires permissions to create symbolic links.

```powershell
git clone https://github.com/zensical/ui.git
New-Item -Type SymbolicLink -Path zensical\python\zensical\templates -Target ui\dist
```

--------------------------------

### Enable Formatting Extensions in zensical.toml

Source: https://github.com/zensical/docs/blob/master/docs/authoring/formatting.md

Add these lines to your zensical.toml file to enable support for highlighting, keyboard keys, sub/superscripts, and strikethrough text.

```toml
[project.markdown_extensions.pymdownx.caret]
[project.markdown_extensions.pymdownx.keys]
[project.markdown_extensions.pymdownx.mark]
[project.markdown_extensions.pymdownx.tilde]

```

--------------------------------

### Enable Code Annotations Globally (mkdocs.yml)

Source: https://github.com/zensical/docs/blob/master/docs/authoring/code-blocks.md

Add this to your mkdocs.yml configuration to enable code annotations globally.

```yaml
theme:
  features:
    - content.code.annotate # (1)!

```

--------------------------------

### Enable Code Annotations Globally (zensical.toml)

Source: https://github.com/zensical/docs/blob/master/docs/authoring/code-blocks.md

Add this to your zensical.toml configuration to enable code annotations globally.

```toml
[project.theme]
feature = [
  "content.code.annotate" # (1)!
]

```

--------------------------------

### Configure Automatic Instant Previews (MkDocs)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Configure the Material theme's preview extension in MkDocs to enable instant previews on specific pages. This YAML configuration defines which pages should have instant previews enabled.

```yaml
markdown_extensions:
  - material.extensions.preview:
      configurations:
        - targets:
            include:
              - customization.md
              - setup/extensions/*
```

--------------------------------

### Enable Grid Configuration in Zensical

Source: https://github.com/zensical/docs/blob/master/docs/authoring/grids.md

Add these lines to your zensical.toml file to enable grid functionality.

```toml
[project.markdown_extensions.attr_list]
[project.markdown_extensions.md_in_html]

```

--------------------------------

### Specify Additional Paths to Watch (YAML)

Source: https://github.com/zensical/docs/blob/master/docs/setup/basics.md

List additional file or directory paths to monitor for changes during preview.

```yaml
watch:
  - data.csv
  - fragments

```

--------------------------------

### Enable Navigation Expansion (TOML)

Source: https://github.com/zensical/docs/blob/master/docs/setup/navigation.md

Add 'navigation.expand' to your project's theme features in zensical.toml to automatically expand subsections in the sidebar.

```toml
[project.theme]
features = [
    "navigation.expand"
]
```

--------------------------------

### Set Logo from Bundled Icon (zensical.toml)

Source: https://github.com/zensical/docs/blob/master/docs/setup/logo-and-icons.md

Configure the project to use one of the theme's bundled icons as the logo. Find suitable icons from the available sets.

```toml
[project.theme.icon]
logo = "lucide/smile"
```

--------------------------------

### KaTeX Configuration JavaScript

Source: https://github.com/zensical/docs/blob/master/docs/authoring/math.md

Configure KaTeX to render math in the document body, supporting various delimiters. Integrates with instant navigation.

```js
document$.subscribe(({ body }) => { // (1)!
  renderMathInElement(body, {
    delimiters: [
      { left: "$$",  right: "$$",  display: true },
      { left: "$",   right: "$",   display: false },
      { left: "\\(", right: "\\)", display: false },
      { left: "\\[", right: "\\]", display: true }
    ],
  })
})
```