Document appearance and structure¶

Most document-wide changes are made in one of six places:

Make one kind of change at a time, preview the website with zensical serve, and build the PDF before committing. Use Prodockit authoring features for headings, references, citations, glossary terms, captions, tables, steps, trees, and the index.

Customise the website¶

Open zensical.toml to change the configuration. The [project] section contains the site's identity and the [project.theme] section controls its appearance. The examples below cover the settings most authors change; the Zensical setup guide contains the complete reference.

Set the site details¶

Review these values first:

[project]
site_name = "Project report"
site_description = "Design and evaluation of the project"
site_author = "Your Name"
site_url = "https://example.github.io/project/"
copyright = "Copyright © 2026 Your Name"
repo_url = "https://github.com/username/project"
repo_name = "project"

site_name also appears in the PDF's running header and on the cover. The repository settings create the website's repository link; they do not change the Git remote used for pushing.

Keep repository details in sync¶

Synchronise repository details after the project is moved, renamed, or copied from the template. First check that the displayed repository details still match its origin remote:

1. Change to the repository directory with cd.
2. Activate its virtual environment as shown in Prepare the terminal.
3. Run the read-only check:

prodockit sync-repo --check

If the check reports differences, apply them with:

prodockit sync-repo

The command updates repo_url, repo_name, edit_uri, the repository icon, and an existing badge block in README.md. Missing configuration entries are created safely; you do not need to uncomment or insert them in an editor. For a fresh site's incomplete details, an interactive run asks you to confirm the detected repository, website title and proposed website address. A proposed address does not prove that the website has been published. Existing custom domains are preserved unless you explicitly request a different address.

If the project has no README, create a starter one at the same time:

prodockit sync-repo --create-readme

You can also supply details directly, substituting your own title and address:

prodockit sync-repo --site-name "My report" --site-url "https://your-account.github.io/your-repository/"

--check never prompts or changes files. The command does not change the Git remote, enable hosting or push files. Review the reported changes and git diff before committing them.

The command-line guide provides the full sync-repo reference.

Set a PDF-only copyright value in pdk-pdf.toml when its footer needs different content:

[document]
copyright = "Copyright © 2026 Your Name"

Replace the site logo¶

Replace both default logo files so light and dark mode remain readable:

• docs/assets/logo_default_black.png
• docs/assets/logo_default_white.png

Do not edit logo_black.png or logo_white.png; each build regenerates those working copies.

To add a browser-tab icon, put the image under docs/ and set:

[project.theme]
favicon = "images/favicon.png"

Choose colours and the page heading¶

The existing palette blocks provide light and dark modes. Change their schemes or toggle icons only when the defaults do not suit the document:

[[project.theme.palette]]
media = "(prefers-color-scheme: light)"
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"

[[project.theme.palette]]
media = "(prefers-color-scheme: dark)"
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"

Replace header-background.jpg and header-background-dark.jpg under docs/assets/ to change the website header. Check contrast in both modes.

Fonts¶

Set the proportional and monospace fonts in zensical.toml:

[project.theme.font]
text = "Inter"
code = "Jetbrains Mono"

The website and PDF use the same families. The PDF defaults to 11pt body text and 10pt inline or fenced code, keeping code one point smaller than the surrounding prose. Ensure custom fonts are installed wherever local PDF builds run.

Choose icons and website features¶

[project.theme.icon] controls the edit, view, and repository icons. Use an icon name supported by Zensical:

[project.theme.icon]
edit = "lucide/pencil"
view = "lucide/eye"
repo = "fontawesome/brands/github"

The features list under [project.theme] enables website behaviour such as sticky navigation, search highlighting, and the back-to-top button. The comments in zensical.toml link each feature to its Zensical documentation. Change only the feature line you understand, then test desktop and mobile layouts.

Extra CSS and JavaScript¶

The project loads managed Prodockit assets before user-managed overrides. It also keeps the managed MathJax configuration before the website runtime:

extra_css = ["stylesheets/pdk.css", "stylesheets/extra.css"]
extra_javascript = [
    "javascripts/pdk.js",
    "javascripts/mathjax.js",
    "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js",
    "javascripts/extra.js",
]

pdk.js is managed by Prodockit and contains shared website behaviour. extra.js is the user-managed extension point and is preserved by Adopt and Template Sync. Keep it last so project-specific code can build on or override the managed behaviour.

The website follows Zensical's MathJax 3 setup. mathjax.js is a committed Prodockit-managed file; keep it before the browser runtime. PDF maths uses a separate, verified MathJax 4 cache prepared by pdk pdf, with no npm install.

Load the managed PDF defaults before your PDF-only overrides in pdk-pdf.toml:

[document]
extra_css = ["stylesheets/pdk-pdf.css", "stylesheets/print.css"]

The complete PDF cascade is pdk.css, extra.css, pdk-pdf.css, then print.css; your two override files therefore take precedence over the corresponding managed defaults.

Add footer links¶

Add a social or organisation link by repeating this block:

[[project.extra.social]]
icon = "fontawesome/brands/github"
link = "https://github.com/username"

Navigation structure¶

The navigation nav list in zensical.toml controls the page order for both the website and PDF. A top-level group becomes a website tab; entries inside it become pages or collapsible groups.

