Rules and almanac: a Zensical site and a Pandoc PDF¶

Exercise zensical-site-pandoc-pdf-annex.pdf · PDF

It is your turn in a board game, and you want to build a road. Which booklet do you open? The rules: how do I do this? Now somebody plays a card and you all argue about what exactly it allows. Which one now? The almanac: what exactly is this? Two questions, two documents.

Your app needs the same pair. A user manual answers "how do I...?". A reference guide answers "what is...?". Mix them and the page answers neither. On this page you write both in Markdown, publish them as a website, and turn the same text into a PDF without copying a single line.

Get the tools¶

You need three commands working. Zensical is a Python program, so it needs Python 3.11 or later, installed inside a virtual environment: a private folder of Python packages for this project.

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

python -m venv .venv
.venv\Scripts\activate
pip install zensical

Pandoc comes from the installer at pandoc.org/installing.html. Typst is already on your PC from Unit 6. Check all three:

zensical --version
pandoc --version
typst --version

A site in three commands¶

Go to the root of your project, next to package.json:

zensical new .          # creates zensical.toml, docs/index.md and docs/markdown.md
zensical serve          # preview at http://localhost:8000, reloads on save
zensical build          # writes the finished site into site/

zensical new also creates .github/workflows/docs.yml, a ready-made recipe for publishing on GitHub Pages. Delete it if you do not publish there.

A clean build ends with the words No issues found. Add site/ to your .gitignore: it is output, just like build/.

Also, zensical serve publishes nothing: it is a preview on your PC. zensical build produces site/, and that folder is what gets published.

The menu is your map¶

Open zensical.toml. It is long and full of comments, but only two settings matter now: site_name, and nav, the menu. Replace the generated nav with the docs map you drew, one line per card:

[project]
site_name = "NoteBox docs"
nav = [
  { "Home" = "index.md" },
  { "User manual" = "user-manual.md" },
  { "Reference guide" = "reference.md" },
]

Create the two empty files in docs/, save, and watch the menu appear. A page missing from nav does not appear in the menu.

Keep docs/markdown.md open for now: it is a generated cheat sheet of everything the theme can do, such as admonitions, tabs and diagrams. Before you hand in, remove it from nav and delete the file. Leaving it out of nav only hides it from the menu: Zensical still builds the page into site/.

Manual or reference?¶

This split comes from Diátaxis, a documentation framework by Daniele Procida. It calls the first kind of page a how-to guide (task-oriented) and the second reference (information-oriented).

Writing a manual page¶

A manual page has six parts. Each one has a rule:

1. The title is the task. What did the reader type into the search box to get here? "Export a report as PDF", not "Reports".
2. One sentence of purpose. What the reader gets. No history, no architecture.
3. Numbered steps, one action each. If a step has "and then", it is two steps. Use the imperative, and use the words on the screen: if the button says Add, the manual says Add, in bold, not "the create button".
4. End with what you should see. "Then it works" is not something anybody can see. A step list with no result is a recipe with no photo.
5. Pictures only where words are slower. Each one has a caption and a file name that says what it shows. Never write "the picture above": it breaks when the page is printed or reordered.
6. "If something goes wrong". The problem the reader sees, and what to do.

Here is a task from the NoteBox manual:

## Delete a note, and get it back

Remove a note you no longer need. You have a few seconds to change your mind.

1. Press the cross on the note's row. The note disappears at once.
2. A bar appears at the bottom: *"Shopping list" deleted · Undo*.
3. Press **Undo** to get the note back.

The bar stays for 6 seconds. After that the note cannot be recovered.

Do not write from memory. Do the task in the app, one click at a time, and write each click. The step you forget is the one the user gets stuck on. And ban "simply", "obviously" and "very easy". They help nobody, and they insult the person who is stuck.

Writing a reference page¶

One screen, complete. One row per control, with the same five columns every time. Icons count. Messages count. Here is the Settings screen of NoteBox:

Is a control too obvious to include? Obvious to whom? The reference is the one place that must be complete. And keep explanations out of the manual's steps: the user with a task does not care that your app uses localStorage. Move that here, or delete it.

