Build your first site¶

This walkthrough starts with an empty directory and ends with a local Zensical site using numbered headings and a cross-reference. It also demonstrates prodockit.steps: the procedure you are reading is rendered by that extension.

1. Install Python

   prodockit requires Python 3.10 or later. Install Python for your operating system, then close and reopen the terminal so the new command is on PATH.

   macOS Windows Linux (Ubuntu)

   Install Homebrew first if you do not already have it, then run:

   brew update
   brew install python
   python3 --version
   

   Open PowerShell and run:

   winget install --exact --id Python.Python.3.13
   python --version
   

   If python opens the Microsoft Store, search Windows for Manage app execution aliases and turn off the App Installer aliases for python.exe and python3.exe.

   Open a terminal and run:

   sudo apt update
   sudo apt install python3 python3-venv python3-pip
   python3 --version
   

2. Create and activate a virtual environment

   Create a directory for the site, then create the virtual environment inside it:

   macOS Windows Linux (Ubuntu)

   mkdir my-docs
   cd my-docs
   "$(brew --prefix)/bin/python3" -m venv .venv
   source .venv/bin/activate
   

   In PowerShell:

   mkdir my-docs
   cd my-docs
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

   mkdir my-docs
   cd my-docs
   python3 -m venv .venv
   source .venv/bin/activate
   

   The prompt normally starts with (.venv) after activation. The rest of the walkthrough uses python, which now means the interpreter inside that virtual environment on all three platforms.

3. Install prodockit

   python -m pip install prodockit
   

   Zensical is a core dependency, so this installs the zensical command too. Confirm both commands are available:

   prodockit --version
   zensical --version
   

4. Create the Zensical project

   zensical new .
   

   This creates zensical.toml and a starter docs/ directory without overwriting unrelated files.

5. Enable the two extensions

   Add these tables at the end of zensical.toml:

   [project.markdown_extensions."prodockit.headings"]
   [project.markdown_extensions."prodockit.refs"]
   

   The quoted table names matter: each dotted extension name must remain one TOML key. Extensions are independent, so a project can enable only these two.

6. Add content that uses them

   Replace docs/index.md with:

   # My first document
   
   The detail is in \ref{results}.
   
   ## Method
   
   Describe what you did here.
   
   ## Results {: #results }
   
   Describe what you found here.
   

   prodockit.headings numbers the sections. prodockit.refs turns \ref{results} into a link containing the current number and title, so it stays correct if the sections move.

7. Preview the site

   zensical serve
   

   Open the local address printed in the terminal. Zensical rebuilds the preview when a source file changes; stop it with Ctrl+C.

Where to go next¶

• Browse the authoring reference when you need another document feature.
• Read Generate a PDF when the website is ready to print or submit.
• Follow the project maintenance cycle when the first site becomes a maintained project, then use the command-line map to choose a command safely.