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.
diff validate Validates redirect rules have been applied to the current branch.
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
OS | Architectures |
---|---|
Windows | x64, Arm64 |
Linux | x64, Arm64 |
macOS | x64, Arm64 |
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
If documentation is moved, renamed or deleted, docs-builder
can verify if changes in the working branch in relation to the default branch are reflected in the repository's redirects.yml
. Verification in the local machine is currently supported.
docs-builder diff validate <path>
<path>
is an optional parameter to customize the documentation folder path. It defaults to docs
.
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
./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.
To create a new release trigger the release workflow on the main
branch.
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.
Important
Make sure the release-drafter workflow is finished before publishing the release.
Note
When a release is published, the create-major-tag workflow
will force push a new major tag in the format vX
where X
is the major version of the release.
For example, if the release is 1.2.3
was published, the workflow will force push a new tag v1
on the same commit.