Skip to content

Zensical tasksλ︎

Zensical is a static site generator that provides a rich authoring system to create excellent usability experience.

All Practicalli Books are switching to Zensical in 2026, migrating from Material for MkDocs.

Zensical Installλ︎

Install Zensical as a tool using UV, along with the catppuccin-zensical theme plugin.

The --upgrade option will update to the latest version of zensical even if a version is already installed.

docs-install:  ## Install or upgrade Zensical with Catppuccin theme plugin
    uv tool install zensical --with catppuccin-zensical --upgrade

Document Generationλ︎

DOCS_SERVER Makefile variable is used to simplify maintenance of tasks by avoiding repetition.

# -- Makefile Variables -------------------------- #
DOCS_SERVER := zensical serve --dev-addr localhost:7777
# ------------------------------------------------ #

# --- Documentation Generation  ------------------ #
docs:  ## Build and run docs in local server
    $(info -- Local Server --------------------------)
    $(DOCS_SERVER)

docs-open:  ## Build docs, run server & open browser
    $(info -- Local Server & Browser ----------------)
    $(DOCS_SERVER) --open

docs-build:  ## Build docs locally
    $(info -- Build Docs Website --------------------)
    zensical build

docs-debug:  ## Run local server in debug mode
    $(info -- Local Server Debug --------------------)
    $(DOCS_SERVER) -v

dist: docs-build ## Build mkdocs website
# ------------------------------------------------ #

Complete Makefileλ︎

The complete Practicalli Makefile includes tasks to run Megalinter locally and update GitHub actions (using Practicalli Clojure CLI Config).

# ------------------------------------------------ #
# Practicalli Makefile
#
# Consistent set of targets to support local book development
#
# `-` before a command ignores any errors returned
# ------------------------------------------------ #

# Requirements
# - python
# - uv
# - clojure & practicalli cli config (dependency check)
# - docker (run megalinter locally)
# - mega-linter-runner
# ------------------------------------------------ #

# -- Makefile task config ------------------------ #
# .PHONY: ensures target used rather than matching file name
# https://makefiletutorial.com/#phony
.PHONY: all clean dist docs lint pre-commit-check
# ------------------------------------------------ #

# -- Makefile Variables -------------------------- #
# run help if no target specified
.DEFAULT_GOAL := help
# Column the target description is printed from
HELP-DESCRIPTION-SPACING := 24

# SHELL := /usr/bin/zsh

# Tool variables
MEGALINTER_RUNNER := npx mega-linter-runner --flavor documentation --env "'MEGALINTER_CONFIG=.github/config/megalinter.yaml'" --remove-container
DOCS_SERVER := zensical serve --dev-addr localhost:7777
OUTDATED_FILE := outdated-$(shell date +%y-%m-%d-%T).md
# ------------------------------------------------ #

# -- Code Quality -------------------------------- #
pre-commit-check: lint ## Format and lint with Megalinter

lint:  ## Run MegaLinter with custom configuration (node.js required)
    $(info -- MegaLinter Runner ---------------------)
    $(MEGALINTER_RUNNER)

lint-fix:  ## Run MegaLinter with applied fixes and custom configuration (node.js required)
    $(info -- MegaLinter Runner fix errors ----------)
    $(MEGALINTER_RUNNER) --fix

lint-clean:  ## Clean MegaLinter report information
    $(info -- MegaLinter Clean Reports --------------)
    - rm -rf ./megalinter-reports

megalinter-upgrade:  ## Upgrade MegaLinter config to latest version
    $(info -- MegaLinter Upgrade Config -------------)
    npx mega-linter-runner@latest --upgrade

dependencies-outdated: ## Report new versions of library dependencies and GitHub action
    $(info -- Search for outdated libraries ---------)
    - clojure -T:search/outdated > $(OUTDATED_FILE)

dependencies-update: ## Update all library dependencies and GitHub action
    $(info -- Search for outdated libraries ---------)
    - clojure -T:update/dependency-versions > $(OUTDATED_FILE)
# ------------------------------------------------ #

# --- Documentation Generation  ------------------ #
docs-install:  ## Install or upgrade Zensical with Catppuccin theme plugin
    uv tool install zensical --with catppuccin-zensical --upgrade

docs:  ## Build and run docs in local server
    $(info -- Local Server --------------------------)
    $(DOCS_SERVER)

docs-open:  ## Build docs, run server & open browser
    $(info -- Local Server & Browser ----------------)
    $(DOCS_SERVER) --open

docs-build:  ## Build docs locally
    $(info -- Build Docs Website --------------------)
    zensical build

docs-debug:  ## Run local server in debug mode
    $(info -- Local Server Debug --------------------)
    $(DOCS_SERVER) -v

dist: docs-build ## Build Zensical website
# ------------------------------------------------ #

# -- Version Control ----------------------------- #
git-sr:  ## status list of git repos under current directory
    $(info -- Multiple Git Repo Status --------------)
    mgitstatus -e --flatten

git-status:  ## status details of git repos under current directory
    $(info -- Multiple Git Status -------------------)
    mgitstatus
# ------------------------------------------------ #

# -- Help ---------------------------------------- #
# Source: https://nedbatchelder.com/blog/201804/makefile_help_target.html

help:  ## Describe available tasks in Makefile
    @grep '^[a-zA-Z]' $(MAKEFILE_LIST) | \
    sort | \
    awk -F ':.*?## ' 'NF==2 {printf "\033[36m  %-$(HELP-DESCRIPTION-SPACING)s\033[0m %s\n", $$1, $$2}'
# ------------------------------------------------ #