docs-builder

Distributed documentation tooling for a distributed company.

This repository is host to:

• docs-builder command line tool to generate single doc-sets
• docs-assembler command line tool to assemble all the doc sets.

Both get distributed as native OSX, 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.

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-assembler tool 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 9.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
• docs-assembler: ./.artifacts/publish/docs-assembler/release/docs-assembler

Getting Started

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

The TLDR, however, is

• 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.

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.

environment:
  name: github-pages
  url: ${{ steps.deployment.outputs.page_url }}
steps:
  - uses: actions/checkout@v4
    
  - name: Publish Github
    uses: elastic/docs-builder/actions/publish@main
    id: deployment

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

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