Zensical

https://github.com/zensical/docs
Admin
Zensical is a tool for managing and serving documentation with a preview server for easy local...
Tokens:103,545
Snippets:1,065
Trust Score:6.6
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Zensical and run preview server

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

Install Zensical and start the local preview server. Run these commands in order after cloning the repository.

```bash
pip install zensical
```

```bash
zensical serve
```

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

### Install theme from PyPI

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

Installs the published theme package from PyPI, allowing users to install it with the package name.

```bash
pip install my-theme
```

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

### Install Zensical-compatible mike fork

Source: https://github.com/zensical/docs/blob/master/docs/compatibility/mkdocs/mike.md

Use pip to install the fork directly from GitHub. This requires git to be installed on your system.

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

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

### Start the Zensical preview server with zensical serve

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

Starts a web server that automatically rebuilds the site when source files change. Point your browser to http://localhost:8000 to see the live preview.

```sh
zensical serve
```

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

### Install theme locally with pip

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

Installs the current package in development mode, making it available for local testing.

```bash
pip install .
```

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

### Clone the Zensical repository

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

Clones the Zensical repository (or your own fork) to start development. Run this before installing dependencies with uv sync.

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

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

### Install mkdocstrings-python

Source: https://github.com/zensical/docs/blob/master/docs/compatibility/mkdocs/plugins.md

Install the mkdocstrings-python package, which is required for the mkdocstrings plugin.

```sh
pip install mkdocstrings-python
```

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

### Install Zensical with pip on Windows

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

Sets up a Python virtual environment and installs Zensical using pip on Windows. Run these commands in a Command Window. Depending on your Python installation, you may need to use a different binary name such as `python3` or use `py -3`.

```ps1
python -m venv .venv  # (1)!
.venv\Scripts\activate
pip install zensical
```

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

### Admonition type: example

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

Renders an example admonition.

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

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

### Quick start: catalog directives and variant build commands

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

Quick start workflow: a Markdown page using @if/@elif/@use/@var directives, the included source file, and commands to build the default variant or serve a named variant via ZENSICAL_VARIANT. ZENSICAL_VARIANT overrides default_variant when both are set.

```markdown
# Deploy Acme Platform

@if deployment = cloud

    ## Set up the cloud deployment

    Create an Acme Platform workspace. The service is managed for you.

@elif deployment = self-hosted

    ## Set up the self-hosted deployment

    Provision a Linux host and install the server package.

@use shared/deployment-overview.md

This guide covers the **@var{deployment}** deployment.
```

```markdown
Read the deployment overview before configuring the service.
```

```sh
zensical build
```

```sh
ZENSICAL_VARIANT=self-hosted zensical serve
```

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

### Enable blog plugin in zensical.toml or mkdocs.yml

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

Enable the blog plugin in either the Zensical TOML configuration or the MkDocs YAML configuration. These are equivalent alternatives for the same setup step.

```toml
[project.plugins.blog]

```

```yaml
plugins:
  - blog

```

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

### Show installed Zensical version with uv

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

Displays the currently installed version of Zensical when using uv.

```bash
uv pip show zensical
```

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

### Full configuration example for instant previews in mkdocs.yml

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

Complete configuration for the preview extension in mkdocs.yml, showing sources and targets with include/exclude patterns. Sources specify pages on which previews are enabled; targets specify pages to which previews are enabled.

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

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

### Install theme content on Windows (cmd.exe)

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

Clones the UI repository and creates a symbolic link using mklink on Windows cmd.exe. Requires permission to create symbolic links.

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

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

### Install Zensical with pip on macOS

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

Sets up a Python virtual environment and installs Zensical using pip on macOS. Run these commands in a terminal window.

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

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

### Example catalog.toml with variables and variants

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

Example catalog.toml file that declares the default variant, variable values, and named variants for the documentation build contexts.

```toml
default_variant = "cloud"

[variables.deployment]
values = ["cloud", "self-hosted"]

[variables.authentication]
values = ["single-sign-on", "local"]

[variants.cloud]
deployment = "cloud"
authentication = "single-sign-on"

[variants.self-hosted]
deployment = "self-hosted"
authentication = "local"
```

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

### Create a new minimal Zensical project

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

Creates a fresh Zensical project named 'reproduction' and changes into its directory. Use this as the starting point for a minimal reproduction that avoids any customizations from an existing project.

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

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

