Zensical.org Markdown cheat sheet¶

Zensical (and the docs site at zensical.org) is built on Python Markdown plus a curated set of Markdown extensions. If you don’t configure extensions yourself, Zensical applies a default set that enables most authoring features shown in the documentation. (zensical.org)

Below is a practical “what you can write” cheat sheet: core Markdown + the supported extension syntax + the theme/authoring patterns (buttons, grids, etc.) that Zensical explicitly documents. (zensical.org)

1) Core Markdown (baseline)¶

These are the “normal Markdown” bits you can assume work:

Headings¶

# H1
## H2
### H3

Paragraphs & line breaks¶

A paragraph.

Another paragraph.

A forced line break  
(using two trailing spaces)

Emphasis¶

*italic* or _italic_
**bold** or __bold__
***bold italic***

Blockquotes¶

> Quoted text
>
> Another paragraph in the quote.

Inline code¶

Use `inline_code()` for identifiers.

Horizontal rule¶

---

Links¶

[Link text](https://example.com)

Images¶

![Alt text](path-or-url.png)

2) What Zensical explicitly supports (extensions list)¶

Zensical documents support for (at least) the following extensions:

• Abbreviations
• Admonition
• Arithmatex (math)
• Attribute Lists
• Caret, Mark & Tilde (underline/highlight/sub/sup)
• Definition Lists
• Details (collapsible blocks)
• Emoji
• Footnotes
• Highlight (code highlighting)
• Keys (keyboard key styling)
• Markdown in HTML
• SmartSymbols
• Snippets
• SuperFences (enhanced fenced blocks)
• Tabbed (content tabs)
• Table of Contents
• Tables
• Tasklist (zensical.org)

3) Attribute Lists (attach classes/attrs with { ... })¶

Attribute Lists are a cornerstone of Zensical authoring patterns (buttons, aligned images, styled icons, etc.). (zensical.org)

Add CSS classes to a thing¶

[Some link](#){ .some-class }

Add HTML-ish attributes¶

![Alt](image.png){ width="300" loading=lazy }

4) Buttons (links styled as buttons)¶

Zensical’s theme provides button styling by adding classes to links (via Attribute Lists). (zensical.org)

Basic button¶

[Subscribe](#){ .md-button }

Primary filled button¶

[Subscribe](#){ .md-button .md-button--primary }

Button with an icon/emoji shortcode¶

[Send :fontawesome-solid-paper-plane:](#){ .md-button }

(Icon shortcodes are covered below.) (zensical.org)

5) Icons & Emojis (shortcodes)¶

Zensical supports emojis and a large set of icons using shortcode-like syntax. (zensical.org)

Emojis¶

Put the emoji shortcode between colons:

:smile:

(zensical.org)

Icons¶

Icons use the same :...: pattern, but refer to an icon “path” transformed into a shortcode (slashes become hyphens). Example:

:fontawesome-regular-face-laugh-wink:

(zensical.org)

Add a class to an icon (e.g., for color/animation)¶

:fontawesome-brands-youtube:{ .youtube }

This relies on Attribute Lists. (zensical.org)

6) Admonitions (callout blocks) and Details (collapsible callouts)¶

Zensical supports Admonition and Details. (zensical.org)

Standard admonition¶

Common pattern (indent the content under the admonition):

!!! note
    This is a note.

Custom title¶

!!! warning "Be careful"
    This action can’t be undone.

Collapsible (details-style) admonition¶

A common “details” pattern is the same block but collapsible:

??? info "Click to expand"
    Hidden until expanded.

Tip: If you’re contributing to zensical.org docs, you can verify the exact look by checking the Admonitions page examples in their docs. (zensical.org)

7) Lists (unordered, ordered, definition lists, task lists)¶

Zensical supports standard unordered/ordered lists, plus definition lists and task lists via extensions. (zensical.org)

Unordered lists¶

Use -, *, or +:

- Item A
- Item B
  - Nested item

(zensical.org)

Ordered lists¶

Numbers don’t need to be consecutive (they’ll be renumbered on render):

1. First
1. Second
1. Third

(zensical.org)

Definition lists¶

Term
:   Definition text

Another term
:   Another definition

(zensical.org)

Task lists (checkboxes)¶

- [x] Done
- [ ] Not done
  - [x] Nested done

(zensical.org)

8) Tables¶

Zensical supports the Tables extension. (zensical.org)

A typical pipe-table looks like:

| Column A | Column B |
|---------:|:---------|
| right    | left     |
| 123      | abc      |

(Exact alignment rules follow the common Markdown “tables” extension behavior.)

9) Footnotes¶

Footnotes are supported and render at the bottom of the page. (zensical.org)

Footnote references¶

Here is a statement with a footnote.[^1]

(zensical.org)

Footnote definitions (single line)¶

[^1]: The footnote content goes here.

(zensical.org)

Footnote definitions (multi-line)¶

Indent continuation lines by 4 spaces:

[^2]:
    This footnote has multiple lines.
    It keeps going here.

(zensical.org)

Footnote tooltips¶

