Zensical Documentation

Zensical Documentation for the Learn Project

Documentation as Code Best Practices

1. Structure & Organization

• Single Source of Truth: All documentation lives in the repository, version-controlled with code
• Logical Hierarchy: Organize by domain (operations, coding, deployment, AI collaboration)
• Consistent Naming: Use kebab-case for files and directories
• Metadata Standardization: Include frontmatter or structured metadata for searchability

2. Content Standards

• Action-Oriented Titles: Use verb-first naming (e.g., “Install Zensical”, “Validate Availability”)
• Step-by-Step Procedures: Numbered lists for sequential operations
• Code Examples: Provide executable, non-interactive examples with clear input/output
• Error Handling: Document expected errors and resolution steps

3. Search & Discovery

• Tag-Based Classification: Use consistent tags for cross-referencing
• Cross-Links: Reference related procedures and concepts
• Provenance Tracking: Include author, date, and update history
• Status Indicators: Mark content as active, deferred, or deprecated

4. AI Agent Compatibility

• Non-Interactive Scripts: All executable procedures must work without user input
• Structured Output: Return JSON or parseable stdout with exit codes
• Idempotency: Scripts must be safe to re-run without side effects
• Toolset Alignment: Document required tools and dependencies

Learn Project Overview

The Learn Project is a living, git-backed knowledge base for a senior computer engineer and their AI agents. It serves as a curated, versioned, searchable collection of procedures, scripts, and reference guides.

Project Scope

• Operations — Installation, updates, fixes, DevOps
• Coding — Planning, programming, testing
• Deployment — CI/CD, containers, cloud
• AI Agent Collaboration — Multi-agent workflows, handoffs, skills
• System Administration — Linux, networking, security
• Documentation — Writing, wiki, reference
• Infrastructure — Docker, Proxmox, systemd
• Incidents — Troubleshooting, rollback, post-mortem

Current State

• Active Domains: Operations, Coding, Cross-Cutting
• Deferred Domains: Deployment (activation on request)
• Version Control: Git-backed with full history
• AI Agent Support: Hermes, Cline, Junie compatible

Zensical Features Utilized

1. Search with Excerpts

Zensical’s search engine now includes excerpts, making it easier to understand why a result matches. Search remains fully client-side and as fast as before, even for projects with thousands of pages.

2. Search Highlighting

Search highlighting now ignores single-character tokens, which avoids noisy matches like highlighting every e for queries such as e-mail.

3. Instant Previews

Instant previews include a hover bridge so moving the cursor from a link to the tooltip no longer drops the popup across the visual gap.

4. Native mkdocs.yml Support

Zensical natively reads mkdocs.yml, allowing users to build existing projects with minimal changes. Existing Markdown files, template overrides, CSS, and JavaScript extensions do not need to be touched.

5. Python Markdown Processing

Zensical currently relies on Python Markdown for content processing, ensuring compatibility with existing documentation formats.

Project Structure

learn/
├── .specify/              # SDD artifacts (specs, plans, tasks)
├── docs/                  # Zensical documentation site
│   ├── zensical.toml      # Zensical configuration
│   ├── index.md           # Home page
│   ├── docs-as-code.md    # Documentation as code best practices
│   └── zensical-documentation.md # Zensical documentation
├── ops/                   # Operations procedures
├── coding/                # Coding workflows
├── scripts/               # Shared utility scripts
└── git-cheatsheet.md      # Quick reference guide

Next Steps for Zensical Migration

1. Validate Zensical Installation: Ensure Zensical v0.0.46+ is available and functional
2. Generate Documentation Site: Use Zensical to build the documentation site from zensical.toml
3. Validate Search Functionality: Test search with excerpts and highlighting
4. Validate UI Features: Test instant previews and hover bridges
5. Validate Validation Defaults: Ensure the disabled validation options (unresolved_references, etc.) do not impact documentation quality

Zensical Spark Considerations

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