From 2ce15b14ec88dd5ce23efa80e7cadd4d685ea0a3 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 18 Nov 2025 09:28:42 +0100 Subject: [PATCH 1/2] Update README.md Add links to new contribution docs and edit for style and accuracy. There was also a broken H1 heading. --- README.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 19713a1aa..b0ca7021c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -#docs-builder +# docs-builder [![ci](https://github.com/elastic/docs-builder/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/elastic/docs-builder/actions/workflows/ci.yml) @@ -6,15 +6,20 @@ Distributed documentation tooling for a distributed company. * *`docs-builder`* command line tool to generate single doc-sets -Distributed [as native OSX, Linux and Windows binaries for several CPU architectures.](#installation) +Distributed [as native macOS, Linux, and Windows binaries for several CPU architectures.](#installation) The documentation files: * are written in common Markdown with [Additional syntax extensions](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/) 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](https://www.elastic.co/docs/contribute-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. @@ -56,11 +61,11 @@ After which the locally built binaries will be available at: * **docs-builder**: `./.artifacts/publish/docs-builder/release/docs-builder` -## Getting Started +## Getting started -Our [Documentation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/locally) is the best place to learn how to start using the tool locally. +Our [Documentation](https://www.elastic.co/docs/contribute-docs/locally) is the best place to learn how to start using the tool locally. -The TLDR, however, is +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. @@ -69,14 +74,12 @@ The TLDR, however, is * 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](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/move) * `docs-builder diff validate` [Manage redirects across doc sets](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/redirects#validation) * `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. @@ -141,6 +144,6 @@ https://github.com/elastic/{your-repository}/settings/pages --- -# Local Development +# Local development -See [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to develop locally and contribute to the project. +Refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to develop locally and contribute to the project. From 3b7acc0d262382c19a94c8ccee8c1faeb3b1de49 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 18 Nov 2025 09:32:52 +0100 Subject: [PATCH 2/2] Add .NET line and link to CLI docs --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b0ca7021c..5d0a9577b 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ If you want to manually install the tool you can download the latest release fro ### Building locally -Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run: +Install [.NET 10.0](https://dotnet.microsoft.com/en-us/download/dotnet/10.0), then run: ```bash ./build.sh publishbinaries @@ -80,6 +80,8 @@ The essential commands are: * `docs-builder diff validate` [Manage redirects across doc sets](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/redirects#validation) * `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](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/cli). + ## Github Action The `docs-builder` tool is available as a GitHub action.