Authoring reference¶
This section is for a document author who has built a first Zensical site and wants to add structure or specialist content to its Markdown pages. You do not need to read every page: choose the feature the document needs, enable that extension, and copy its smallest complete example.
Build on PyMdown Blocks¶
Two prodockit extensions are built directly on PyMdown Blocks (see the
upstream Blocks guide):
prodockit.steps for procedures and prodockit.tree for directory listings.
They use PyMdown's slash-fenced container syntax, nesting rules, and block
options rather than introducing a separate container language.
If you already use PyMdown Blocks, the structure will be familiar. If you do not, start with Numbered steps: its first example shows the complete opening and closing fences before explaining nested blocks.
Follow the same three stages¶
Every extension guide starts with the same learning path:
-
Enable the extension
Add the extension's table to
zensical.toml. Each prodockit extension is independent, so enabling headings does not silently enable citations, tables, or another feature. -
Write the Markdown
Start with the complete copyable example. The guide shows both its Markdown source and rendered result before introducing variations.
-
Configure only when needed
Keep the defaults for a first use. The configuration section explains the available
zensical.tomlsettings and shows a rendered example when an option changes visible output.
Choose a feature¶
| Document need | Reference |
|---|---|
| Number sections and give headings stable links | Headings |
| Refer to a heading, figure, or table without typing its changing number | Cross-references |
| Define short references directly in Markdown | Hand-written citations and references |
| Expand abbreviations and define specialist terms | Acronyms and glossary |
| Control column widths, merged cells, and dense layouts | Tables |
| Show a folder and file hierarchy | Directory trees |
| Present a procedure with connected numbered stages | Numbered steps |
| Cite a BibTeX library in a selected CSL style | Bibliography |
| Mark terms for a PDF back-of-book index | Index |
prodockit.citations and prodockit.bibliography are two approaches to the
same broad task. A small document can define sources directly in Markdown;
a report with an existing .bib library normally uses the bibliography
extension. You do not need to enable both.
Keep publishing concerns separate¶
The authoring pages explain what to write. When the content is ready to become a complete PDF or hosted website, continue to Publish a document. Machine setup, template updates, CI, Pages deployment, and output tests live there so they do not interrupt the Markdown reference.