Repository files navigation

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 distributedas native OSX, Linux and Windows binaries for several CPU architectures.

The documentation files:

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

The main driver for folks writing documentation isdocs-builder.This tool builds each repository in isolation and in addition produces a full mapping of all the linkable resources it contains in alinks.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.

Thedocs-assembler tool then assembles all the repositories in thelink-registry using their last known good commit.

This allows us to:

• Validate outbound and inbound links ahead of time, even during localdocs-builder builds.
• Snapshot builds: only building commits that produced alinks.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.

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

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

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

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

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

The TLDR, however, is

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

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

Thedocs-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-lateststeps:      -uses:actions/checkout@v4      -name:Build documentationuses:elastic/docs-builder@main

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

environment:name:github-pagesurl:${{ steps.deployment.outputs.page_url }}steps:  -uses:actions/checkout@v4      -name:Publish Githubuses:elastic/docs-builder/actions/publish@mainid: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

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