### Example mkdocs.yml plugin configuration

Source: https://github.com/zensical/docs/blob/master/docs/compatibility/mkdocs/plugins.md

Shows a typical mkdocs.yml plugin configuration with the tags and minify plugins, where minify_html is enabled. This configuration can remain unchanged when migrating to Zensical.

```yaml
plugins:
  - tags
  - minify:
      minify_html: true
```

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

### Install theme content on macOS/Linux

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

Clones the UI repository and creates a symbolic link so the dist directory appears under python/zensical/templates. Use this on macOS and Linux.

```bash
git clone https://github.com/zensical/ui.git
ln -s ../../../ui/dist zensical/python/zensical/templates
```

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

### Example directory structure for offline polyfill

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

Shows the expected directory layout where the polyfill asset is placed in a js/ folder inside the docs/ directory.

```text
.
├── docs
│   ├── index.md
│   └── js
│       └── iframe-worker-shim.js
└── zensical.toml

```

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

### Install markdown-exec with ANSI support

Source: https://github.com/zensical/docs/blob/master/docs/compatibility/mkdocs/plugins.md

Install the markdown-exec plugin with the ansi extra using pip. Required before using the plugin.

```sh
pip install "markdown-exec[ansi]"
```

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

### Build Zensical with maturin

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

Builds Zensical after the development setup is complete. Run this in the project directory.

```bash
uv run maturin develop
```

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

### Document environment with pip freeze

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

Records the packages installed in the virtual environment into requirements.txt when using pip. Run this in the reproduction project to document the environment.

```bash
pip freeze > requirements.txt
```

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

### Install theme content on Windows (PowerShell)

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

Clones the UI repository and creates a symbolic link using New-Item on Windows PowerShell. Requires permission 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
```

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

### Example: assign 'compat' identifier to Compatibility tag

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

Example of associating the tag 'Compatibility' with the identifier 'compat'. Identifiers can be reused between tags to assign groups of tags the same icon.

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

```

```yaml
extra:
  tags:
    Compatibility: compat

```

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

### Document environment with uv pip freeze

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

Records the packages installed in the virtual environment into requirements.txt when using uv. Run this in the reproduction project to document the environment.

```bash
uv pip freeze > requirements.txt
```

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

### Example: assign icons to tags in zensical.toml and mkdocs.yml

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

Complete example showing how to assign icons to tags via identifiers. The default icon is lucide/hash, and specific icons are set for html, js, and css identifiers. Tags HTML5, JavaScript, and CSS are mapped to those identifiers.

```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 = "css"

```

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

```

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

### Build the themes with npm

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

Installs dependencies and builds the themes (modern and classic) in the UI repository. The dist directory is symlinked into the Zensical project, so new runs pick up the build artifacts.

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

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

### Configuring Markdown Extensions in mkdocs.yml

Source: https://github.com/zensical/docs/blob/master/docs/compatibility/markdown/index.md

Example configuration for enabling Markdown extensions in mkdocs.yml. It shows the supported extensions, such as admonition and pymdownx.superfences.

```yaml
markdown_extensions:
  - admonition
  - pymdownx.superfences

```

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

### External Link Navigation in mkdocs.yml

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

Navigation items can be URLs; this example links to the GitHub repository for the Zensical Documentation.

```yaml
nav:
  - GitHub Repo: https://github.com/zensical/docs

```

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

### Enable instant prefetching in mkdocs.yml

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

Adds the navigation.instant.prefetch feature to the theme configuration in mkdocs.yml. This experimental feature starts fetching a page when the user hovers over a link, reducing perceived loading time.

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

```

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

### Enable instant prefetching in zensical.toml

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

Adds the navigation.instant.prefetch feature to the theme configuration in zensical.toml. This experimental feature starts fetching a page when the user hovers over a link, reducing perceived loading time.

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

