You've reached the home of the latest incarnation of the documentation tooling.

This repository is host to:

• docs-builder command line tool to generate single doc-sets (13mb native code, no dependencies)
• docs-assembler command line tool to assemble all the doc sets. (IN PROGRESS)
• elastic/docs-builder@main Github Action to build and validate a repositories documentation

$ docs-builder --help Usage: [command] [options...] [-h|--help] [--version] Converts a source markdown folder or file to an output folder Options: -p|--path <string?> Defaults to the`{pwd}/docs` folder (Default: null) -o|--output <string?> Defaults to `.artifacts/html` (Default: null) --path-prefix <string?> Specifies the path prefix for urls (Default: null) --force <bool?> Force a full rebuild of the destination folder (Default: null) Commands: generate Converts a source markdown folder or file to an output folder serve Continuously serve a documentation folder at http://localhost:3000. File systems changes will be reflected without having to restart the server.

In the near term native code will be published by CI for the following platforms

And we'll invest time in making sure these are easily obtainable (brew, winget, apt)

For now you can run the tool locally through docker run

docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \ ghcr.io/elastic/docs-builder:edge

This ensures .git/docs and .artifacts (the default output directory) are mounted.

The tool will default to incremental compilation. Only the changed files on subsequent runs will be compiled unless you pass --force to force a new compilation.

docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \ ghcr.io/elastic/docs-builder:edge --force

Through the serve command you can continuously and partially compile your documentation.

docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \ -p 3000:3000 ghcr.io/elastic/docs-builder:edge serve

Each page is compiled on demand as you browse http://localhost:3000 and is never cached so changes to files and navigation will always be reflected upon refresh.

Note the docker image is linux-x86 and will be somewhat slower to invoke on OSX due to virtualization.

The docs-builder tool is available as github action.

Since it runs from a precompiled distroless image ~25mb it's able to execute snappy. (no need to wait for building the tool itself)

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

To set up the tool to publish to GitHub pages use the following configuration. NOTE: In the near feature we'll make this a dedicated single step GitHub action

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

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

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

You can use the .NET CLI to publish a self-contained docs-builder native code binary. (On my M2 Pro mac the binary is currently 16mb)

Install .NET 9.0, then run:

dotnet publish "src/docs-builder/docs-builder.csproj"

The resulting binary ./.artifacts/publish/docs-builder/release/docs-builder will run on machines without .NET installed.

To test performance it's best to build the binary and run outside of docker:

For reference here's the markitpy-doc docset (50k markdown files) currently takes 14s vs several minutes compared to existing surveyed tools

• .NET 9.0 SDK
• Node.js 22.13.1 (LTS)

./build.sh watch

This will monitor code, cshtml template files & static files and reload the application if any changes.

Web assets are reloaded through parcel watch and don't require a recompilation.

Markdown files are refreshed automatically through livereload

Code or layout changes will relaunch the server automatically

This section outlines the process for releasing a new version of this project.

This project uses Semantic Versioning and its version is automatically determined by release-drafter based on the labels of the pull requests merged into the main branch.

See the release-drafter configuration for more details.

Every time a pull request is merged into the main branch, release-drafter will create a draft release or update the existing draft release in the Releases page.

To create a new release you need to publish the existing draft release created by release-drafter.