Zensical Customizer

Zensical Customizer

Zensical is the successor to Material for MkDocs, built by the same team. Config file: zensical.toml (TOML format, all settings under [project]). Template engine: MiniJinja (Rust). Dev server: uv run poe docs-serve. Build: uv run poe docs-build.

Use DeepWiki (mcp__deepwiki__ask_question with repo zensical/zensical) for questions about Zensical internals not covered here.

Decision Tree

1. Add styles to existing pages -> Edit docs/stylesheets/extra.css or create a new

stylesheet and register in extra_css. See [project-setup.md](references/project-setup.md).

1. Add JavaScript to all pages -> Place script in docs/javascripts/, register in

extra_javascript in zensical.toml. See [javascript.md](references/javascript.md).

1. Add interactive widget to specific page -> Add `` in markdown, create

JS that uses document$ to mount on that element. See "Pattern 1" in [javascript.md](references/javascript.md).

1. Create a fully custom page layout -> Set up overrides/ directory, create custom

template extending base.html, reference via page frontmatter template: field. See [templates.md](references/templates.md).

1. Override header/footer/nav -> Override partials in overrides/partials/. See

"Overridable Partials" in [templates.md](references/templates.md).

1. Embed a JS framework app (React, Vue, Svelte) -> Build externally, output bundle to

docs/javascripts/, mount via document$ or custom template. See "Pattern 2" and "Pattern 3" in [javascript.md](references/javascript.md).

Quick Start: Add an Interactive Page

Step 1: Enable template overrides (one-time)

Add to zensical.toml under [project.theme]:

custom_dir = "overrides"

Create the directory: overrides/

Step 2: Create a custom template

Create overrides/interactive.html:

{% extends "base.html" %}

{% block content %}
  {{ page.content }}
  
{% endblock %}

{% block scripts %}
  {{ super() }}
  
{% endblock %}

Step 3: Create the page

Create a markdown file (e.g., docs/demos/my-demo.md):

---
template: interactive.html
icon: lucide/play
---

# Interactive Demo

Description of the demo.

Step 4: Add JavaScript

Place docs/javascripts/my-app.js with initialization logic.

Step 5: Register in navigation

Add to nav in zensical.toml:

{ "Demos" = ["demos/my-demo.md"] },

Key Constraints

• No full plugin/module system - extensibility is limited to templates, JS, CSS
• MiniJinja, not Jinja2 - mostly compatible, but complex Jinja2 patterns may differ
• 125% root font-size - Zensical sets html { font-size: 125% } (20px); third-party

libraries with rem-based sizing render 25% larger. Fix with explicit pixel values.

• Markdown extensions are all-or-nothing - defining any custom extensions requires

configuring ALL extensions (defaults don't apply partially)

• navigation.instant not enabled in this project - window.load works for site-wide

scripts, but page-specific widgets should still use document$ for forward compatibility

References

• [templates.md](references/templates.md) - Template blocks, custom page templates,

partials, context variables, MiniJinja syntax

• [javascript.md](references/javascript.md) - JS/CSS injection, document$ observable,

instant navigation, interactive component patterns

• [project-setup.md](references/project-setup.md) - This project's directory structure,

existing customizations, ISCC brand colors, Zensical quirks

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: titusz
• Source: titusz/skills
• License: MIT

Install and usage instructions live in the source repository linked above.