Skip to content

Zensical demo

Zensical demo

Quickstart

Create and activate a venv, upgrade pip, then install Zensical:

python3 -m venv .venv
# Linux / macOS / Actions
source .venv/bin/activate
# Windows PowerShell
# . .venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
pip install zensical
# or install all project deps:
pip install -r requirements.txt

Common CLI commands

# build site to site/ (or configured output)
python -m zensical build

# serve locally with live reload
python -m zensical serve

# new content skeleton
python -m zensical new page "My Page Title"

(When not activating the venv in CI steps, run the module directly: ./.venv/bin/python -m zensical build on Linux/macOS or .venv\Scripts\python -m zensical build on Windows.)

  • docs/
  • index.md
  • about.md
  • zensical-demo.md
  • site/ (output)
  • requirements.txt
  • zensical.yml or pyproject.toml (site config)

Example zensical.yml (minimal)

site_name: Boening.us Demo
theme:
  name: material
nav:
  - Home: index.md
  - Demo: zensical-demo.md

Preview & CI notes

  • Combine venv creation, install and build in one CI step to ensure the CLI binary is available in the same shell.
  • Or call the venv python module directly in later steps.

GitHub Actions snippet (build step):

- name: Build site
  run: |
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install -r requirements.txt
    python -m zensical build

Or without activation:

python3 -m venv .venv
python -m pip install -r .venv/lib/python*/site-packages || true
./.venv/bin/python -m zensical build

Troubleshooting

  • "zensical: command not found": ensure you installed zensical into the same shell (or call python -m zensical).
  • Stale bytecode: remove __pycache__ and .pyc files.
  • Virtualenv issues on Actions: prefer python -m venv .venv and using the venv's python binary explicitly.

Tips & best practices

  • Add zensical to requirements.txt to pin versions: zensical==<version>
  • Use a simple zensical.yml for reproducible builds.
  • Keep content modular: small pages and a clear nav.

FAQ

  • Q: Is Zensical a Node tool?
    A: No — Zensical is a Python package installable via pip.

  • Q: Should I install globally in CI?
    A: Prefer project venv for reproducibility; only use global install as fallback.

Changelog

  • 0.2.1 — Added build/serve examples, CI guidance, troubleshooting tips.

Admonition

Note

Ha, ha, ha