Zensical can render footnotes as tooltips via a theme feature, and the docs note it’s enabled on their documentation. (zensical.org)

10) Tooltips (link titles + site-wide glossary)¶

Link title tooltips¶

Standard Markdown link titles become tooltips (and look nicer if “improved tooltips” is enabled in the theme). (zensical.org)

[Hover me](https://example.com "I'm a tooltip!")

(zensical.org)

Glossary-style abbreviations¶

Zensical uses Abbreviations + Snippets to build a site-wide glossary file you can auto-append to all pages. (zensical.org)

Define abbreviations like:

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

(zensical.org)

11) Content tabs¶

Zensical supports tabbed content blocks. (zensical.org)

Tabs grouping code blocks¶

=== "C"

    ``` c
    #include <stdio.h>
    int main(void) { return 0; }
    ```

=== "C++"

    ``` c++
    #include <iostream>
    int main(void) { return 0; }
    ```

(zensical.org)

Linked tabs across the whole site¶

There’s a theme feature that links tabs by label so selecting a tab on one page selects the same-labeled tab elsewhere. (zensical.org)

12) Code blocks and fenced blocks (general)¶

Zensical supports enhanced fenced blocks via SuperFences and code highlighting via Highlight. (zensical.org)

Standard fenced code block¶

``` python
print("Hello")
```

Fences used for non-code features¶

Many “features” are just fenced blocks with a special info string (language), like mermaid (diagrams) or the tabbed example above. (zensical.org)

13) Diagrams (Mermaid)¶

Zensical integrates with Mermaid.js and will initialize Mermaid when a page contains a mermaid code block. (zensical.org)

Mermaid flowchart¶

``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Debug];
  B -->|No| D[Done];
```

(zensical.org)

Zensical documents other Mermaid diagram types too (state diagrams, class diagrams, etc.). (zensical.org)

14) Math (LaTeX-style)¶

Zensical supports math via Arithmatex and documents integration with MathJax or KaTeX. (zensical.org)

Block math¶

Use either $$...$$ or \[...\] on separate lines:

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

(zensical.org)

Inline math¶

Use $...$ or \(...\):

The map $f$ is injective iff \(\ker(f)=\{e\}\).

(zensical.org)

15) Images (alignment, captions, lazy-loading, light/dark variants)¶

Align images left/right¶

Add align=left or align=right via Attribute Lists:

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }

(zensical.org)

Captions¶

Option A: HTML figure + Markdown in HTML

<figure markdown="span">
  ![Image title](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

(zensical.org)

Option B: Caption blocks

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

(zensical.org)

Lazy-loading¶

![Big image](https://dummyimage.com/1200x800/){ loading=lazy }

(zensical.org)

Light/dark mode images¶

Append #only-light / #only-dark to the image URL:

![Light](image.png#only-light)
![Dark](image.png#only-dark)

(zensical.org)

16) Grids (card grids + generic grids)¶

Grids are authored using HTML containers plus markdown processing (Markdown in HTML) so you can write Markdown inside. (zensical.org)

Card grid (list syntax)¶

<div class="grid cards" markdown>
- **Card 1** — text
- **Card 2** — text
- **Card 3** — text
</div>

(zensical.org)

Card grid (block syntax)¶

Add { .card } to blocks inside a .grid container:

<div class="grid" markdown>

**Card A**
{ .card }

> A blockquote can also live in the grid.

</div>

(zensical.org)

Generic grids¶

Wrap arbitrary blocks (tabs, code blocks, admonitions, etc.) inside:

<div class="grid" markdown>

=== "Tab 1"
    Content

=== "Tab 2"
    Content

</div>

(zensical.org)

17) “Caret, Mark & Tilde” and “Keys” quick syntax¶

Zensical supports these formatting extensions. (zensical.org)

Common patterns (as used by these extensions):

==highlight==

^^underline^^

~~strikethrough~~

H~2~O        (subscript)
X^2^         (superscript)

++ctrl+alt+del++   (keyboard keys)

(Exact rendering depends on the enabled extensions/theme, but these are the standard syntaxes for the supported set.) (zensical.org)

18) Table of contents and heading permalinks¶

Zensical enables a Table of Contents extension and (in the documented defaults) sets permalink: true, which adds permalink anchors to headings. (zensical.org)

Practical authoring takeaway:

• Use meaningful heading structure (##, ###, …).
• Expect headings to get linkable anchors/permalinks when that feature is enabled. (zensical.org)

Notes on “what’s enabled on zensical.org” vs “what Zensical supports”¶

• The list above is the supported set (what Zensical can parse/render). (zensical.org)
• Some behaviors are explicitly theme features (e.g., improved tooltips, footnote tooltips, linked tabs) and depend on site configuration; the docs call out how to enable them. (zensical.org)
• Zensical’s docs also mention it’s working toward CommonMark support in the future. (zensical.org)

If you tell me whether you’re (a) writing docs for the zensical.org repo specifically or (b) authoring your own Zensical site, I can tailor this into a “minimal subset that’s enabled by default” vs “optional features you must enable.”