```

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

### State diagram example with Markdown source and Mermaid output

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

Shows the Markdown source and rendered output for a Mermaid state diagram with fork and join states. Use this to describe system behavior as states and transitions.

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

```mermaid
``` 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 --> [*]
```
```

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

### Full configuration example for instant previews in zensical.toml

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

Complete configuration for the preview extension in zensical.toml, showing sources and targets with include/exclude patterns. Sources specify pages on which previews are enabled; targets specify pages to which previews are enabled.

```toml
[[project.markdown_extensions.zensical.extensions.preview.configurations]]
sources.include = [] # (1)!
sources.exclude = []
targets.include = [] # (2)!
targets.exclude = []
```

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

### Install Zensical with uv

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

Initializes a new project with uv, adds Zensical as a development dependency, and runs it. Note that you need to use `uv run` or activate the project's virtual environment manually when using Zensical as a project dependency.

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

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

### Install Zensical with conda/Mamba on macOS

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

Creates and activates a new conda environment named 'zensical' with Python 3.14, then installs Zensical from conda-forge. Use this on macOS when you prefer conda/Mamba over the official PyPI installation.

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

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

### Initialize a new project with zensical new

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

The command syntax for creating a new project. Provide an optional project directory path.

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

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

### Show installed Zensical version with pip

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

Displays the currently installed version of Zensical when using pip.

```bash
pip show zensical
```

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

### Example markdown for shadowed_footnotes

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

Markdown example that triggers the shadowed_footnotes warning: a footnote reference with two definitions.

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

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

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

### Example markdown for shadowed_definitions

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

Markdown example that triggers the shadowed_definitions warning: a link reference with two definitions.

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

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

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

### Add blog entry point to explicit navigation in zensical.toml or mkdocs.yml

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

Add the blog entry point to explicit navigation in either the Zensical TOML configuration or the MkDocs YAML configuration. Only the blog index page is listed, not individual posts.

```toml
[project]
nav = [
  "index.md",
  { "Blog" = ["blog/index.md"] },
]

```

```yaml
nav:
  - index.md
  - Blog:
      - blog/index.md

