Zensical basics¶

Zensical Zensical turns the Markdown files under docs/ into the website. Prodockit uses the same configured Markdown pipeline when it builds the PDF, so the authoring features on this page are intended to work in both outputs.

Start with Markdown basics if headings, links, images, or lists are new to you. This page introduces the extended features configured in this project. Each section shows either the source to copy, a live result, or both.

Preview and build¶

Run commands from the project directory with its virtual environment active. Use the Zensical Studio viewer in Visual Studio Code, or start the live website preview with:

zensical serve

Leave it running while you edit and press Ctrl+C when you want to stop it. For a complete clean website build, use:

zensical build --clean --strict

The preview and website build do not rebuild the PDF. After the clean build, use prodockit pdf; it reads the completed website rather than running Zensical itself. Follow the author checks in Start editing when both outputs need reviewing.

Follow the four-space rule¶

Python Markdown uses four spaces to attach nested content to a list item, admonition, tab, or other containing block:

1. A list item with supporting information.

    !!! note
        This admonition belongs to the list item. Its own content is indented
        by another four spaces.

2. The next list item.

If a list unexpectedly restarts at 1, or block syntax appears as visible text, inspect its indentation first. Do not substitute a tab or two spaces.

Add an admonition¶

admonitions Admonitions distinguish supporting information from the main argument. Use them sparingly: note for context, tip for useful advice, and warning or danger when ignoring the message has a consequence.

!!! note "Optional title"
    The content is indented by four spaces.

!!! warning
    A title is optional.

The first example renders as:

See Zensical's admonitions reference for every supported type.

Add collapsible details¶

Replace !!! with ??? to hide the content until a reader opens it. Use ???+ when it should start open:

??? info "Show the explanation"
    This content starts closed.

???+ note "Shown initially"
    This content starts open but can be collapsed.

Collapsible details are useful for optional explanations and answers, but not for information every reader must see.

Enhance code blocks¶

Add options after a fenced block's language to provide a title, line numbers, or highlighted lines:

``` python title="Greeting" linenums="1" hl_lines="2"
def greet(name):
    print(f"Hello, {name}!")

greet("Python")
```

Annotations connect a numbered marker in code with an explanation immediately after the block:

print("Hello")  # (1)!

1. This explanation belongs to marker 1.

Highlight short inline code by adding a language after #!: print("Hello, Python!").

See Zensical's code-block reference for the complete option list.

Present alternatives in content tabs¶

content tabs Tabs are useful when a reader should choose one of several alternatives, such as an operating system. Each tab heading begins with ===, and all of its content is indented by four spaces:

=== "Python"

    ``` python
    print("Hello from Python!")
    ```

=== "Rust"

    ``` rust
    println!("Hello from Rust!");
    ```

The example renders as:

print("Hello from Python!")

println!("Hello from Rust!");

Keep tab labels short and do not hide sequential steps inside tabs.

Add a caption¶

This project enables PyMdown Blocks captions for images and tables. Put the caption block immediately after the item it describes:

![Example reference-list layout](images/reference-style-european.png){ width="70%" }
/// figure-caption
    attrs: {id: figure-caption-example}

Example reference-list layout
///

For a table, use table-caption and add | < to display its caption above the table:

| Option | Purpose |
|---|---|
| `--clean` | Start with an empty output directory |
/// table-caption | <
    attrs: {id: table-caption-example}

Build options
///

The figure and table caption types are numbered in both outputs. Continue to Caption a figure for stable ids and cross-references, or Caption a table for positioning and the table-layout features. The PyMdown Blocks caption reference contains the underlying syntax.

Add a Mermaid diagram¶

Zensical renders Mermaid definitions as diagrams. Use a Mermaid fence rather than an ordinary code fence:

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

The website renders Mermaid in the browser. The PDF needs the optional Mermaid renderer installed through the chosen installation path. If the PDF shows definition text instead of a diagram, use the editing help.

Add footnotes¶

Place a marker in the sentence and define it elsewhere on the page:

This statement needs extra context.[^context]

[^context]: This is the supporting information.

This statement has a live footnote.¹

Use a meaningful label such as context rather than a number when the source will be easier to maintain that way.

Use extended formatting¶

Avoid combining several styles merely for decoration. Headings and emphasis communicate document structure more clearly.

Add icons and emojis¶

icons and emojis Use :name: for an emoji or configured icon:

• :sparkles: →
• :rocket: →
• :material-file-document: →

The available icon sets depend on zensical.toml. See Zensical's icons and emojis reference before adding a new icon family.

Add mathematics¶

MathJax Put inline mathematics between single dollar signs. Put displayed mathematics between double dollar signs on separate lines. This live example is displayed mathematics:

MathJax renders the website copy and prodockit's optional maths tool renders the PDF copy. Both must be installed for consistent output. Use the editing help if the formula appears as raw TeX.

Add task lists¶

Task-list syntax produces checkboxes:

- [x] Draft completed
- [x] References checked
- [ ] Final review outstanding

Use these for project work, not as a substitute for numbered procedural steps.

Add a tooltip or abbreviation¶

A reference-style link with a title becomes a tooltip:

[Hover over this text][example]

[example]: https://example.com "Additional information"

Hover over this live text.

Define an abbreviation once and Zensical explains matching text when a reader hovers over it:

*[HTML]: HyperText Markup Language

Use the dedicated Acronyms and abbreviations feature when the term must also link to a managed acronym or glossary page.

Avoid common mistakes¶

• Preview with Zensical Studio or zensical serve, not a generic Markdown viewer that lacks this project's extensions.
• Use four spaces for content nested inside lists, tabs, admonitions, details, footnotes, and other blocks.
• Leave a blank line around block syntax and close every fence or block.
• Build and inspect the PDF as well as the website; JavaScript-rendered diagrams and mathematics use a separate PDF toolchain.
• Use an ordinary Markdown link when link text should differ from a registered term, citation, or cross-reference.

Where to go next¶

Use Shell commands as a beginner's reference when following terminal instructions. Continue to Document appearance and structure to change the site, cover page, navigation, and PDF layout, or to Prodockit authoring features for prodockit's authoring extensions.