docs-builder

Distributed documentation tooling for a distributed company.

• docs-builder command line tool to generate single doc-sets

Distributed as native macOS, Linux, and Windows binaries for several CPU architectures.

The documentation files:

• are written in common Markdown with Additional syntax extensions to produce a richer writing and reading experience.
• By conventions the documentation lives in docs folder but the tooling will look for any folder holding the docset.yml configuration file given the current working directory.

[!TIP] To learn how to use docs-builder to contribute docs to Elastic, refer to Contribute to the docs locally.

Distributed documentation

The main driver for folks writing documentation is docs-builder.

This tool builds each repository in isolation and in addition produces a full mapping of all the linkable resources it contains in a links.json file.

Each time a repository successfully builds on its respective main integration branch, our automation will publish its links.json file. For example, Elasticsearch's links.json representing all linkable resources in the Elasticsearch repository.

The docs-builder assemble command then assembles all the repositories in the link-registry using their last known good commit.

This allows us to:

• Validate outbound and inbound links ahead of time, even during local docs-builder builds.
• Snapshot builds: only building commits that produced a links.json
  • Documentation errors in one repository won't affect all the others.
  • Resilient to repositories having build failures on their integration branches, we fall back to the last known good commit.

Installation

Linux / OSX

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

Windows

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

Installing through the script will download the latest version of the tool and make it available in your PATH.

If you want to manually install the tool you can download the latest release from the Releases Page

Building locally

Install .NET 10.0, then run:

./build.sh publishbinaries

After which the locally built binaries will be available at:

• docs-builder: ./.artifacts/publish/docs-builder/release/docs-builder

Getting started

Our Documentation is the best place to learn how to start using the tool locally.

The essential commands are:

• Running docs-builder from the root of any checkout with a docs folder will build the documentation.
  • Running docs-builder consecutively will only rebuild the documentation that has changed.
  • Running docs-builder with the --force flag will force a full rebuild of the documentation.
  • You can target different folders by passing a path to docs-builder --path <path>
• Running docs-builder serve will provide a local server with live reloading.
  • You can leave this command running while you add/remove/rename files in your docs folder.

Other commands to know:

• docs-builder mv Move files and folders
• docs-builder diff validate Manage redirects across doc sets
• docs-builder inbound-links validate-link-reference can be used after a build to validate the local links.json against all published documentation.

For a complete reference of all available commands, refer to the CLI documentation.

Github Action

The docs-builder tool is available as a GitHub action.

It runs as native code on a distroless image ~25mb so there is little overhead invoking the tooling.

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build documentation
        uses: elastic/docs-builder@main

GitHub Pages

To set up the tool to publish to GitHub Pages, use the following configuration.

name: Build the docs

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  docs:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Check out the repo
        uses: actions/checkout@v4

      - name: Publish Github
        uses: elastic/docs-builder/actions/publish@main
        id: deployment
        with:
          continue-on-error: "true"
          private: true

This single action will build and validate the documentation before publishing.

Make sure your repository settings are set up to deploy from GitHub actions see:

https://github.com/elastic/{your-repository}/settings/pages

---

---

Local development

Refer to CONTRIBUTING.md for more information on how to develop locally and contribute to the project.