Running docs.konghq.com locally

July 1, 2024 · View on GitHub

We currently only have installation instructions for MacOS. If you're using Windows or Linux, ensure that you have Ruby (see .ruby-version in the repo root for the current version)+ Node.js installed before running the commands in the README

Authentication

SSH authentication: Generate and add an SSH key to your GitHub account. For more information, see Generating a new SSH key and adding it to the ssh-agent and Adding a new SSH key to your GitHub account in GitHub Docs.
Personal access token authentication: Create a personal access token for your GitHub account. For more information, see Creating a personal access token in GitHub Docs.

MacOS Dependency Installation

Install Homebrew and required dependencies

Install developer tools:

xcode-select --install

Install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Install Ruby/Node version manager:

brew install libyaml mise

Configure `git` and ensure that you're using `zsh`

git config --global user.name "Your Name"
git config --global user.email "user@example.com"
chsh -s /bin/zsh

Configure `mise`

echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

If you want to set default versions for your entire system:

mise use -g node@latest

Clone the repository and install dependencies

The method you use to clone the repository differs depending on if you use SSH or a personal access token.

If you are using a personal access token, run the following:

git clone https://github.com/Kong/docs.konghq.com.git

If you are using SSH, run the following:

git clone git@github.com:Kong/docs.konghq.com

Install Ruby/Node:

cd docs.konghq.com
mise install

Install project dependencies:

gem install bundler
make install

At this point you can go back to the README and continue reading the Run Locally instructions.

FAQ

If I get an error while attempting to install dependencies for building the docs site locally, what can I do?

You can try installing next step i.e. gem install liquid-c -v '4.0.0' --source 'https://rubygems.org/' -- --with-cflags=\"-Wno-compound-token-split-by-macro\", to install missing dependencies.