The same text, as a PDF¶

Who still needs a PDF? The client who wants "the manual" attached to the delivery. The administrator in a server room with no internet. The person who prints. Pandoc converts your Markdown and Typst typesets it:

flowchart LR
    M["<b>user-manual.md</b><br>the source"] --> P["<b>Pandoc</b><br>converts it to Typst"]
    P --> T["<b>Typst</b><br>typesets the pages"]
    T --> F["<b>user-manual.pdf</b><br>one file to attach"]

Give the page one # heading for its title and use ## for each task. Then, from the project root:

mkdir manual
cd docs
pandoc user-manual.md -o ../manual/user-manual.pdf --pdf-engine=typst --shift-heading-level-by=-1 -V mainfont="Libertinus Serif" -V papersize=a4 -V section-numbering=1.1 --toc

Open the PDF. It is your Markdown, typeset: title, table of contents, numbered sections, lists and tables. Every option has a job:

Two traps with paths¶

Run Pandoc from inside docs/. Run it from the project root on a page with an image and you get file not found: Typst looks for assets/... starting from where you ran the command. That is why the command starts with cd docs.

Create the output folder. Pandoc 3.7 fails with does not exist when manual/ is missing. Pandoc 3.13 creates it for you. mkdir manual is safe either way, once.

What does not survive the trip¶

Add a tip box and a diagram to your page, then rebuild:

!!! tip "Careful"

    Back up first.

```mermaid
flowchart LR
    A --> B
```

On the site they look perfect. In the PDF, the tip is a plain paragraph starting with !!! tip, its text is a code block, and the diagram is its source code. Pandoc reads standard Markdown. Admonitions, tabs, icons and Mermaid are Zensical's extensions.

A table too wide for the page is a different problem with the same answer: fewer columns, shorter cells. It was too wide for the reader as well.

Save the commands¶

Nobody should have to remember that line. Put both commands in package.json. Inside a JSON string, the inner quotes are written \":

"scripts": {
  "docs:site": "zensical build --clean",
  "docs:pdf": "cd docs && pandoc user-manual.md -o ../manual/user-manual.pdf --pdf-engine=typst --shift-heading-level-by=-1 -V mainfont=\"Libertinus Serif\" -V papersize=a4 -V section-numbering=1.1 --toc"
}

Keep the other scripts your project already has. Now npm run docs:site builds the site and npm run docs:pdf builds the PDF.

Two extensions when you are ready:

• Several files, one PDF. Pandoc takes them in order: pandoc user-manual.md reference.md -o ../manual/manual.pdf, plus the same options. With the shift, only the first file's # becomes the title. The others turn into a plain line, so remove them from the PDF's source or accept it.
• Your own styling. Replace -o ../manual/user-manual.pdf --pdf-engine=typst with -s -o manual.typ to get the Typst source, then style it as you did in Unit 6.

The PDF is one output, never the source. Nobody edits it: correct the Markdown and rebuild.

The stranger test¶

You cannot judge your own steps. You know the app too well to notice what is missing. So borrow a stranger:

1. Your partner sits at your app with your PDF open. Not the site: no searching.
2. They do one task from your manual. They do exactly what it says and nothing it does not say.
3. You watch. You may not speak or point.
4. Each time they stop, hesitate or do something else, write down the step number.
5. Fix the worst step.

Watching somebody fail on a step you thought was obvious teaches more than any rule on this page. That is why "obviously" has no place in a manual.

Key takeaways¶

• zensical new ., zensical serve and zensical build create, preview and build a site. nav in zensical.toml is your menu.
• A user manual is organised by task and read in order. A reference guide is organised by screen and looked up one row at a time.
• Manual steps carry one action each, use the words on the screen, and end with what you should see.
• Pandoc + Typst turn the same Markdown into a PDF. Run Pandoc from inside docs/.
• Pandoc reads standard Markdown: admonitions, tabs, icons and Mermaid do not reach the PDF.
• The stranger test finds the steps you cannot see for yourself.

Quick check¶

Your manual still has holes where the pictures should go, and your app still explains nothing on its own screens. The next lesson, Context help and screenshots, fixes both.