### Create setup virtual environment

Source: https://prodockit.org/installation

Create the setup virtual environment in the repositories directory. The environment is stored in a .venv folder alongside the repository folders.

```bash
"$(brew --prefix python@3.14)/bin/python3.14" -m venv .venv

```

```powershell
py -3.14 -m venv .venv

```

```bash
python3.14 -m venv .venv

```

--------------------------------

### Install Node.js and npm on Ubuntu

Source: https://prodockit.org/manual-install

Installs Node.js and npm on Ubuntu using apt. If the installed version is older than required, follow the NodeSource installation instructions for a supported release.

```bash
sudo apt update
sudo apt install -y nodejs npm

```

--------------------------------

### Install Prodockit on Windows

Source: https://prodockit.org/getting-started

Install or update Prodockit in the active project environment on Windows.

```bash
pip install --upgrade prodockit
```

--------------------------------

### Verify prodockit installation with --version

Source: https://prodockit.org/adopt

Confirm that the prodockit command comes from the active project environment. The installation step makes the command available for the first run.

```bash
prodockit --version


```

--------------------------------

### npm allow-scripts warning output

Source: https://prodockit.org/manual-install

Example output from npm when a package has install scripts not covered by allowScripts. The warning indicates Puppeteer's postinstall script is skipped; the install still succeeds, but a later PDF build may fail to find a browser.

```text
Run `npm audit` for details.
npm warn allow-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn allow-scripts   puppeteer (postinstall: node install.mjs)

```

--------------------------------

### Preview website locally with zensical serve

Source: https://prodockit.org/manual-install

Starts a local preview server and prints the address to open in the terminal. Press Ctrl+C to stop the preview.

```text
zensical serve

```

--------------------------------

### Install prodockit[testing] with pip

Source: https://prodockit.org/devcons/testing

Install the prodockit testing extras. The first command uses pip3 for macOS, the second for Windows, and the third for Linux (Ubuntu). If pip or pip3 does not work, try the alternative; keep the intended virtual environment active and check that the alternative command belongs to it before installing packages.

```bash
pip3 install "prodockit[testing]"

```

```bash
pip install "prodockit[testing]"

```

```bash
pip install "prodockit[testing]"

```

--------------------------------

### Install MSYS2 with winget

Source: https://prodockit.org/manual-install

Installs MSYS2, which provides the Pango libraries WeasyPrint needs on Windows. Run this before installing the graphics libraries.

```powershell
winget install --id MSYS2.MSYS2

```

--------------------------------

### Install Node.js on macOS with Homebrew

Source: https://prodockit.org/manual-install

Installs Node.js on macOS using Homebrew. Run this before installing the diagram and maths toolchains.

```bash
brew install node

```

--------------------------------

### Install Node.js on Windows with winget

Source: https://prodockit.org/manual-install

Installs Node.js on Windows using winget. After installation, close and reopen PowerShell to update PATH, then change to the project directory and activate the virtual environment.

```powershell
winget install OpenJS.NodeJS.LTS

```

--------------------------------

### Approve Puppeteer script and reinstall Mermaid

Source: https://prodockit.org/manual-install

Approve Puppeteer's install script and reinstall Mermaid dependencies. Run this if a later PDF build reports it cannot find a browser, because recent npm versions skip Puppeteer's setup step that downloads the headless browser.

```bash
npm approve-scripts puppeteer --prefix tools/mermaid
npm ci --prefix tools/mermaid

```

--------------------------------

### sync-repo output example

Source: https://prodockit.org/devcons/repo-metadata

Example output from prodockit sync-repo. It reports only what actually changed, here the repo_url, repo_name, and edit_uri values.

```text
Detected GitHub remote (https://github.com/you/your-repo); updated: repo_url, repo_name, edit_uri

```

--------------------------------

### Install Visual Studio Code on macOS with Homebrew

Source: https://prodockit.org/manual-install

Install Visual Studio Code on macOS using Homebrew. Run these commands in the Terminal after installing Homebrew and reopening the Terminal.

```bash
brew update
brew install --cask visual-studio-code

```

--------------------------------

### Example prompt with active virtual environment

Source: https://prodockit.org/manual-install

Example of the shell prompt after activating the virtual environment. The `(.venv)` prefix indicates the environment is active.