```

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

### Example markdown for unused_footnotes

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

Markdown example that triggers the unused_footnotes warning: a footnote definition that is never referenced.

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

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

### Enable MathJax with configuration files

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

Adds MathJax support by creating a JavaScript file that configures MathJax and integrates with instant navigation, then registers the script and the MathJax CDN in the project's configuration. The configuration enables the pymdownx.arithmatex extension with generic processing. Use in a new project or migrate an existing one by adding these lines.

```js
window.MathJax = {
  tex: {
    inlineMath: [["\\\\(", "\\\\)"]],
    displayMath: [["\\\\(", "\\\\)"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { // (1)!
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

component$.subscribe(({ ref }) => {
  if (ref.classList.contains("md-annotation"))
    MathJax.typesetPromise([ref])
})
```

```toml
[project]
extra_javascript = [
  "javascripts/mathjax.js",
  "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js",
]

[project.markdown_extensions]
pymdownx.arithmatex.generic = true
```

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

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
```

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

### Example markdown for unused_definitions

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

Markdown example that triggers the unused_definitions warning: a link definition that is never referenced.

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

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

### Bootstrap a new Zensical project with zensical new .

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

Run this command in the directory where you want your project to be located. It creates the project structure including .github/workflows/docs.yml, docs/index.md, docs/markdown.md, and zensical.toml.

```sh
zensical new .
```

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

### Use custom icons in configuration

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

Demonstrates how to reference a custom icon in the configuration file by providing the path relative to the .icons folder.

```toml
[project.theme.icon]
logo = "bootstrap/envelope-paper"
```

```yaml
theme:
  icon:
    logo: bootstrap/envelope-paper
```

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

### Example markdown for unresolved_footnotes

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

Markdown example that triggers the unresolved_footnotes warning: a footnote reference without a matching definition.

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

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

### Example markdown for unresolved_references

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

Markdown example that triggers the unresolved_references warning: a link reference without a matching definition.

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

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

### Example pre-filled title

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

Example of the pre-filled title that results from the GitHub issue link, showing the page title and path.

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

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

### Define a custom status identifier example

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

Example of defining a status identifier `new` with description `Recently added` in both configuration formats.

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

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

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

### Inline syntax example

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

Use $...$ or \(...\) for inline math within a paragraph. The example shows a sentence with inline math for a homomorphism and its kernel.

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

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

### Build the same project with MkDocs or Zensical

Source: https://github.com/zensical/docs/blob/master/docs/compatibility/mkdocs/migration.md

Shows that the same project can be built with either command because Zensical reads the existing mkdocs.yml.

```sh
mkdocs build
```

```sh
zensical build
```

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

### Configure custom icons in zensical.toml

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

Shows the required directory structure and the configuration settings in zensical.toml to enable custom icons.

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

```toml
[project.theme]
custom_dir = "overrides"

[project.markdown_extensions]
pymdownx.emoji.emoji_generator = "zensical.extensions.emoji.to_svg"
pymdownx.emoji.emoji_index = "zensical.extensions.emoji.twemoji"
pymdownx.emoji.options.custom_icons = [
  "overrides/.icons",
]
```

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

### Install Directives wheel with pip

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

Install the Directives extension wheel into the Python environment used to build the site. The wheel is provided within Zensical Spark.

```sh
pip install path/to/zensical_directives-0.1.1-py3-none-any.whl
```

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

### Block syntax example

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

Use $$...$$ or \[...\] on separate lines to create block-level math equations. The example shows the LaTeX code for the cosine series expansion.

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

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

### Enable instant navigation in zensical.toml

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

Adds the navigation.instant feature to the theme configuration in zensical.toml. Requires the site_url setting to be set, as instant navigation relies on the generated sitemap.xml.

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

```

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

### Enable strict mode in zensical.toml or mkdocs.yml

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

Configuration options to enable strict mode, which fails the build when link validation issues are found. The TOML example is for zensical.toml, and the YAML example is for mkdocs.yml.

```toml
[project]
strict = true
```

```yaml
strict: true
```

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

### 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. Ensure the correct virtual environment is activated before running. The --force-reinstall flag forces a reinstall even if the version is already installed.

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

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

### Default project layout

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

Shows the default directory structure with the blog posts directory and entry point index.md. Used to visualize the expected project layout for blog support.

```sh
.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     └─ index.md
└─ zensical.toml

```

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

### Highlight specific lines with hl_lines argument

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

Shows how to highlight lines 2 and 3 in a Python code block using the hl_lines argument. The line count starts at 1, regardless of the starting line number from linenums.

```markdown
``` py hl_lines="2 3"
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]
```
```

```python
``` py linenums="1" hl_lines="2 3"
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]
```
```

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

### Code block with line numbers (linenums="1")

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

Add line numbers to a code block using the linenums="<start>" option after the shortcode. The start value can be any number, allowing large code blocks to be split for readability.

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

```py
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]
```

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

### Build a static site with zensical build

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

Builds a static site from your Markdown files. The output is self-contained and can be hosted on GitHub Pages, a CDN, or your private web space.

```text
zensical build
```

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

### pyproject.toml for a theme extension

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

Declares the package metadata and the mkdocs.themes entry point. The entry point group is what Zensical uses to discover installed themes; the key on the left is the name users set in their configuration, and the value on the right is the directory inside the package containing the theme files. Replace the highlighted placeholders with your actual values.

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

```

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

### External Link Navigation in zensical.toml

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

Navigation items can be URLs; this example links to the GitHub repository for the Zensical Documentation.

```toml
[project]
nav = [
  { "GitHub Repo" = "https://github.com/zensical/docs" },
]

```

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

### zensical build command usage

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

The core command to build the documentation site, with an optional [OPTIONS] argument. Generates the static site in the configured 'site_dir' (default 'site').

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

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

### Enable instant previews via zensical.toml

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

Configuration for the preview Markdown extension in zensical.toml. Targets specify pages to which instant previews are enabled. Sources can be omitted to enable on all pages.

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

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

### Basic admonition syntax

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

Starts an admonition block with `!!!` followed by a type qualifier. Content is indented by four spaces on the next line.

```markdown
!!! note

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

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

### Override htmltitle block

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

Example of overriding the htmltitle block in main.html to change the site title. The template extends base.html and redefines the block.

```html
{% extends "base.html" %}

{% block htmltitle %}
  <title>Lorem ipsum dolor sit amet</title>
{% endblock %}
```

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

### Project structure created by zensical new .

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

Shows the directory tree generated by the new command. The docs/ folder contains index.md and markdown.md, and zensical.toml is the configuration file.

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

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

### Configure custom icons in mkdocs.yml

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

Shows the required directory structure and the configuration settings in mkdocs.yml to enable custom icons.

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

```yaml
theme:
  custom_dir: overrides

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:zensical.extensions.emoji.twemoji
      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons
```

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

### Override partials directory structure

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

To override a partial, create a file with the same name and location in the overrides directory. This example shows replacing the footer.html partial.

```text
.
└─ overrides/
   └─ partials/
      └─ footer.html
```

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

### Markdown: Data table with sortable columns

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

Example of a data table that becomes sortable after applying the customization. Clicking a column header sorts the table.

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