Zensical basics¶

Zensical is the static site generator that powers this template: it turns the Markdown files under docs/ into the website you're reading now, and (via prodockit pdf) into the single-file PDF version of your document. It reads its configuration from zensical.toml, extends Markdown with the authoring features shown below (admonitions, tabs, diagrams, maths, and more), and lets you preview your changes locally with zensical serve before publishing.

This page is a quick reference for the Markdown extensions you're most likely to use while writing your document, each with a live example. For the underlying, general-purpose Markdown syntax these extensions build on (headings, links, bold/italic text, and so on), see Markdown basics. For full documentation on Zensical itself, visit zensical.org.

Commands¶

Zensical provides a command line interface (CLI) to create, build, and serve your documentation. The following commands are available:

• zensical new - Create a new project
• zensical serve - Start local web server
• zensical build - Build your site

Examples¶

Some examples of Zensical syntax are below. For full documentation visit zensical.org.

Lists within lists¶

Markdown supports nested lists by indenting the inner list by four spaces. This is an implementation-specific feature of Python Markdown used by Zensical, and isn't part of the original Markdown specification.

Admonitions¶

Zensical supports admonitions, that highlight blocks of content to draw attention to important information. Admonitions are available for notes, warnings, tips, and more. For further details, go to the admonitions documentation.

Details¶

Zensical supports collapsible blocks using the ??? syntax. This is useful for hiding content until the user clicks to expand it. For further details, go to the admonitions collapsible blocks documentation.

Code blocks¶

Zensical supports fenced code blocks with syntax highlighting. You can specify the language for syntax highlighting by adding the language name after the opening backticks. For further details, go to the code blocks documentation.

def greet(name):
    printf("Hello, {name}!") # (1)!

greet("Python")

1. Go to code annotations documentation

   Code annotations enable attaching of notes to lines of code.

You can also highlight code inline: print("Hello, Python!").

Content tabs¶

Zensical supports content tabs, which enables you to present different content in the same space. This is useful for showing code examples in multiple programming languages. For further details, go to the content tabs documentation.

print("Hello from Python!")

println!("Hello from Rust!");

Images¶

Zensical supports Markdown image syntax using the <figure> tag to add captions. For further details, go to the images documentation.

This template also enables the pymdownx.blocks.caption extension, an alternative way to caption an image using a /// caption ... /// block straight after it, rather than wrapping it in <figure>/<figcaption> tags:

![Image title](https://dummyimage.com/600x400/){ width="300" }
/// caption
Image caption
///

See Captions in Customise document content for more detail, including how this same syntax also captions tables, and how this template handles it in the PDF.

Diagrams¶

Zensical supports Mermaid diagrams. You can create flowcharts, sequence diagrams, and more. For further details, go to the diagrams documentation.

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

Footnotes¶

Zensical supports footnotes, which enables you to add references or additional information without cluttering the main text. You can create a footnote by using the [^1] syntax. For further details, go to the footnotes documentation.

Here's a sentence with a footnote.¹

Hover it, to see a tooltip.

Formatting¶

Zensical supports various formatting options, including bold, italics, and strikethrough. You can also create headings, blockquotes, and horizontal rules. For further details, go to the formatting documentation.

• This was marked (highlight)
• This was inserted (underline)
• This was deleted (strikethrough)
• H₂O
• A^TA
• Ctrl+Alt+Del

Icons, emojis¶

Zensical supports icons and emojis. You can use the :icon-name: syntax to add icons from the Lucide icon set, or use standard emoji codes. For further details, go to the icons and emojis documentation.

• :sparkles:
• :rocket:
• :tada:
• :memo:
• :eyes:

Maths¶

Zensical supports mathematical notation using MathJax. You can write inline math using the $...$ syntax, and display math using the $$...$$ syntax. For further details, go to the math documentation.

Task lists¶

Zensical supports task lists, which allow you to create checklists with checkboxes. You can create a task list by using the - [ ] syntax for an unchecked item and - [x] for a checked item. For further details, go to the task lists documentation.

• Install Zensical
• Configure zensical.toml
• Write amazing documentation
• Deploy anywhere

Tooltips¶

Zensical supports tooltips, which allow you to add additional information that appears when the user hovers over a specific element. You can create a tooltip by using the [text][example] syntax. For further details, go to the tooltips documentation.

Hover over this text

Where to go next¶

Continue to Customisation to change this template's branding, restructure your document's pages, and customise the cover page and PDF layout.