Zensical Docs Guide¶

This page documents how the vlash-piper documentation site is built and how to work with it locally. The site is generated by Zensical and hosted on GitHub Pages.

📖 Full Zensical documentation: zensical.org/docs

What is Zensical?¶

Zensical is a documentation site generator. It turns Markdown files in docs/ into a static site configured via zensical.toml.

Key features used in this project:

• Lucide icons in the nav sidebar via frontmatter icon: keys
• Admonitions (!!! note, !!! warning, !!! tip) for callout blocks
• TOML-based navigation defined in zensical.toml
• GitHub Pages deployment via .github/workflows/docs.yml

Local Preview¶

# Install Zensical (one-time, if not using Pixi)
pip install zensical

# Serve locally with live reload
zensical serve

# Build static site into site/
zensical build

Or, if you're already inside the Pixi environment:

pixi run docs-serve   # live reload at localhost:8000
pixi run docs-build   # build site/

The local preview is available at http://localhost:8000.

Project Structure¶

vlash-piper/
├── docs/                    # All Markdown source files
│   ├── index.md             # Home page
│   ├── operation_guide.md   # Clone → install → run workflow
│   ├── integration.md       # lerobot_piper compatibility shims
│   ├── problems.md          # Diagnostics & fixes log
│   ├── report.md            # Full technical reference
│   └── guide.md             # This page
└── zensical.toml            # Site config & navigation

Adding a Page¶

1. Create a new .md file in docs/
2. Add a frontmatter block at the top with an icon:

---
icon: lucide/your-icon-name
---

# Your Page Title

1. Add it to the nav in zensical.toml:

nav = [
  { "Home" = "index.md" },
  { "Your Page" = "your_page.md" },
]

Browse available Lucide icons at lucide.dev.

Useful Zensical Syntax¶

Admonitions¶

!!! note
    Informational callout.

!!! warning
    Warning callout.

!!! tip
    Tip callout.

Collapsible Blocks¶

??? info "Click to expand"
    Hidden content here.

Code Blocks with Highlighting¶

```python hl_lines="2" title="example.py"
def hello():
    print("highlighted line")
```

Full reference: zensical.org/docs/authoring

Deployment¶

The site deploys automatically to GitHub Pages on every push to main via .github/workflows/docs.yml. No manual steps needed.