zensical-alloy 0.2.0

A refined documentation theme for Zensical

Zensical Alloy

A documentation theme for Zensical. Alloy extends the built-in Material theme, so search, instant navigation, code annotations, footnotes, tabs, palette switching, and plugins keep working.

Alloy only changes the visual layer. It gives Material a quieter header, denser navigation, calmer typography, and matching styles for common documentation surfaces.

Install

pip install zensical-alloy

Use

In zensical.toml:

[project.theme]
name = "alloy"

[project.extra.alloy]
accent_preset = "violet"

In mkdocs.yml:

theme:
  name: alloy

extra:
  alloy:
    accent_preset: violet

What Alloy Changes

• Header, search trigger, source link, and palette toggle.
• Left navigation, right table of contents, and footer links.
• Prose typography, headings, links, tables, and task lists.
• Code blocks, annotations, content tabs, callouts, and buttons.
• Mermaid diagrams and optional Apache ECharts blocks.
• Mobile drawer spacing and tap targets.

Alloy does not replace the Material runtime. The behavior stays upstream.

Screenshots

Light	Dark

Code	Callouts

Mobile home	Mobile drawer

Theme Knobs

All public options live under [project.extra.alloy]:

[project.extra.alloy]
accent_preset = "violet"       # orange, slate, cyan, violet
accent_color = "oklch(...)"    # optional light-mode override
accent_color_dark = "oklch(...)" # optional dark-mode override
radius = "0.625rem"
font_sans = "\"Inter\", ui-sans-serif, system-ui"
font_mono = "\"JetBrains Mono\", ui-monospace"
content_width = "46rem"
sidebar_width = "clamp(10rem, 18vw, 14.5rem)"
toc_width = "clamp(9rem, 15vw, 13rem)"
top_nav_accent = false

accent_preset uses Alloy's curated preset values. Material palette.accent still accepts Material names such as indigo, amber, and deep-purple.

Use alloy_layout: wide in page front matter when one page needs wider content:

---
title: System overview
alloy_layout: wide
---

See the theming guide for details.

Compatibility

Alloy is tested with zensical >= 0.0.40 on Python 3.10 through Python 3.13.

The compatibility notes in MATERIAL_COMPAT.md list the upstream Material selectors and variables that Alloy relies on.

Local Development

python -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python scripts/bundle-css.py --watch

In another terminal:

cd examples/zensical-toml
../../.venv/bin/zensical serve -a 127.0.0.1:8765

Open http://127.0.0.1:8765. The Kitchen Sink page is the main regression target because it places the busiest surfaces on one page.

Checks

Run the full local sweep:

./scripts/smoke.sh

That rebuilds the CSS bundle, checks cache-bust versions, and builds the canonical docs, MkDocs compatibility example, variant fixtures, and real-world shape fixtures.

Contributing

Good changes are small and visible. Improve one component, add one focused fixture, tighten the docs, or make light and dark mode more consistent.

Read the contributing guide for the workflow.

License

MIT