```bash
(.venv) yourname@Mac your-project %

```

--------------------------------

### Install prodockit[index] on Windows

Source: https://prodockit.org/pdf

Install the prodockit package with the index extra on Windows. Required only when the document enables the PDF index, which needs pymupdf.

```bash
pip install "prodockit[index]"

```

--------------------------------

### Return to repositories directory and activate virtual environment

Source: https://prodockit.org/manual-install

Return to the repositories directory and activate the virtual environment. The examples use 'repos'; substitute the name you chose. The macOS and Linux (Ubuntu) commands are identical, while Windows uses PowerShell with an execution policy change.

```bash
cd ~/repos
source .venv/bin/activate

```

```powershell
cd ~/repos
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.\venv\Scripts\Activate.ps1

```

```bash
cd ~/repos
source .venv/bin/activate

```

--------------------------------

### Install Git on Linux with apt

Source: https://prodockit.org/manual-install

Install or update Git on Linux (Ubuntu/Debian) using apt. Run in a terminal.

```bash
sudo apt update
sudo apt install git

```

--------------------------------

### Install Pandoc 3.10.1 with prodockit.toolchain

Source: https://prodockit.org/pdf

Install the exact supported Pandoc version (3.10.1) into the activated project environment without changing a system or Homebrew Pandoc. Run on all three operating systems.

```bash
python -m prodockit.toolchain install-pandoc --version 3.10.1

```

--------------------------------

### Install Pango on macOS

Source: https://prodockit.org/manual-install

Installs Pango, a system library required by WeasyPrint for PDF generation. Pango is not a Python package, so pip cannot install it. Skipping it causes `prodockit pdf` to fail with `pandoc exited with status 43`.

```bash
brew install pango

```

--------------------------------

### Install project packages and Pandoc with python -m pip

Source: https://prodockit.org/manual-install

Installs the project packages and the exact Pandoc version inside the active virtual environment. Using python -m pip ties the install to the active environment; do not use sudo pip and do not continue if the prompt has lost its (.venv) prefix.

```bash
python -m pip install -r requirements.txt
python -m prodockit.toolchain install-pandoc --version 3.10.1

```

--------------------------------

### Install Git on macOS with Homebrew

Source: https://prodockit.org/manual-install

Install or update Git on macOS using Homebrew. Run in the Terminal.

```bash
brew install git

```

--------------------------------

### Install Git on Windows with winget

Source: https://prodockit.org/manual-install

Install Git on Windows using winget in an Administrator PowerShell window. Close and reopen PowerShell afterward to update PATH.

```powershell
winget install Git.Git

```

--------------------------------

### Install Visual Studio Code on Linux with apt

Source: https://prodockit.org/manual-install

Install Visual Studio Code on Linux (Ubuntu/Debian) from a downloaded .deb package. Replace <file> with the actual filename.

```bash
sudo apt install ./<file>.deb

```

--------------------------------

### Check prodockit version and help

Source: https://prodockit.org/command-line

Use to confirm the installed prodockit release and list the commands it provides. The first command prints the installed release; the second lists the commands supplied by that release.

```bash
prodockit --version
prodockit --help

```

--------------------------------

### Install Pandoc on macOS

Source: https://prodockit.org/manual-install

Installs Pandoc, which `prodockit pdf` shells out to. Pandoc hands the result to WeasyPrint for layout. Skipping it causes `prodockit pdf` to fail with `pandoc exited with status 43`.

```bash
brew install pandoc

```

--------------------------------

### Verify release in a clean environment

Source: https://prodockit.org/devcons/releasing

Creates a temporary virtual environment, installs the released package version, and verifies the installed CLI reports the expected version. Use the platform's corresponding activation or executable path on Windows.

```bash
python -m venv /tmp/prodockit-release-check
/tmp/prodockit-release-check/bin/python -m pip install "prodockit==0.42.0"
/tmp/prodockit-release-check/bin/prodockit --version
```

--------------------------------

### Install Pango for ARM64/aarch64 Python

Source: https://prodockit.org/manual-install

Installs the Pango library for ARM64/aarch64 Python and sets $MsysBin to the clangarm64 bin directory. Use this when Python reports ARM64 or aarch64.