nav = [
    {"Cover" = [
        "index.md",
    ]},
    {"Report" = [
        {"1. Introduction" = "introduction.md"},
        {"2. Design" = "design.md"},
        {"3. Evaluation" = "evaluation.md"},
    ]},
    {"Appendixes" = [
        {"Appendix A. Acronyms" = "acronyms.md"},
        {"Appendix B. Glossary" = "glossary.md"},
        {"Appendix C. References" = "references.md"},
    ]},
]

To add a page:

1. Create its .md file beneath docs/.
2. Give it one level-one heading.
3. Add its path to nav in the required position.
4. Renumber the visible nav labels after it where necessary.
5. Preview the website and build the PDF.

Do not put a second level-one heading in the same file. Create another page instead. Changing heading numbering explains automatic in-page numbers and appendixes.

Customise front page¶

Edit docs/index.md to change the front page. Keep the surrounding HTML classes and Jinja markers until you have confirmed what each one supplies.

Institution branding¶

The cover contains a default organisation branch. Edit its organisation name, programme or document description, and logo paths. Preserve any surrounding Jinja markers: they allow the same source to select different institutional branding when a project needs it.

The template sets on_error_fail = true for Zensical's macros extension. Keep that setting when changing zensical.toml: if Jinja cannot render a page variable or macro call, the preview or build then stops instead of returning the unrendered page and allowing a broken site to be published. The website-macros reference shows the complete configuration.

PDF-only and web-only content¶

Add .pdf-only to content intended only for the PDF and .web-only to content intended only for the website. For example:

<p class="pdf-only">Word count: {WORDCOUNT}</p>

[Download PDF](site_documentation.pdf){ .md-button .web-only }

Use these classes only when the two outputs genuinely need different content.

Site name¶

Zensical exposes the site_name from zensical.toml through its native config variable:

<p class="title-ctr-b4">{{ config.site_name }}</p>

Edit site_name rather than typing a second copy into the cover. Remove the line from both branding branches if the cover should not show it.

Word count and repository link¶

The shipped cover can display these PDF markers:

<p class="pdf-only">Word count: {WORDCOUNT}</p>
<p class="pdf-only">Repo: {REPOURL}</p>
<p class="pdf-only">Release: {RELEASE}</p>

• {WORDCOUNT} counts the built document, excluding the cover, contents page, and pages marked exclude_from_word_count: true.
• {REPOURL} uses the repository's origin remote.
• {RELEASE} uses the latest published repository release and disappears when none exists.

Exclude another page from the word count in its front matter:

---
icon: lucide/book-open
exclude_from_word_count: true
---

For the website, ProDocKit supplies {{ pdk_word_count }} and {{ pdk_repo_url }}. Zensical supplies the release through its native {{ git.short_tag }} variable. The website count is an estimate and can differ slightly from the final PDF count.

Download PDF button¶

The cover's .web-only button links to site_documentation.pdf:

[:material-file-pdf-box: Download PDF](site_documentation.pdf){ .md-button .web-only }

Keep the filename aligned with the build output. Remove the line if the site does not publish a PDF.

Customise PDF generation¶

The configuration is read when you run prodockit pdf. PDF-only settings live in pdk-pdf.toml beside zensical.toml. The PDF also uses the website's rendered Markdown, site name, fonts, extensions, and most content customisations. See Build the PDF for the working command and Build and publish for build configuration.

Page header¶

The running header shows site_name on the left and the current chapter on the right. Change site_name for the shared title. The chapter title comes from the page's level-one heading.

Page footer¶

The footer shows the copyright on the left and “Page X of Y” on the right. Set shared appearance values only when the defaults need changing:

[header_footer]
font_size = "10pt"
color = "#555555"
divider_color = "#e2e8f0"

The cover does not show the running header or footer.

Page size and margins¶

Set the physical page and margins in pdk-pdf.toml:

[document]
page_size = "A4"

[margins]
top = "2cm"
right = "2cm"
bottom = "2cm"
left = "2cm"

These values affect only the PDF. Build and inspect pages containing wide tables, figures, and long headings after changing them.

Double-sided printing¶

For a bound document, mirror the inner and outer margins and begin chapters on right-hand pages:

[document]
double_sided = true

[margins]
inner = "2.5cm"
outer = "1.5cm"

Use recto_title: "Short title" in a page's front matter if its chapter title is too long for the running header.

Source-code bundling¶

Build a separate PDF containing the authored Markdown, configuration, and root README when a submission requires its source:

prodockit source-bundle

It writes source_bundle.pdf alongside site_documentation.pdf. It does not include the entire repository or generated template-maintenance files. The PDF source-bundle reference describes programmatic full-repository bundling for the less common case that requires it.

Screenshots¶

Give screenshots the .screenshot class and a numbered figure caption:

![Initial commit](images/initial-commit.png){ width="40%" .screenshot }
/// figure-caption
    attrs: {id: figure-screenshot-example}

Initial commit
///

The class adds a border and shadow in both outputs. Do not apply it to logos, icons, or diagrams.

Directory structure¶

The directory structure below shows the files an author most often changes:

Use Prodockit authoring features for the authoring files and Build and publish for build tools and publishing files.

Where to go next¶

Continue to Prodockit authoring features for headings, references, sources, captions, tables, procedures, directory trees, and the index. Then use Build and publish for local and published build behaviour.