Skip to content

Contributing

Contributions to Flexoki for Zensical are welcome.

Quick Start

# Fork https://github.com/leightonpayne/flexoki-zensical
git clone https://github.com/<your-username>/flexoki-zensical.git
cd flexoki-zensical
git remote add upstream https://github.com/leightonpayne/flexoki-zensical.git
uv sync

Development Commands

Command Description
uv run zensical serve Serve docs locally
uv run zensical build -c Build docs locally
uv build Build sdist and wheel

Project Structure

src/flexoki_zensical/
├── assets/stylesheets/  # Theme CSS
├── partials/            # Template partial overrides
├── main.html            # Theme entry template
└── mkdocs_theme.yml     # Theme metadata and defaults

docs/                    # Theme documentation site

Making Changes

  1. Create a branch for your work
  2. Make changes in src/flexoki_zensical/ or docs/
  3. If you changed docs or presentation, preview with uv run zensical build -c or uv run zensical serve
  4. If you changed packaged assets, templates, or theme metadata, verify uv build

Submitting Changes

  1. Sync your local main branch from upstream
  2. Rebase or merge your work branch onto the latest main if needed
  3. Push the branch to your fork
  4. Open a pull request against main
  5. Include the relevant context, screenshots, or notes for any visible theme changes

Release Process

PyPI publishing is handled by publish.yml. It runs when a GitHub release is published.

Docs deployment is handled by docs.yml. It builds the site on pushes to main and deploys the generated site/ directory to GitHub Pages from the github-pages environment.