docs-builder
Loading

Contribute locally

Follow these steps to contribute to Elastic docs.

To write and push updates to Elastic documentation, you need the following:

  1. A code editor: we recommend Visual Studio Code
  2. Git installed on your machine: learn how here
  3. A GitHub account: sign up here

There are two different ways to install and run docs-builder:

  1. Download, extract, and run the binary (recommended).
  2. Clone the repository and build the binary from source.

This guide uses the first option. If you'd like to clone the repository and build from source, learn how in the project readme.

  1. Download and run the install script

    Run this command to download and install the latest version of docs-builder:

    curl -sL https://ela.st/docs-builder-install | sh

    This downloads the latest binary, makes it executable, and installs it to your user PATH.

    To download and install the binary file manually, refer to Releases on GitHub.

  2. Run docs-builder from a docs folder

    Use the serve command from any docs folder to start serving the documentation at http://localhost:3000. The path to the docset.yml file that you want to build can be specified with -p:

    docs-builder serve

To download and install the binary file manually, refer to Releases on GitHub.

If you get a Permission denied error, make sure that you aren't trying to run a directory instead of a file. Also, grant the binary file execution permissions using chmod +x docs-builder.

  1. Download and run the install script

    Run this command to download and install the latest version of docs-builder:

    iex (New-Object System.Net.WebClient).DownloadString('https://ela.st/docs-builder-install-win')

    This downloads the latest binary, makes it executable, and installs it to your user PATH.

    To download and install the binary file manually, refer to Releases on GitHub.

  2. Run docs-builder from a docs folder

    Use the serve command from any docs folder to start serving the documentation at http://localhost:3000. The path to the docset.yml file that you want to build can be specified with -p:

    docs-builder serve
Tip

Documentation lives in many repositories across Elastic. If you're unsure which repository to clone, you can use the "Edit this page" link on any documentation page to determine where the source file lives.

In this guide, we'll clone the docs-content repository. The docs-content repository is the home for narrative documentation at Elastic. Clone this repo to a directory of your choice:

git clone https://github.com/elastic/docs-content.git

Static-site generators like docs-builder can serve docs locally. This means you can edit the source and see the result in the browser in real time.

To serve the local copy of the documentation in your browser, follow these steps:

  1. Go to the docs-builder clone location 

    cd docs-content

  2. Run docs-builder

    Run the docs-builder binary with the serve command to build and serve the content set to http://localhost:3000. Specify the path to the docset.yml file that you want to build with -p.

    For example:

    docs-builder serve -p ./migration-test

    docs-builder serve -p .\migration-test

  3. Open the documentation in the browser

    Now you should be able to view the documentation locally by navigating to http://localhost:3000.

We write docs in Markdown. Refer to our syntax guide for the flavor of Markdown that we support and all of our custom directives that enable you to add a little extra pizzazz to your docs.

After you've made your changes locally:

You can open a docs preview from the Deployments page of the repository. For example, https://github.com/elastic/docs-content/deployments.

  1. Select the pull request or branch.
  2. Select the ↗ icon next to the timestamp.

The preview URL is in the form https://docs-v3-preview.elastic.dev/elastic/<repository>/tree/branch.