```powershell
C:\msys64\usr\bin\bash.exe -lc "pacman -S --noconfirm --needed mingw-w64-clang-aarch64-pango"
$MsysBin = "C:\msys64\clangarm64\bin"

```

--------------------------------

### Install Pango for AMD64/x86_64 Python

Source: https://prodockit.org/manual-install

Installs the Pango library for AMD64/x86_64 Python and sets $MsysBin to the ucrt64 bin directory. Use this when Python reports AMD64 or x86_64.

```powershell
C:\msys64\usr\bin\bash.exe -lc "pacman -S --noconfirm --needed mingw-w64-ucrt-x86_64-pango"
$MsysBin = "C:\msys64\ucrt64\bin"

```

--------------------------------

### Install Pandoc 3.10.1 with winget

Source: https://prodockit.org/manual-install

Installs the exact Pandoc release (3.10.1) used by Bootstrap and CI. The package is published under the author's name, John MacFarlane, not as Pandoc.Pandoc.

```powershell
winget install --id JohnMacFarlane.Pandoc --exact --version 3.10.1

```

--------------------------------

### Start SSH agent with eval $(ssh-agent -s)

Source: https://prodockit.org/manual-install

Starts the SSH agent on macOS or Linux when it is not running. Run this before repeating the ssh-add command if it fails with an agent connection error.

```bash
eval "$(ssh-agent -s)"

```

--------------------------------

### Install Pandoc 3.10.1 and WeasyPrint dependencies on Debian/Ubuntu

Source: https://prodockit.org/manual-install

Installs the exact Pandoc 3.10.1 release used by Bootstrap, plus the Pango/HarfBuzz libraries and fonts that WeasyPrint needs for PDF generation. Requires a supported Debian or Ubuntu release; on older releases libharfbuzz-subset0 is unavailable and the distribution must be upgraded.

```bash
sudo apt update
sudo apt install -y curl
curl -fsSL -o /tmp/pandoc.deb "https://github.com/jgm/pandoc/releases/download/3.10.1/pandoc-3.10.1-1-$(dpkg --print-architecture).deb"
sudo apt install -y /tmp/pandoc.deb
sudo apt install -y \
  libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0 \
  fonts-inter fonts-jetbrains-mono

```

--------------------------------

### Activate virtual environment (macOS/Linux/Windows)

Source: https://prodockit.org/manual-install

Activate the project's virtual environment. The first and third blocks are the macOS/Linux (Ubuntu) commands; the middle block is the Windows PowerShell command. Run the appropriate one for your platform before installing dependencies.

```bash
source .venv/bin/activate

```

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.\venv\Scripts\Activate.ps1

```

```bash
source .venv/bin/activate

```

--------------------------------

### Install Prodockit on Windows

Source: https://prodockit.org/devcons/bootstrap

Upgrades pip and installs Prodockit in the active setup virtual environment on Windows. The pip command must belong to the active environment.

```bash
pip install --upgrade pip
pip install --upgrade prodockit

```

--------------------------------

### Create Zensical site

Source: https://prodockit.org/getting-started

Initialize a new Zensical starter site in the current directory.

```bash
zensical new .
```

--------------------------------

### Install Prodockit on macOS

Source: https://prodockit.org/devcons/bootstrap

Upgrades pip and installs Prodockit in the active setup virtual environment on macOS. The pip3 command must belong to the active environment.

```bash
pip3 install --upgrade pip
pip3 install --upgrade prodockit

```

--------------------------------

### Check site configuration and build

Source: https://prodockit.org/getting-started

Run these commands to verify the ProDockIt environment and build the site. Stop if any command fails.

```bash
pdk diag
zensical build --clean --strict
```

--------------------------------

### Install Mermaid dependencies

Source: https://prodockit.org/manual-install

Install Mermaid's locked dependencies from tools/mermaid. Uses the exact versions in the lockfile, matching the automated builds. Creates a node_modules folder that is not committed; run again after re-cloning.

```bash
npm ci --prefix tools/mermaid

```

--------------------------------

### Install MathJax dependencies

Source: https://prodockit.org/manual-install

Install MathJax's locked dependencies from tools/mathjax. Uses the exact versions in the lockfile, matching the automated builds. Creates a node_modules folder that is not committed; run again after re-cloning.

```bash
npm ci --prefix tools/mathjax

```