Zensical Migration

Zensical Migration Guide

Overview

Zensical is a modern static site generator built by the creators of Material for MkDocs. It is designed to overcome the technical limitations of MkDocs and support docs-as-code workflows with tens of thousands of pages without compromising performance or usability.

Why Migrate to Zensical?

1. Performance Improvements

• 5x Faster Rebuilds: With the ZRX Differential Build Engine, repeated builds—especially when serving the site—are 4 to 5x faster, as only changed files need to be rebuilt.
• Modern Design: A fresh, modern design that breaks out of the Material Design aesthetic, prioritizing clarity, simplicity, and usability while remaining easily brandable.

2. Enhanced Search

• Disco Search Engine: A modular, blazing-fast client-side search engine with improved ranking algorithms, filtering, and aggregation capabilities.
• Search with Excerpts: Search results now include excerpts, making it easier to understand why a result matches.
• Improved Highlighting: Search highlighting now ignores single-character tokens, which avoids noisy matches.

3. Native Compatibility

• Native mkdocs.yml Support: Zensical natively reads mkdocs.yml, allowing users to build existing projects with minimal changes.
• No Changes Required for Assets: Existing Markdown files, template overrides, CSS, and JavaScript extensions do not need to be touched.

Current Zensical State

Version: v0.0.46 (Latest Release)

• Release Date: June 21, 2026
• Latest Commit: 30afc96 fix: percent-encode & in URLs used in templates and sitemap (#772) (Jun 25, 2026)
• Repository: https://github.com/zensical/zensical

Key Features Available Now

• Search results with excerpts
• Search highlighting that ignores single-character tokens
• Instant previews with hover bridge
• UI v0.0.19 with navigation and interaction fixes
• 83 new icons added, 2 removed, 19 modified (Lucide icon set v1.21.0)

Validation Defaults Changed

The following validation options are now disabled by default because they have proven too unstable in edge cases with the current reference parser:

• unresolved_references
• unresolved_footnotes
• unused_definitions
• unused_footnotes
• shadowed_definitions
• shadowed_footnotes

These checks remain available when explicitly enabled, but they will eventually be superseded by a higher-fidelity parser.

Migration Steps

1. Validate Zensical Installation

Ensure Zensical v0.0.46+ is available and functional:

# Check Zensical repository
ls -la ~/external/zensical

# Verify latest commit
cd ~/external/zensical && git log -1 --oneline

# Verify current tag
cd ~/external/zensical && git describe --tags --exact-match 2>/dev/null || git describe --tags

2. Generate Documentation Site

Use Zensical to build the documentation site from zensical.toml:

cd ~/internal/learn
zensical build

3. Validate Search Functionality

Test search with excerpts and highlighting to ensure compatibility.

4. Validate UI Features

Test instant previews and hover bridges to ensure the UI is functioning correctly.

5. Validate Validation Defaults

Ensure the disabled validation options (unresolved_references, etc.) do not impact documentation quality.

Zensical Spark

For professional users and large organizations, Zensical Spark offers:

• Early access to new features
• Hands-on migration support
• Direct access to the Zensical team
• Financial contributions ensuring the continued development of OSI-compliant Open Source projects

Future Roadmap (Early 2026)

• Component System: A more flexible and adaptable layout system tailored to different use cases and branding requirements.
• Rust-based Markdown Toolchain: A new CommonMark-compliant parser written in Rust will replace Python Markdown, making Markdown processing significantly faster.