Instructions on how to checkout the documentation-ng repo, and then install the toolchain needed to convert from Asciidoc to HTML and build the documentation site.

Install git if you don't already have it, and check out the documentation-ng repo as follows,

$ git clone https://github.com/raspberrypi/documentation-ng.git
$ cd documentation-ng

You can install the necessary dependencies on Liunux as follows,

$ sudo apt-get -qq -y install ruby ruby-bundler ruby-dev build-essential python3 git ninja-build

This works on both regular Ubuntu Linux — and has been tested in a minimal Docker container — and also under Raspberry Pi OS if you are working from a Raspberry Pi.

If you don't already have it installed you should go ahead and install HomeBrew,

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Then you need to install Ruby,

$ brew install ruby@2.7

NOTE: Homebrew defaults to Ruby 3.0 which is incompatible with Asciidoctor.

If you're using csh or tcsh add the following lines to your .cshrc or .tcshrc,

setenv PATH /usr/local/opt/ruby/bin:${PATH}
setenv PATH ${PATH}:/usr/local/lib/ruby/gems/2.7.0/bin
setenv LDFLAGS -L/usr/local/opt/ruby@2.7/lib
setenv CPPFLAGS -I/usr/local/opt/ruby@2.7/include
setenv PKG_CONFIG_PATH /usr/local/opt/ruby@2.7/lib/pkgconfig

or if you're using bash add the following lines to your .bash_profile,

export PATH="/usr/local/opt/ruby/bin:$PATH"
export PATH="$PATH:/usr/local/lib/ruby/gems/2.7.0/bin"
export PATH="/usr/local/opt/ruby@2.7/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/ruby@2.7/lib"
export CPPFLAGS="-I/usr/local/opt/ruby@2.7/include"
export PKG_CONFIG_PATH="/usr/local/opt/ruby@2.7/lib/pkgconfig"

Go ahead and brew install the other dependencies,

$ brew install python@3
$ brew install ninja

After you've installed the toolchain, you'll need to install the required Ruby gems. Make sure you're in the documentation-ng directory and then run,

$ bundle install

After you've installed the toolchain and configured the repository you can build the documentation with,

$ make

This will automatically convert the build/jekyll/ files to HTML and put them into documentation/html/.

You can also start a local server to view the compiled site by running,

$ make serve_html

As the local server launches, the local URL will be printed in the terminal -- open this URL in a browser to see the locally-built site.

To build without an active internet connection, run

$ OFFLINE_MODE=1 make

which will copy the fonts.html and header.html files from offline_includes (instead of downloading them from esi.raspberrypi.org).