Skip to content

Build Instructions

These instructions only apply if you want to build a local/offline version of the documentation. This is convenient for more involved edits, using an editor of your choice.

Quick Setup

Install Required Software

  1. Download the Python installation package for Windows.
  2. Install Python with the installation wizard. Make sure to enable the "Add Python to PATH" option.
  3. Download and install Git for Windows.

Set up Git LFS
Open a command line window and run the following command: 

git lfs install

Install PIP, Git and Git LFS. When using Homebrew, run the following commands in the terminal: 

python3 -m ensurepip
brew install git git-lfs

Set up Git LFS
Open a terminal and run the following command: 

git lfs install

Install Python, PIP, Git and Git LFS using your package manager:

sudo apt install python3 python3-pip git git-lfs

sudo yum install python python-pip git git-lfs

sudo pacman -S python python-pip git git-lfs

Set up Git LFS:

git lfs install --skip-repo

Clone the Documentation Sources

git clone https://projects.blender.org/blender/blender-developer-docs.git developer-docs
cd developer-docs

This will clone the sources into a developer-docs directory inside the current one and change into it.

Install Material for MkDocs and other dependencies in a virtual environment: 

make setup

Build the Documentation

This is the most commonly used method to build the documentation for editing.

make serve dirty

Use the dirty option when editing single pages, as it makes rebuilds much faster. It only rebuilds the HTML for modified files. Do not use it when modifying the navigation hierarchy, since the option often fails to reflect such changes.

Builds static HTML pages without live reloading.

make

Simply open site/index.html in a browser when done.

Updating

Run the following commands inside the developer-docs directory.

Update the documentation sources

make update

And then build documentation as before.

Update Dependencies

Dependencies should be updated regularly, especially on dependency related build errors.

make setup

Advanced

The make setup command will install dependencies into a virtual environment, using these commands:

python3 -m venv .venv
.venv/bin/python3 -m pip install pip --upgrade
.venv/bin/python3 -m pip install -r requirements.txt --upgrade

This avoids interference with system packages and is the recommended workflow for Python packages in general. You may alternatively install the packages globally,

pip install -r requirements.txt --upgrade