building.md

Building the DuckDB documentation

The site is built using Jekyll used by GitHub Pages.

Using a local Jekyll installation

Prerequisites

The site is built using Jekyll 3.9.x, which requires Ruby v2.7.x.

Install Jekyll and the other required Ruby dependencies using Bundler:

bundle install

Some environments require additional tweaking:

• If you are on Windows, run these two commands to ensure Jekyll works:

  gem uninstall eventmachine
  gem install eventmachine --platform ruby

• If you are using macOS running on an Apple Silicon CPU (M1, M2, etc.), you need to specify the OpenSSL version when installing Ruby:

  export PKG_CONFIG_PATH="$(brew --prefix [email protected])/lib/pkgconfig"
  ruby-install 2.7.8 -- --with-openssl-dir=$(brew --prefix [email protected])
  gem uninstall eventmachine
  gem install eventmachine

For more details on using Jekyll, consult GitHub's instructions.

Syntax highlighter

We use a fork of the Rouge syntax highligher, which is extended with keywords not in standard SQL (e.g., RETURNING, ASOF). This is automatically installed by Bundler.

Serving the site using a local Jekyll installation

Serve the website (latest only, archives excluded) with:

scripts/serve.sh

The website can be browsed by going to http://localhost:4000/docs/ in your browser.

Serve the full website with:

scripts/serve-full.sh

Using Docker

Prerequisites

Install Docker.

Serving the site from Docker

For portability, we provide a Docker image.

First, build the image using:

scripts/docker-build.sh

Serve the website (latest only, archives excluded) with:

scripts/docker-serve.sh

The website can be browsed by going to http://localhost:4000/docs/ in your browser.

Serve the full website with:

scripts/docker-serve-full.sh

To stop the container, run:

scripts/docker-stop.sh

With a Dev Container

If you are using a Dev Container, click the green Code button to the top right to open a new codespace with this repository initialized.