Contribute locally
This document describes the process to set up Elastic documentation repositories locally, enabling you to contribute effectively.
To write and push updates to Elastic documentation, you need the following:
- A code editor: We recommend Visual Studio Code
- Git installed on your machine: To install Git, see How to install Git
- A GitHub account: Sign up for an account on Github
There are two different ways to install and run docs-builder
:
- Download, extract, and run the binary (recommended).
- Clone the repository and build the binary from source.
This guide follows the first option. If you'd like to clone the repository and build from source, learn how in the project readme.
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 to
/usr/local/bin
, makes it an executable, and installs it to your user PATH. This means you can use thedocs-builder
command from any location of your machine to deploy and run documentation repositories likedocs-builder
,docs-content
and so on.You can optionally specify a specific version to install:
DOCS_BUILDER_VERSION=0.40.0 curl -sL https://ela.st/docs-builder-install | sh
Run docs-builder from a docs folder
Use the
serve
command from anydocs
folder to start serving the documentation at http://localhost:3000:docs-builder serve
The path to the
docset.yml
file that you want to build can be specified with-p
.ImportantRun
docs-builder
withoutserve
to run a full build and detect errors.
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
.
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. You can optionally specify a specific version to install:
$env:DOCS_BUILDER_VERSION = '0.40.0'; iwr -useb https://ela.st/docs-builder-install.ps1 | iex
To download and install the binary file manually, refer to Releases on GitHub.
Run docs-builder from a docs folder
Use the
serve
command from any docs folder to start serving the documentation at http://localhost:3000:docs-builder serve
The path to the
docset.yml
file that you want to build can be specified with-p
.
Documentation is hosted 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 the location of the source file.
Clone the docs-content
repository to a directory of your choice. The docs-content
repository is the home for most narrative documentation at Elastic.
git clone https://github.com/elastic/docs-content.git
We write docs in Markdown. Refer to our syntax guide for the flavor of Markdown we support and all of our custom directives that enable you to add a little extra pizzazz to your docs.
This documentation is cumulative. This means that a new set of docs is not published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content. Learn how to write cumulative documentation.
Some repositories use a tagged branching strategy, which means that their docs are published from a branch that is not main
or master
. In these cases, documentation changes need to be made to main
or master
, and then backported to the relevant branches.
For detailed backporting guidance, refer to the example in Choose the docs branching strategy for a repository.
To determine the published branches for a repository, find the repository in assembler.yml
.
Before pushing your changes, verify all of them locally .
docs-builder
The build process informs you of any critical errors or warnings. It also shows less critical issues as Hints. Make sure you don't introduce any new build errors, warnings, or hints.
After you've made your changes locally:
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:
-
Change directory to a docs repository
For example,
docs-content
:cd docs-content
-
Run docs-builder
Run the
docs-builder
binary with theserve
command to build and serve the content set to http://localhost:3000. If necessary, specify the path to thedocset.yml
file that you want to build with-p
.For example:
docs-builder serve
docs-builder serve -p .\docs-content
-
Open the documentation in the browser
Now you should be able to view the documentation locally by navigating to http://localhost:3000.