Writing pages¶

Pages are Markdown files in docs/. Use these conventions, so that all ISCC sites work the same for readers and for agents.

Front matter¶

Key	Use
`icon`	The navigation icon, `lucide/<name>`. Each page must have one
`description`	One sentence for link previews and the `llms.txt` index. Without it, the page uses `site_description`
`title`	The page title in the browser and in link previews, if it is different from the navigation label
`location`	Makes the page a redirect to another URL. Use it for pages that moved

---
icon: lucide/rocket
description: Set up the theme for the documentation of an ISCC project
---

Each page shows an icon before its entry in the navigation. Select a name from the Lucide set. Zensical puts the icon into the page as SVG, so the icon adds no request. Section labels in nav have no icon. Only pages have icons.

For Coding Agents¶

The last page in the navigation of each ISCC site is "For Coding Agents". It is a short reference for AI agents that work on the project or use it. It contains an architecture map, decision tables, constraints, side effects, task recipes, change playbooks and common mistakes. It uses tables and code, not long text.

Convention	Value
File	`docs/for-coding-agents.md`
Nav entry	`{ "For Coding Agents" = "for-coding-agents.md" }`, last
Icon	`lucide/bot`

Write the page with the zensical-iscc:docs-for-agents skill: /zensical-iscc:docs-for-agents create.
Run the skill with update each time the public API, the command line or the configuration changes. Agents follow this page closely. If it is out of date, they make errors.
Add this line to the CLAUDE.md or AGENTS.md of the project, so that coding sessions keep the page up to date: "After changing the public API, CLI or configuration, run the docs-for-agents skill with update."
zensical-iscc check gives a warning if the page is missing or not in nav. With --strict, as in CI, the warning makes the build fail.
llms.txt lists the page first, so agents that read the index start there.

The For Coding Agents page of this site is an example.

Markdown for agents and people¶

zensical-iscc build writes the Markdown source of each page next to its HTML, without the front matter:

File	Contents
`<page>/index.md`	One page. "Copy page" and "View as Markdown" read it
`llms-full.txt`	All pages, in navigation order
`llms.txt`	An index in the llmstxt.org format: the agent page first, then all pages with their descriptions

The head of each page links to its Markdown copy with <link rel="alternate" type="text/markdown">, so an agent that gets the HTML can also find the source.

Page components¶

The theme styles a lead paragraph, buttons for calls to action, audience cards and ISCC-UNIT labels. Components shows each of them with its markup. Cards need the md_in_html extension.

Images, badges and media¶

Pages load nothing from other domains, except Plausible and, if chat is on, iscc.ai.

Keep images and badges in docs/. Do not link to images on other sites. Download shields.io badges one time and link to the copies.
To show an image in a lightbox, put it in <a class="glightbox" href="...">. The theme loads its own copy of GLightbox, and only on pages with a lightbox.
Do not use Mermaid diagrams. The Zensical bundle loads Mermaid from unpkg.com, and zensical-iscc check rejects pages with a Mermaid diagram. Use an SVG file.

Command line lists the requests that the check cannot see.