---
title: "Build the docs"
url: "https://docs.yugabyte.com/stable/contribute/docs/docs-build/"
---

# Build the docs

Build the YugabyteDB docs locally

## Prerequisites

To run the docs site locally and edit the docs, you'll need:

- **A text editor**, such as [Visual Studio Code](https://code.visualstudio.com "Visual Studio Code").
- [**Node.js**](https://nodejs.org/en/download/ "Node.js") LTS (22) using [NVM](https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script "NVM") : `nvm install 22.14.0`
- **A GitHub account**.

In addition to the above, there are tools you'll need to install, and the steps vary depending on your machine.

- [macOS](#macos)
- [Ubuntu](#ubuntu)

<!--THE END-->

- **Command-line tools for Xcode** on macOS.
  
  ```sh
  $ xcode-select --install
  ```
  
  Xcode is many gigabytes. Install the command-line tools unless you actually need the full Xcode.
- [**Homebrew**](https://brew.sh "Homebrew") on macOS.
- **Python** (v3.10 or earlier): You need `python` to be available somewhere in your shell path.
  
  Recent versions of macOS have only a `python3` executable, as does the Homebrew install. You can use [pyenv](https://github.com/pyenv/pyenv "pyenv") to manage multiple versions of python on your system. Make sure to point to Python v3.10 or earlier.
- **Hugo**: Install Hugo v0.154.5. Follow these steps:
  
  - Unpin Hugo to stop its formula from being updated - `brew unpin hugo`
  - Uninstall any older version if installed - `brew uninstall hugo`
  - Download the v0.154.5 formula file from [Homebrew's repository](https://github.com/Homebrew/homebrew-core/blob/main/Formula/h/hugo.rb "Homebrew's repository").
  - Install the downloaded formula into a tap - `brew install hugo.rb`
    
    - Create a tap if you haven't already - `brew tap-new mytap/local-hugo`
    - Move the formula file - `mv hugo.rb $(brew --repository mytap/local-hugo)/Formula/`
    - Install - `brew install mytap/local-hugo/hugo`
  - Lastly, prevent automatic updates of Hugo version - `brew pin hugo`
- **Go**: `brew install go` installs the latest version.
- **Git client**: The system Git binary is out of date, but works. If you like, you can use Homebrew to get a newer version (`brew install git`).

<!--THE END-->

- **Python** (v3.10 or earlier): You need `python` to be available somewhere in your shell path.
  
  Recent versions of Ubuntu default to `python` and point to Python 3. If not, you can install a new version of Python, and use [pyenv](https://github.com/pyenv/pyenv "pyenv") to manage multiple Python versions. Ensure you're using Python 3.10 or earlier.
- **Hugo**: Install the `hugo_extended_0.154.5` version from the [official Hugo releases](https://github.com/gohugoio/hugo/releases "official Hugo releases") for your Linux machine architecture. Make sure the `hugo` binary is available in the shell path.
- **Go**: Install latest Go from the [official Go website](https://golang.org/dl/ "official Go website").
- **Git client**: Ubuntu includes Git by default, but ensure you have the latest version (`sudo apt-get install git`).

## Configure Hugo

By default, Hugo uses the operating system's temporary directory to cache modules, which can cause some problems. You can avoid those problems by telling Hugo to put its cache elsewhere.

Add a line similar to the following to your `.bashrc` or `.zshrc` file:

```sh
export HUGO_CACHEDIR=~/.hugo-cache
```

Create the folder with `mkdir ~/.hugo-cache`, then start a new terminal session.

## Fork the repository

1. To make the commands in this section work correctly when you paste them, set an environment variable to store your GitHub username. (Replace `your-github-id` in the following command with your own GitHub ID.)
   
   ```sh
   export GITHUB_ID=your-github-id
   ```
2. Fork the [`yugabyte-db` GitHub repository](https://github.com/yugabyte/yugabyte-db/ "yugabyte-db GitHub repository").
3. Create a local clone of your fork:
   
   ```sh
   git clone https://github.com/$GITHUB_ID/yugabyte-db.git
   ```
4. Identify your fork as *origin* and the original YB repository as *upstream*:
   
   ```sh
   cd yugabyte-db/
   git remote set-url origin https://github.com/$GITHUB_ID/yugabyte-db.git
   git remote add upstream https://github.com/yugabyte/yugabyte-db.git
   ```
5. Make sure that your local repository is still current with the upstream Yugabyte repository:
   
   ```sh
   cd docs/
   git checkout master
   git pull upstream master
   ```

Refer to [Edit an existing page](/stable/contribute/docs/docs-edit/#edit-an-existing-page "Edit an existing page") to create a new branch, commit your changes, and create a pull request.

## Build the docs site

The YugabyteDB documentation is written in Markdown, and processed by Hugo (a static site generator) into an HTML site.

To get the docs site running in a live-reload server on your local machine, run the following commands:

```sh
cd yugabyte-db/docs  # Make sure this is YOUR fork.
npm ci               # Only necessary the first time you clone the repo.
hugo mod get -u      # Installs Hugo as a dependency of the site.
hugo mod clean       # Only necessary the first time you clone the repo.
npm start            # Do this every time to build the docs and launch the live-reload server.
```

The live-reload server runs at [http://localhost:1313/](http://localhost:1313/ "http://localhost:1313/") unless port 1313 is already in use. Check the output from the `npm start` command to verify the port.

When you're done, type Ctrl-C stop the server.

### Optional: Run builds more quickly

If you are only working in `preview` or `stable`, you can start the live-reload server more quickly using the following:

```sh
npm run fast
```

This builds only the `preview` and `stable` directories, and does not generate syntax diagrams.

### Optional: Run a full build

The live-reload server is the quickest way to get the docs running locally. If you want to run the build exactly the same way the CI pipeline does for a deployment, do the following:

```sh
cd yugabyte-db/docs
npm run build
```

When the build is done, the `yugabyte-db/docs/public` folder contains a full HTML site, exactly the same as what's deployed on the live website at [https://docs.yugabyte.com/](https://docs.yugabyte.com/ "https://docs.yugabyte.com/").

## Troubleshooting

- Make sure the GUI installer for the command-line tools finishes with a dialog box telling you the install succeeded. If not, run it again.
- If you get an error about missing command-line tools, make sure xcode-select is pointing to the right directory, and that the directory contains a `usr/bin` subdirectory. Run `xcode-select -p` to find the path to the tools. Re-run xcode-select --install.
- If the live-reload server (`npm start`) is returning a Hugo error — say, about shortcodes — re-run `hugo mod clean`, followed by `npm start`. Also, be sure you've followed the instructions on this page to [configure Hugo](#configure-hugo "configure Hugo").
- Make sure your tools are up-to-date. Run `brew update` periodically, and if it reports anything out of date, run `brew upgrade`.
- If you get an error about missing modules, try running `npm install`.

## Next steps

Need to edit an existing page? [Start editing](/stable/contribute/docs/docs-edit/ "Start editing") it now. (Optional: [set up your editor](/stable/contribute/docs/docs-editor-setup/ "set up your editor").)

Adding a new page? Use the [overview of sections](/stable/contribute/docs/docs-layout/ "overview of sections") to find the appropriate location.