From 2c197f7fe5543ede2f5708e4bb749a31d142acfb Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Mon, 29 Sep 2025 19:17:21 +0200 Subject: [PATCH 01/86] Add CLI command documentation drafts - Introduced draft documentation for all CLI commands under `docs/cli`. - Updated `_docset.yml` to include new CLI documentation. - Adjusted navigation order and reinstated missing migration files. --- docs/_docset.yml | 68 +++++++---- docs/cli/assemble.md | 35 ++++++ docs/cli/assembler-bloom-filter-create.md | 14 +++ docs/cli/assembler-bloom-filter-lookup.md | 14 +++ docs/cli/assembler-build.md | 26 +++++ docs/cli/assembler-clone.md | 23 ++++ docs/cli/assembler-config-init.md | 17 +++ docs/cli/assembler-content-source-match.md | 15 +++ docs/cli/assembler-content-source-validate.md | 7 ++ docs/cli/assembler-deploy-apply.md | 20 ++++ docs/cli/assembler-deploy-plan.md | 23 ++++ docs/cli/assembler-deploy-update-redirects.md | 17 +++ docs/cli/assembler-index.md | 71 +++++++++++ ...bler-navigation-validate-link-reference.md | 14 +++ docs/cli/assembler-navigation-validate.md | 9 ++ docs/cli/assembler-serve.md | 17 +++ docs/cli/diff-validate.md | 14 +++ docs/cli/generate.md | 110 ++++++++++++++++++ docs/cli/inbound-links-validate-all.md | 9 ++ .../inbound-links-validate-link-reference.md | 17 +++ docs/cli/inbound-links-validate.md | 17 +++ docs/cli/index-command.md | 71 +++++++++++ docs/cli/index.md | 30 +++++ docs/cli/mv.md | 25 ++++ docs/cli/serve.md | 18 +++ docs/configure/site/legacy-url-mappings.md | 3 + 26 files changed, 683 insertions(+), 21 deletions(-) create mode 100644 docs/cli/assemble.md create mode 100644 docs/cli/assembler-bloom-filter-create.md create mode 100644 docs/cli/assembler-bloom-filter-lookup.md create mode 100644 docs/cli/assembler-build.md create mode 100644 docs/cli/assembler-clone.md create mode 100644 docs/cli/assembler-config-init.md create mode 100644 docs/cli/assembler-content-source-match.md create mode 100644 docs/cli/assembler-content-source-validate.md create mode 100644 docs/cli/assembler-deploy-apply.md create mode 100644 docs/cli/assembler-deploy-plan.md create mode 100644 docs/cli/assembler-deploy-update-redirects.md create mode 100644 docs/cli/assembler-index.md create mode 100644 docs/cli/assembler-navigation-validate-link-reference.md create mode 100644 docs/cli/assembler-navigation-validate.md create mode 100644 docs/cli/assembler-serve.md create mode 100644 docs/cli/diff-validate.md create mode 100644 docs/cli/generate.md create mode 100644 docs/cli/inbound-links-validate-all.md create mode 100644 docs/cli/inbound-links-validate-link-reference.md create mode 100644 docs/cli/inbound-links-validate.md create mode 100644 docs/cli/index-command.md create mode 100644 docs/cli/index.md create mode 100644 docs/cli/mv.md create mode 100644 docs/cli/serve.md diff --git a/docs/_docset.yml b/docs/_docset.yml index dd11ae52c..dbbab6312 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -46,26 +46,6 @@ toc: - file: branching-strategy.md - file: add-repo.md - file: release-new-version.md - - folder: migration - children: - - file: index.md - - folder: freeze - children: - - file: index.md - - file: gh-action.md - - file: syntax.md - - file: ia.md - - file: versioning.md - - file: engineering.md - - folder: guide - children: - - file: index.md - - file: working-in-docs-content.md - - file: automated.md - - file: tooling.md - - file: move-ref-docs.md - - file: mapping.md - - file: how-to-set-up-docs-previews.md - folder: configure children: - file: index.md @@ -74,9 +54,9 @@ toc: - file: index.md - file: content.md - file: navigation.md + - file: products.md - file: versions.md - file: legacy-url-mappings.md - - file: products.md - folder: content-set children: - file: index.md @@ -121,6 +101,52 @@ toc: - file: tabs.md - file: tagged_regions.md - file: titles.md + - folder: cli + children: + - file: index.md + - file: assemble.md + - file: assembler-bloom-filter-create.md + - file: assembler-bloom-filter-lookup.md + - file: assembler-build.md + - file: assembler-clone.md + - file: assembler-config-init.md + - file: assembler-content-source-match.md + - file: assembler-content-source-validate.md + - file: assembler-deploy-apply.md + - file: assembler-deploy-plan.md + - file: assembler-deploy-update-redirects.md + - file: assembler-index.md + - file: assembler-navigation-validate.md + - file: assembler-navigation-validate-link-reference.md + - file: assembler-serve.md + - file: diff-validate.md + - file: generate.md + - file: inbound-links-validate.md + - file: inbound-links-validate-all.md + - file: inbound-links-validate-link-reference.md + - file: index-command.md + - file: mv.md + - file: serve.md + - folder: migration + children: + - file: index.md + - folder: freeze + children: + - file: index.md + - file: gh-action.md + - file: syntax.md + - file: ia.md + - file: versioning.md + - file: engineering.md + - folder: guide + children: + - file: index.md + - file: working-in-docs-content.md + - file: automated.md + - file: tooling.md + - file: move-ref-docs.md + - file: mapping.md + - file: how-to-set-up-docs-previews.md # nested TOCs are only allowed from docset.yml by default # to prevent them from being nested deeply arbitrarily # use max_toc_depth to allow deeper nesting (Expert mode, consult with docs team) diff --git a/docs/cli/assemble.md b/docs/cli/assemble.md new file mode 100644 index 000000000..2123af23b --- /dev/null +++ b/docs/cli/assemble.md @@ -0,0 +1,35 @@ +# assemble + +Do a full assembler clone and assembler build in one swoop + +## Usage + +``` +assemble [options...] [-h|--help] [--version] +``` + +## Options + +`--strict` `` +: Treat warnings as errors and fail the build on warnings (Default: null) + +`--environment` `` +: The environment to build (Default: null) + +`--fetch-latest` `` +: If true, fetch the latest commit of the branch instead of the link registry entry ref (Default: null) + +`--assume-cloned` `` +: If true, assume the repository folder already exists on disk assume it's cloned already, primarily used for testing (Default: null) + +`--metadata-only` `` +: Only emit documentation metadata to output, ignored if 'exporters' is also set (Default: null) + +`--show-hints` `` +: Show hints from all documentation sets during assembler build (Default: null) + +`--exporters` `?>` +: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (Default: null) + +`--serve` +: Serve the documentation on port 4000 after successful build (Optional) \ No newline at end of file diff --git a/docs/cli/assembler-bloom-filter-create.md b/docs/cli/assembler-bloom-filter-create.md new file mode 100644 index 000000000..ff9a0e483 --- /dev/null +++ b/docs/cli/assembler-bloom-filter-create.md @@ -0,0 +1,14 @@ +# assembler bloom-filter create + +Generate the bloom filter binary file + +## Usage + +``` +assembler bloom-filter create [options...] [-h|--help] [--version] +``` + +## Options + +`--built-docs-dir` `` +: The local dir of local elastic/built-docs repository (Required) \ No newline at end of file diff --git a/docs/cli/assembler-bloom-filter-lookup.md b/docs/cli/assembler-bloom-filter-lookup.md new file mode 100644 index 000000000..efc3f76d8 --- /dev/null +++ b/docs/cli/assembler-bloom-filter-lookup.md @@ -0,0 +1,14 @@ +# assembler bloom-filter lookup + +Lookup whether a path exists in the bloomfilter + +## Usage + +``` +assembler bloom-filter lookup [options...] [-h|--help] [--version] +``` + +## Options + +`--path` `` +: The local dir of local elastic/built-docs repository (Required) \ No newline at end of file diff --git a/docs/cli/assembler-build.md b/docs/cli/assembler-build.md new file mode 100644 index 000000000..e84ad4739 --- /dev/null +++ b/docs/cli/assembler-build.md @@ -0,0 +1,26 @@ +# assembler build + +Builds all repositories + +## Usage + +``` +assembler build [options...] [-h|--help] [--version] +``` + +## Options + +`--strict` `` +: Treat warnings as errors and fail the build on warnings (Default: null) + +`--environment` `` +: The environment to build (Default: null) + +`--metadata-only` `` +: Only emit documentation metadata to output, ignored if 'exporters' is also set (Default: null) + +`--show-hints` `` +: Show hints from all documentation sets during assembler build (Default: null) + +`--exporters` `?>` +: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (Default: null) \ No newline at end of file diff --git a/docs/cli/assembler-clone.md b/docs/cli/assembler-clone.md new file mode 100644 index 000000000..9758993a1 --- /dev/null +++ b/docs/cli/assembler-clone.md @@ -0,0 +1,23 @@ +# assembler clone + +Clones all repositories + +## Usage + +``` +assembler clone [options...] [-h|--help] [--version] +``` + +## Options + +`--strict` `` +: Treat warnings as errors and fail the build on warnings (Default: null) + +`--environment` `` +: The environment to build (Default: null) + +`--fetch-latest` `` +: If true, fetch the latest commit of the branch instead of the link registry entry ref (Default: null) + +`--assume-cloned` `` +: If true, assume the repository folder already exists on disk assume it's cloned already, primarily used for testing (Default: null) \ No newline at end of file diff --git a/docs/cli/assembler-config-init.md b/docs/cli/assembler-config-init.md new file mode 100644 index 000000000..9eacb7876 --- /dev/null +++ b/docs/cli/assembler-config-init.md @@ -0,0 +1,17 @@ +# assembler config init + +Clone the configuration folder + +## Usage + +``` +assembler config init [options...] [-h|--help] [--version] +``` + +## Options + +`--git-ref` `` +: The git reference of the config, defaults to 'main' (Default: null) + +`--local` +: Save the remote configuration locally in the pwd so later commands can pick it up as local (Optional) \ No newline at end of file diff --git a/docs/cli/assembler-content-source-match.md b/docs/cli/assembler-content-source-match.md new file mode 100644 index 000000000..7927990c6 --- /dev/null +++ b/docs/cli/assembler-content-source-match.md @@ -0,0 +1,15 @@ +# assembler content-source match + +## Usage + +``` +assembler content-source match [arguments...] [-h|--help] [--version] +``` + +## Arguments + +`[0] ` +: + +`[1] ` +: \ No newline at end of file diff --git a/docs/cli/assembler-content-source-validate.md b/docs/cli/assembler-content-source-validate.md new file mode 100644 index 000000000..cf5e8261b --- /dev/null +++ b/docs/cli/assembler-content-source-validate.md @@ -0,0 +1,7 @@ +# assembler content-source validate + +## Usage + +``` +assembler content-source validate [-h|--help] [--version] +``` \ No newline at end of file diff --git a/docs/cli/assembler-deploy-apply.md b/docs/cli/assembler-deploy-apply.md new file mode 100644 index 000000000..56e97acf5 --- /dev/null +++ b/docs/cli/assembler-deploy-apply.md @@ -0,0 +1,20 @@ +# assembler deploy apply + +Applies a sync plan + +## Usage + +``` +assembler deploy apply [options...] [-h|--help] [--version] +``` + +## Options + +`--environment` `` +: The environment to build (Required) + +`--s3-bucket-name` `` +: The S3 bucket name to deploy to (Required) + +`--plan-file` `` +: The file path to the plan file to apply (Required) \ No newline at end of file diff --git a/docs/cli/assembler-deploy-plan.md b/docs/cli/assembler-deploy-plan.md new file mode 100644 index 000000000..9476c56fd --- /dev/null +++ b/docs/cli/assembler-deploy-plan.md @@ -0,0 +1,23 @@ +# assembler deploy plan + +Creates a sync plan + +## Usage + +``` +assembler deploy plan [options...] [-h|--help] [--version] +``` + +## Options + +`--environment` `` +: The environment to build (Required) + +`--s3-bucket-name` `` +: The S3 bucket name to deploy to (Required) + +`--out` `` +: The file to write the plan to (Default: "") + +`--delete-threshold` `` +: The percentage of deletions allowed in the plan as float (Default: null) \ No newline at end of file diff --git a/docs/cli/assembler-deploy-update-redirects.md b/docs/cli/assembler-deploy-update-redirects.md new file mode 100644 index 000000000..50907008b --- /dev/null +++ b/docs/cli/assembler-deploy-update-redirects.md @@ -0,0 +1,17 @@ +# assembler deploy update-redirects + +Refreshes the redirects mapping in Cloudfront's KeyValueStore + +## Usage + +``` +assembler deploy update-redirects [options...] [-h|--help] [--version] +``` + +## Options + +`--environment` `` +: The environment to build (Required) + +`--redirects-file` `` +: Path to the redirects mapping pre-generated by docs-assembler (Default: null) \ No newline at end of file diff --git a/docs/cli/assembler-index.md b/docs/cli/assembler-index.md new file mode 100644 index 000000000..8b44bff6f --- /dev/null +++ b/docs/cli/assembler-index.md @@ -0,0 +1,71 @@ +# assembler index + +Index documentation to Elasticsearch, calls `docs-builder assembler build --exporters elasticsearch`. Exposes more options + +## Usage + +``` +assembler index [options...] [-h|--help] [--version] +``` + +## Options + +`-es|--endpoint ` +: Elasticsearch endpoint, alternatively set env DOCUMENTATION_ELASTIC_URL (Default: null) + +`--environment` `` +: The --environment used to clone ends up being part of the index name (Default: null) + +`--api-key` `` +: Elasticsearch API key, alternatively set env DOCUMENTATION_ELASTIC_APIKEY (Default: null) + +`--username` `` +: Elasticsearch username (basic auth), alternatively set env DOCUMENTATION_ELASTIC_USERNAME (Default: null) + +`--password` `` +: Elasticsearch password (basic auth), alternatively set env DOCUMENTATION_ELASTIC_PASSWORD (Default: null) + +`--no-semantic` `` +: Index without semantic fields (Default: null) + +`--search-num-threads` `` +: The number of search threads the inference endpoint should use. Defaults: 8 (Default: null) + +`--index-num-threads` `` +: The number of index threads the inference endpoint should use. Defaults: 8 (Default: null) + +`--bootstrap-timeout` `` +: Timeout in minutes for the inference endpoint creation. Defaults: 4 (Default: null) + +`--index-name-prefix` `` +: The prefix for the computed index/alias names. Defaults: semantic-docs (Default: null) + +`--buffer-size` `` +: The number of documents to send to ES as part of the bulk. Defaults: 100 (Default: null) + +`--max-retries` `` +: The number of times failed bulk items should be retried. Defaults: 3 (Default: null) + +`--debug-mode` `` +: Buffer ES request/responses for better error messages and pass ?pretty to all requests (Default: null) + +`--proxy-address` `` +: Route requests through a proxy server (Default: null) + +`--proxy-password` `` +: Proxy server password (Default: null) + +`--proxy-username` `` +: Proxy server username (Default: null) + +`--disable-ssl-verification` `` +: Disable SSL certificate validation (EXPERT OPTION) (Default: null) + +`--certificate-fingerprint` `` +: Pass a self-signed certificate fingerprint to validate the SSL connection (Default: null) + +`--certificate-path` `` +: Pass a self-signed certificate to validate the SSL connection (Default: null) + +`--certificate-not-root` `` +: If the certificate is not root but only part of the validation chain pass this (Default: null) \ No newline at end of file diff --git a/docs/cli/assembler-navigation-validate-link-reference.md b/docs/cli/assembler-navigation-validate-link-reference.md new file mode 100644 index 000000000..ad69081d1 --- /dev/null +++ b/docs/cli/assembler-navigation-validate-link-reference.md @@ -0,0 +1,14 @@ +# assembler navigation validate-link-reference + +Validate all published links in links.json do not collide with navigation path_prefixes and all urls are unique. + +## Usage + +``` +assembler navigation validate-link-reference [arguments...] [-h|--help] [--version] +``` + +## Arguments + +`[0] ` +: Path to `links.json` defaults to '.artifacts/docs/html/links.json' \ No newline at end of file diff --git a/docs/cli/assembler-navigation-validate.md b/docs/cli/assembler-navigation-validate.md new file mode 100644 index 000000000..d063ab438 --- /dev/null +++ b/docs/cli/assembler-navigation-validate.md @@ -0,0 +1,9 @@ +# assembler navigation validate + +Validates navigation.yml does not contain colliding path prefixes and all urls are unique + +## Usage + +``` +assembler navigation validate [-h|--help] [--version] +``` \ No newline at end of file diff --git a/docs/cli/assembler-serve.md b/docs/cli/assembler-serve.md new file mode 100644 index 000000000..c2184b7f6 --- /dev/null +++ b/docs/cli/assembler-serve.md @@ -0,0 +1,17 @@ +# assembler serve + +Serve the output of an assembler build + +## Usage + +``` +assembler serve [options...] [-h|--help] [--version] +``` + +## Options + +`--port` `` +: Port to serve the documentation. (Default: 4000) + +`--path` `` +: (Default: null) \ No newline at end of file diff --git a/docs/cli/diff-validate.md b/docs/cli/diff-validate.md new file mode 100644 index 000000000..17c1b8a80 --- /dev/null +++ b/docs/cli/diff-validate.md @@ -0,0 +1,14 @@ +# diff validate + +Validates redirect updates in the current branch using the redirect file against changes reported by git. + +## Usage + +``` +diff validate [options...] [-h|--help] [--version] +``` + +## Options + +`-p|--path ` +: Defaults to the`{pwd}/docs` folder (Default: null) \ No newline at end of file diff --git a/docs/cli/generate.md b/docs/cli/generate.md new file mode 100644 index 000000000..ce0aba91a --- /dev/null +++ b/docs/cli/generate.md @@ -0,0 +1,110 @@ +# generate (root command) + +Converts a source Markdown folder or file to an output folder + +## Usage + +``` +[command] [options...] [-h|--help] [--version] +``` + +## Global Options + +- `--log-level` `level` + +## Options + +`-p|--path ` +: Defaults to the`{pwd}/docs` folder (Default: null) + +`-o|--output ` +: Defaults to `.artifacts/html` (Default: null) + +`--path-prefix` `` +: Specifies the path prefix for urls (Default: null) + +`--force` `` +: Force a full rebuild of the destination folder (Default: null) + +`--strict` `` +: Treat warnings as errors and fail the build on warnings (Default: null) + +`--allow-indexing` `` +: Allow indexing and following of HTML files (Default: null) + +`--metadata-only` `` +: Only emit documentation metadata to output, ignored if 'exporters' is also set (Default: null) + +`--exporters` `?>` +: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (Default: null) + +`--canonical-base-url` `` +: The base URL for the canonical url tag (Default: null) + +## Commands + +`assemble` +: Do a full assembler clone and assembler build in one swoop + +`assembler bloom-filter create` +: Generate the bloom filter binary file + +`assembler bloom-filter lookup` +: Lookup whether path exists in the bloomfilter + +`assembler build` +: Builds all repositories + +`assembler clone` +: Clones all repositories + +`assembler config init` +: Clone the configuration folder + +`assembler content-source match` +: + +`assembler content-source validate` +: + +`assembler deploy apply` +: Applies a sync plan + +`assembler deploy plan` +: Creates a sync plan + +`assembler deploy update-redirects` +: Refreshes the redirects mapping in Cloudfront's KeyValueStore + +`assembler index` +: Index documentation to Elasticsearch, calls `docs-builder assembler build --exporters elasticsearch`. Exposes more options + +`assembler navigation validate` +: Validates navigation.yml does not contain colliding path prefixes and all urls are unique + +`assembler navigation validate-link-reference` +: Validate all published links in links.json do not collide with navigation path_prefixes and all urls are unique. + +`assembler serve` +: Serve the output of an assembler build + +`diff validate` +: Validates redirect updates in the current branch using the redirect file against changes reported by git. + +`inbound-links validate` +: Validate all published cross_links in all published links.json files. + +`inbound-links validate-all` +: Validate all published cross_links in all published links.json files. + +`inbound-links validate-link-reference` +: Validate a locally published links.json file against all published links.json files in the registry + +`index` +: Index a single documentation set to Elasticsearch, calls `docs-builder --exporters elasticsearch`. Exposes more options + +`mv` +: Move a file from one location to another and update all links in the documentation + +`serve` +: Continuously serve a documentation folder at http://localhost:3000. File systems changes will be reflected without having to restart the server. \ No newline at end of file diff --git a/docs/cli/inbound-links-validate-all.md b/docs/cli/inbound-links-validate-all.md new file mode 100644 index 000000000..5f4cc0a91 --- /dev/null +++ b/docs/cli/inbound-links-validate-all.md @@ -0,0 +1,9 @@ +# inbound-links validate-all + +Validate all published cross_links in all published links.json files. + +## Usage + +``` +inbound-links validate-all [-h|--help] [--version] +``` \ No newline at end of file diff --git a/docs/cli/inbound-links-validate-link-reference.md b/docs/cli/inbound-links-validate-link-reference.md new file mode 100644 index 000000000..502f4ec0a --- /dev/null +++ b/docs/cli/inbound-links-validate-link-reference.md @@ -0,0 +1,17 @@ +# inbound-links validate-link-reference + +Validate a locally published links.json file against all published links.json files in the registry + +## Usage + +``` +inbound-links validate-link-reference [options...] [-h|--help] [--version] +``` + +## Options + +`--file` `` +: Path to `links.json` defaults to '.artifacts/docs/html/links.json' (Default: null) + +`-p|--path ` +: Defaults to the `{pwd}` folder (Default: null) \ No newline at end of file diff --git a/docs/cli/inbound-links-validate.md b/docs/cli/inbound-links-validate.md new file mode 100644 index 000000000..16e36710c --- /dev/null +++ b/docs/cli/inbound-links-validate.md @@ -0,0 +1,17 @@ +# inbound-links validate + +Validate all published cross_links in all published links.json files. + +## Usage + +``` +inbound-links validate [options...] [-h|--help] [--version] +``` + +## Options + +`--from` `` +: (Default: null) + +`--to` `` +: (Default: null) \ No newline at end of file diff --git a/docs/cli/index-command.md b/docs/cli/index-command.md new file mode 100644 index 000000000..8ebd521c8 --- /dev/null +++ b/docs/cli/index-command.md @@ -0,0 +1,71 @@ +# index + +Index a single documentation set to Elasticsearch, calls `docs-builder --exporters elasticsearch`. Exposes more options + +## Usage + +``` +index [options...] [-h|--help] [--version] +``` + +## Options + +`-es|--endpoint ` +: Elasticsearch endpoint, alternatively set env DOCUMENTATION_ELASTIC_URL (Default: null) + +`--path` `` +: path to the documentation folder, defaults to pwd. (Default: null) + +`--api-key` `` +: Elasticsearch API key, alternatively set env DOCUMENTATION_ELASTIC_APIKEY (Default: null) + +`--username` `` +: Elasticsearch username (basic auth), alternatively set env DOCUMENTATION_ELASTIC_USERNAME (Default: null) + +`--password` `` +: Elasticsearch password (basic auth), alternatively set env DOCUMENTATION_ELASTIC_PASSWORD (Default: null) + +`--no-semantic` `` +: Index without semantic fields (Default: null) + +`--search-num-threads` `` +: The number of search threads the inference endpoint should use. Defaults: 8 (Default: null) + +`--index-num-threads` `` +: The number of index threads the inference endpoint should use. Defaults: 8 (Default: null) + +`--bootstrap-timeout` `` +: Timeout in minutes for the inference endpoint creation. Defaults: 4 (Default: null) + +`--index-name-prefix` `` +: The prefix for the computed index/alias names. Defaults: semantic-docs (Default: null) + +`--buffer-size` `` +: The number of documents to send to ES as part of the bulk. Defaults: 100 (Default: null) + +`--max-retries` `` +: The number of times failed bulk items should be retried. Defaults: 3 (Default: null) + +`--debug-mode` `` +: Buffer ES request/responses for better error messages and pass ?pretty to all requests (Default: null) + +`--proxy-address` `` +: Route requests through a proxy server (Default: null) + +`--proxy-password` `` +: Proxy server password (Default: null) + +`--proxy-username` `` +: Proxy server username (Default: null) + +`--disable-ssl-verification` `` +: Disable SSL certificate validation (EXPERT OPTION) (Default: null) + +`--certificate-fingerprint` `` +: Pass a self-signed certificate fingerprint to validate the SSL connection (Default: null) + +`--certificate-path` `` +: Pass a self-signed certificate to validate the SSL connection (Default: null) + +`--certificate-not-root` `` +: If the certificate is not root but only part of the validation chain pass this (Default: null) \ No newline at end of file diff --git a/docs/cli/index.md b/docs/cli/index.md new file mode 100644 index 000000000..5a454f483 --- /dev/null +++ b/docs/cli/index.md @@ -0,0 +1,30 @@ +--- +navigation_title: docs-builder +--- + +# Command line interface + +- assemble +- assembler bloom-filter create +- assembler bloom-filter lookup +- assembler build +- assembler clone +- assembler config init +- assembler content-source match +- assembler content-source validate +- assembler deploy apply +- assembler deploy plan +- assembler deploy update-redirects +- assembler index +- assembler navigation validate +- assembler navigation validate-link-reference +- assembler serve +- diff validate +- inbound-links validate +- inbound-links validate-all +- inbound-links validate-link-reference +- index +- mv +- serve + + diff --git a/docs/cli/mv.md b/docs/cli/mv.md new file mode 100644 index 000000000..4afc570ef --- /dev/null +++ b/docs/cli/mv.md @@ -0,0 +1,25 @@ +# mv + +Move a file from one location to another and update all links in the documentation + +## Usage + +``` +mv [arguments...] [options...] [-h|--help] [--version] +``` + +## Arguments + +`[0] ` +: The source file or folder path to move from + +`[1] ` +: The target file or folder path to move to + +## Options + +`--dry-run` `` +: Dry run the move operation (Default: null) + +`-p|--path ` +: Defaults to the`{pwd}` folder (Default: null) \ No newline at end of file diff --git a/docs/cli/serve.md b/docs/cli/serve.md new file mode 100644 index 000000000..a77cb4c72 --- /dev/null +++ b/docs/cli/serve.md @@ -0,0 +1,18 @@ +# serve + +Continuously serve a documentation folder at http://localhost:3000. +File systems changes will be reflected without having to restart the server. + +## Usage + +``` +serve [options...] [-h|--help] [--version] +``` + +## Options + +`-p|--path ` +: Path to serve the documentation. Defaults to the`{pwd}/docs` folder (Default: null) + +`--port` `` +: Port to serve the documentation. (Default: 3000) \ No newline at end of file diff --git a/docs/configure/site/legacy-url-mappings.md b/docs/configure/site/legacy-url-mappings.md index 0d72bb433..294e2cc81 100644 --- a/docs/configure/site/legacy-url-mappings.md +++ b/docs/configure/site/legacy-url-mappings.md @@ -1,3 +1,6 @@ +--- +navigation_title: 'legacy-url-mappings.yml' +--- # Legacy URL mappings This [`legacy-url-mappings.yml`](https://github.com/elastic/docs-builder/blob/main/config/legacy-url-mappings.yml) file manages legacy URL patterns for Elastic documentation, mapping the path of each legacy build URL to a list of documentation versions. It ensures that users can easily find previous versions of our documentation. From 771b84b38ff26105291c291aed5bb0215948ab05 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 08:20:11 +0200 Subject: [PATCH 02/86] organize cli command documentation --- docs/_docset.yml | 55 ++++++++------- docs/cli/assemble.md | 35 ---------- docs/cli/assembler-clone.md | 23 ------- docs/cli/assembler-content-source-match.md | 15 ---- docs/cli/assembler-content-source-validate.md | 7 -- docs/cli/assembler/assemble.md | 48 +++++++++++++ .../assembler-bloom-filter-create.md | 6 +- .../assembler-bloom-filter-lookup.md | 5 +- docs/cli/{ => assembler}/assembler-build.md | 18 +++-- docs/cli/assembler/assembler-clone.md | 27 ++++++++ .../{ => assembler}/assembler-config-init.md | 10 ++- .../assembler-content-source-match.md | 19 ++++++ .../assembler-content-source-validate.md | 11 +++ .../{ => assembler}/assembler-deploy-apply.md | 6 +- .../{ => assembler}/assembler-deploy-plan.md | 8 ++- .../assembler-deploy-update-redirects.md | 10 ++- docs/cli/{ => assembler}/assembler-index.md | 68 ++++++++++--------- ...bler-navigation-validate-link-reference.md | 8 ++- .../assembler-navigation-validate.md | 6 +- docs/cli/{ => assembler}/assembler-serve.md | 10 ++- docs/cli/assembler/index.md | 5 ++ docs/cli/{generate.md => docset/build.md} | 28 ++++---- docs/cli/{ => docset}/diff-validate.md | 6 +- docs/cli/{ => docset}/index-command.md | 64 ++++++++--------- docs/cli/docset/index.md | 5 ++ docs/cli/{ => docset}/mv.md | 8 +-- docs/cli/{ => docset}/serve.md | 6 +- docs/cli/inbound-links-validate.md | 17 ----- docs/cli/index.md | 2 +- .../{ => links}/inbound-links-validate-all.md | 2 +- .../inbound-links-validate-link-reference.md | 10 +-- docs/cli/links/inbound-links-validate.md | 17 +++++ 32 files changed, 326 insertions(+), 239 deletions(-) delete mode 100644 docs/cli/assemble.md delete mode 100644 docs/cli/assembler-clone.md delete mode 100644 docs/cli/assembler-content-source-match.md delete mode 100644 docs/cli/assembler-content-source-validate.md create mode 100644 docs/cli/assembler/assemble.md rename docs/cli/{ => assembler}/assembler-bloom-filter-create.md (60%) rename docs/cli/{ => assembler}/assembler-bloom-filter-lookup.md (60%) rename docs/cli/{ => assembler}/assembler-build.md (58%) create mode 100644 docs/cli/assembler/assembler-clone.md rename docs/cli/{ => assembler}/assembler-config-init.md (50%) create mode 100644 docs/cli/assembler/assembler-content-source-match.md create mode 100644 docs/cli/assembler/assembler-content-source-validate.md rename docs/cli/{ => assembler}/assembler-deploy-apply.md (72%) rename docs/cli/{ => assembler}/assembler-deploy-plan.md (63%) rename docs/cli/{ => assembler}/assembler-deploy-update-redirects.md (59%) rename docs/cli/{ => assembler}/assembler-index.md (54%) rename docs/cli/{ => assembler}/assembler-navigation-validate-link-reference.md (60%) rename docs/cli/{ => assembler}/assembler-navigation-validate.md (54%) rename docs/cli/{ => assembler}/assembler-serve.md (55%) create mode 100644 docs/cli/assembler/index.md rename docs/cli/{generate.md => docset/build.md} (78%) rename docs/cli/{ => docset}/diff-validate.md (53%) rename docs/cli/{ => docset}/index-command.md (52%) create mode 100644 docs/cli/docset/index.md rename docs/cli/{ => docset}/mv.md (61%) rename docs/cli/{ => docset}/serve.md (77%) delete mode 100644 docs/cli/inbound-links-validate.md rename docs/cli/{ => links}/inbound-links-validate-all.md (64%) rename docs/cli/{ => links}/inbound-links-validate-link-reference.md (54%) create mode 100644 docs/cli/links/inbound-links-validate.md diff --git a/docs/_docset.yml b/docs/_docset.yml index dbbab6312..5833e223a 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -104,29 +104,38 @@ toc: - folder: cli children: - file: index.md - - file: assemble.md - - file: assembler-bloom-filter-create.md - - file: assembler-bloom-filter-lookup.md - - file: assembler-build.md - - file: assembler-clone.md - - file: assembler-config-init.md - - file: assembler-content-source-match.md - - file: assembler-content-source-validate.md - - file: assembler-deploy-apply.md - - file: assembler-deploy-plan.md - - file: assembler-deploy-update-redirects.md - - file: assembler-index.md - - file: assembler-navigation-validate.md - - file: assembler-navigation-validate-link-reference.md - - file: assembler-serve.md - - file: diff-validate.md - - file: generate.md - - file: inbound-links-validate.md - - file: inbound-links-validate-all.md - - file: inbound-links-validate-link-reference.md - - file: index-command.md - - file: mv.md - - file: serve.md + - folder: docset + children: + - file: index.md + - file: build.md + - file: diff-validate.md + - file: index-command.md + - file: mv.md + - file: serve.md + - folder: assembler + children: + - file: index.md + - file: assemble.md + - file: assembler-bloom-filter-create.md + - file: assembler-bloom-filter-lookup.md + - file: assembler-build.md + - file: assembler-clone.md + - file: assembler-config-init.md + - file: assembler-content-source-match.md + - file: assembler-content-source-validate.md + - file: assembler-deploy-apply.md + - file: assembler-deploy-plan.md + - file: assembler-deploy-update-redirects.md + - file: assembler-index.md + - file: assembler-navigation-validate.md + - file: assembler-navigation-validate-link-reference.md + - file: assembler-serve.md + - folder: links + children: + - file: index.md + - file: inbound-links-validate.md + - file: inbound-links-validate-all.md + - file: inbound-links-validate-link-reference.md - folder: migration children: - file: index.md diff --git a/docs/cli/assemble.md b/docs/cli/assemble.md deleted file mode 100644 index 2123af23b..000000000 --- a/docs/cli/assemble.md +++ /dev/null @@ -1,35 +0,0 @@ -# assemble - -Do a full assembler clone and assembler build in one swoop - -## Usage - -``` -assemble [options...] [-h|--help] [--version] -``` - -## Options - -`--strict` `` -: Treat warnings as errors and fail the build on warnings (Default: null) - -`--environment` `` -: The environment to build (Default: null) - -`--fetch-latest` `` -: If true, fetch the latest commit of the branch instead of the link registry entry ref (Default: null) - -`--assume-cloned` `` -: If true, assume the repository folder already exists on disk assume it's cloned already, primarily used for testing (Default: null) - -`--metadata-only` `` -: Only emit documentation metadata to output, ignored if 'exporters' is also set (Default: null) - -`--show-hints` `` -: Show hints from all documentation sets during assembler build (Default: null) - -`--exporters` `?>` -: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (Default: null) - -`--serve` -: Serve the documentation on port 4000 after successful build (Optional) \ No newline at end of file diff --git a/docs/cli/assembler-clone.md b/docs/cli/assembler-clone.md deleted file mode 100644 index 9758993a1..000000000 --- a/docs/cli/assembler-clone.md +++ /dev/null @@ -1,23 +0,0 @@ -# assembler clone - -Clones all repositories - -## Usage - -``` -assembler clone [options...] [-h|--help] [--version] -``` - -## Options - -`--strict` `` -: Treat warnings as errors and fail the build on warnings (Default: null) - -`--environment` `` -: The environment to build (Default: null) - -`--fetch-latest` `` -: If true, fetch the latest commit of the branch instead of the link registry entry ref (Default: null) - -`--assume-cloned` `` -: If true, assume the repository folder already exists on disk assume it's cloned already, primarily used for testing (Default: null) \ No newline at end of file diff --git a/docs/cli/assembler-content-source-match.md b/docs/cli/assembler-content-source-match.md deleted file mode 100644 index 7927990c6..000000000 --- a/docs/cli/assembler-content-source-match.md +++ /dev/null @@ -1,15 +0,0 @@ -# assembler content-source match - -## Usage - -``` -assembler content-source match [arguments...] [-h|--help] [--version] -``` - -## Arguments - -`[0] ` -: - -`[1] ` -: \ No newline at end of file diff --git a/docs/cli/assembler-content-source-validate.md b/docs/cli/assembler-content-source-validate.md deleted file mode 100644 index cf5e8261b..000000000 --- a/docs/cli/assembler-content-source-validate.md +++ /dev/null @@ -1,7 +0,0 @@ -# assembler content-source validate - -## Usage - -``` -assembler content-source validate [-h|--help] [--version] -``` \ No newline at end of file diff --git a/docs/cli/assembler/assemble.md b/docs/cli/assembler/assemble.md new file mode 100644 index 000000000..135cc499d --- /dev/null +++ b/docs/cli/assembler/assemble.md @@ -0,0 +1,48 @@ +# assemble + +Do a full assembler clone and assembler build in one swoop + +## Usage + +``` +docs-builder assemble [options...] [-h|--help] [--version] +``` + +## Options + +`--strict` `` +: Treat warnings as errors and fail the build on warnings (optional) + +`--environment` `` +: The environment to build (optional) defaults to 'dev' + +`--fetch-latest` `` +: If true, fetch the latest commit of the branch instead of the link registry entry ref (optional) + +`--assume-cloned` `` +: If true, assume the repository folder already exists on disk assume it's cloned already, primarily used for testing (optional) + +`--metadata-only` `` +: Only emit documentation metadata to output, ignored if 'exporters' is also set (optional) + +`--show-hints` `` +: Show hints from all documentation sets during assembler build (optional) + +`--exporters` `` +: Set available exporters: + + * html + * es, + * config, + * links, + * state, + * llm, + * redirect, + * metadata, + * default + * none. + + Defaults to (html, llm, config, links, state, redirect) or 'default'. (optional) + +`--serve` +: Serve the documentation on port 4000 after successful build (Optional) \ No newline at end of file diff --git a/docs/cli/assembler-bloom-filter-create.md b/docs/cli/assembler/assembler-bloom-filter-create.md similarity index 60% rename from docs/cli/assembler-bloom-filter-create.md rename to docs/cli/assembler/assembler-bloom-filter-create.md index ff9a0e483..968a2536b 100644 --- a/docs/cli/assembler-bloom-filter-create.md +++ b/docs/cli/assembler/assembler-bloom-filter-create.md @@ -1,3 +1,7 @@ +--- +navigation_title: "bloom-filter create" +--- + # assembler bloom-filter create Generate the bloom filter binary file @@ -5,7 +9,7 @@ Generate the bloom filter binary file ## Usage ``` -assembler bloom-filter create [options...] [-h|--help] [--version] +docs-builder assembler bloom-filter create [options...] [-h|--help] [--version] ``` ## Options diff --git a/docs/cli/assembler-bloom-filter-lookup.md b/docs/cli/assembler/assembler-bloom-filter-lookup.md similarity index 60% rename from docs/cli/assembler-bloom-filter-lookup.md rename to docs/cli/assembler/assembler-bloom-filter-lookup.md index efc3f76d8..3164f5a9c 100644 --- a/docs/cli/assembler-bloom-filter-lookup.md +++ b/docs/cli/assembler/assembler-bloom-filter-lookup.md @@ -1,3 +1,6 @@ +--- +navigation_title: "bloom-filter lookup" +--- # assembler bloom-filter lookup Lookup whether a path exists in the bloomfilter @@ -5,7 +8,7 @@ Lookup whether a path exists in the bloomfilter ## Usage ``` -assembler bloom-filter lookup [options...] [-h|--help] [--version] +docs-builder assembler bloom-filter lookup [options...] [-h|--help] [--version] ``` ## Options diff --git a/docs/cli/assembler-build.md b/docs/cli/assembler/assembler-build.md similarity index 58% rename from docs/cli/assembler-build.md rename to docs/cli/assembler/assembler-build.md index e84ad4739..bceaa633b 100644 --- a/docs/cli/assembler-build.md +++ b/docs/cli/assembler/assembler-build.md @@ -1,3 +1,7 @@ +--- +navigation_title: "build" +--- + # assembler build Builds all repositories @@ -5,22 +9,22 @@ Builds all repositories ## Usage ``` -assembler build [options...] [-h|--help] [--version] +docs-builder assembler build [options...] [-h|--help] [--version] ``` ## Options `--strict` `` -: Treat warnings as errors and fail the build on warnings (Default: null) +: Treat warnings as errors and fail the build on warnings (optional) -`--environment` `` -: The environment to build (Default: null) +`--environment` `` +: The environment to build (optional) `--metadata-only` `` -: Only emit documentation metadata to output, ignored if 'exporters' is also set (Default: null) +: Only emit documentation metadata to output, ignored if 'exporters' is also set (optional) `--show-hints` `` -: Show hints from all documentation sets during assembler build (Default: null) +: Show hints from all documentation sets during assembler build (optional) `--exporters` `?>` -: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (Default: null) \ No newline at end of file +: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (optional) \ No newline at end of file diff --git a/docs/cli/assembler/assembler-clone.md b/docs/cli/assembler/assembler-clone.md new file mode 100644 index 000000000..3469bc13d --- /dev/null +++ b/docs/cli/assembler/assembler-clone.md @@ -0,0 +1,27 @@ +--- +navigation_title: "clone" +--- + +# assembler clone + +Clones all repositories + +## Usage + +``` +docs-builder assembler clone [options...] [-h|--help] [--version] +``` + +## Options + +`--strict` `` +: Treat warnings as errors and fail the build on warnings (optional) + +`--environment` `` +: The environment to build (optional) + +`--fetch-latest` `` +: If true, fetch the latest commit of the branch instead of the link registry entry ref (optional) + +`--assume-cloned` `` +: If true, assume the repository folder already exists on disk assume it's cloned already, primarily used for testing (optional) \ No newline at end of file diff --git a/docs/cli/assembler-config-init.md b/docs/cli/assembler/assembler-config-init.md similarity index 50% rename from docs/cli/assembler-config-init.md rename to docs/cli/assembler/assembler-config-init.md index 9eacb7876..ea40dc237 100644 --- a/docs/cli/assembler-config-init.md +++ b/docs/cli/assembler/assembler-config-init.md @@ -1,3 +1,7 @@ +--- +navigation_title: "config init" +--- + # assembler config init Clone the configuration folder @@ -5,13 +9,13 @@ Clone the configuration folder ## Usage ``` -assembler config init [options...] [-h|--help] [--version] +docs-builder assembler config init [options...] [-h|--help] [--version] ``` ## Options -`--git-ref` `` -: The git reference of the config, defaults to 'main' (Default: null) +`--git-ref` `` +: The git reference of the config, defaults to 'main' (optional) `--local` : Save the remote configuration locally in the pwd so later commands can pick it up as local (Optional) \ No newline at end of file diff --git a/docs/cli/assembler/assembler-content-source-match.md b/docs/cli/assembler/assembler-content-source-match.md new file mode 100644 index 000000000..79f2bb890 --- /dev/null +++ b/docs/cli/assembler/assembler-content-source-match.md @@ -0,0 +1,19 @@ +--- +navigation_title: "content-source match" +--- + +# assembler content-source match + +## Usage + +``` +docs-builder assembler content-source match [arguments...] [-h|--help] [--version] +``` + +## Arguments + +`[0] ` +: + +`[1] ` +: \ No newline at end of file diff --git a/docs/cli/assembler/assembler-content-source-validate.md b/docs/cli/assembler/assembler-content-source-validate.md new file mode 100644 index 000000000..e1742c7bf --- /dev/null +++ b/docs/cli/assembler/assembler-content-source-validate.md @@ -0,0 +1,11 @@ +--- +navigation_title: "content-source validate" +--- + +# assembler content-source validate + +## Usage + +``` +docs-builder assembler content-source validate [-h|--help] [--version] +``` \ No newline at end of file diff --git a/docs/cli/assembler-deploy-apply.md b/docs/cli/assembler/assembler-deploy-apply.md similarity index 72% rename from docs/cli/assembler-deploy-apply.md rename to docs/cli/assembler/assembler-deploy-apply.md index 56e97acf5..4e2af8a50 100644 --- a/docs/cli/assembler-deploy-apply.md +++ b/docs/cli/assembler/assembler-deploy-apply.md @@ -1,3 +1,7 @@ +--- +navigation_title: "deploy apply" +--- + # assembler deploy apply Applies a sync plan @@ -5,7 +9,7 @@ Applies a sync plan ## Usage ``` -assembler deploy apply [options...] [-h|--help] [--version] +docs-builder assembler deploy apply [options...] [-h|--help] [--version] ``` ## Options diff --git a/docs/cli/assembler-deploy-plan.md b/docs/cli/assembler/assembler-deploy-plan.md similarity index 63% rename from docs/cli/assembler-deploy-plan.md rename to docs/cli/assembler/assembler-deploy-plan.md index 9476c56fd..83a86d4e6 100644 --- a/docs/cli/assembler-deploy-plan.md +++ b/docs/cli/assembler/assembler-deploy-plan.md @@ -1,3 +1,7 @@ +--- +navigation_title: "deploy plan" +--- + # assembler deploy plan Creates a sync plan @@ -5,7 +9,7 @@ Creates a sync plan ## Usage ``` -assembler deploy plan [options...] [-h|--help] [--version] +docs-builder assembler deploy plan [options...] [-h|--help] [--version] ``` ## Options @@ -20,4 +24,4 @@ assembler deploy plan [options...] [-h|--help] [--version] : The file to write the plan to (Default: "") `--delete-threshold` `` -: The percentage of deletions allowed in the plan as float (Default: null) \ No newline at end of file +: The percentage of deletions allowed in the plan as float (optional) \ No newline at end of file diff --git a/docs/cli/assembler-deploy-update-redirects.md b/docs/cli/assembler/assembler-deploy-update-redirects.md similarity index 59% rename from docs/cli/assembler-deploy-update-redirects.md rename to docs/cli/assembler/assembler-deploy-update-redirects.md index 50907008b..ec0255d5d 100644 --- a/docs/cli/assembler-deploy-update-redirects.md +++ b/docs/cli/assembler/assembler-deploy-update-redirects.md @@ -1,3 +1,7 @@ +--- +navigation_title: "deploy update-redirects" +--- + # assembler deploy update-redirects Refreshes the redirects mapping in Cloudfront's KeyValueStore @@ -5,7 +9,7 @@ Refreshes the redirects mapping in Cloudfront's KeyValueStore ## Usage ``` -assembler deploy update-redirects [options...] [-h|--help] [--version] +docs-builder assembler deploy update-redirects [options...] [-h|--help] [--version] ``` ## Options @@ -13,5 +17,5 @@ assembler deploy update-redirects [options...] [-h|--help] [--version] `--environment` `` : The environment to build (Required) -`--redirects-file` `` -: Path to the redirects mapping pre-generated by docs-assembler (Default: null) \ No newline at end of file +`--redirects-file` `` +: Path to the redirects mapping pre-generated by docs-assembler (optional) \ No newline at end of file diff --git a/docs/cli/assembler-index.md b/docs/cli/assembler/assembler-index.md similarity index 54% rename from docs/cli/assembler-index.md rename to docs/cli/assembler/assembler-index.md index 8b44bff6f..ea8d6947c 100644 --- a/docs/cli/assembler-index.md +++ b/docs/cli/assembler/assembler-index.md @@ -1,3 +1,7 @@ +--- +navigation_title: "index" +--- + # assembler index Index documentation to Elasticsearch, calls `docs-builder assembler build --exporters elasticsearch`. Exposes more options @@ -5,67 +9,67 @@ Index documentation to Elasticsearch, calls `docs-builder assembler build --expo ## Usage ``` -assembler index [options...] [-h|--help] [--version] +docs-builder assembler index [options...] [-h|--help] [--version] ``` ## Options -`-es|--endpoint ` -: Elasticsearch endpoint, alternatively set env DOCUMENTATION_ELASTIC_URL (Default: null) +`-es|--endpoint ` +: Elasticsearch endpoint, alternatively set env DOCUMENTATION_ELASTIC_URL (optional) -`--environment` `` -: The --environment used to clone ends up being part of the index name (Default: null) +`--environment` `` +: The --environment used to clone ends up being part of the index name (optional) -`--api-key` `` -: Elasticsearch API key, alternatively set env DOCUMENTATION_ELASTIC_APIKEY (Default: null) +`--api-key` `` +: Elasticsearch API key, alternatively set env DOCUMENTATION_ELASTIC_APIKEY (optional) -`--username` `` -: Elasticsearch username (basic auth), alternatively set env DOCUMENTATION_ELASTIC_USERNAME (Default: null) +`--username` `` +: Elasticsearch username (basic auth), alternatively set env DOCUMENTATION_ELASTIC_USERNAME (optional) -`--password` `` -: Elasticsearch password (basic auth), alternatively set env DOCUMENTATION_ELASTIC_PASSWORD (Default: null) +`--password` `` +: Elasticsearch password (basic auth), alternatively set env DOCUMENTATION_ELASTIC_PASSWORD (optional) `--no-semantic` `` -: Index without semantic fields (Default: null) +: Index without semantic fields (optional) `--search-num-threads` `` -: The number of search threads the inference endpoint should use. Defaults: 8 (Default: null) +: The number of search threads the inference endpoint should use. Defaults: 8 (optional) `--index-num-threads` `` -: The number of index threads the inference endpoint should use. Defaults: 8 (Default: null) +: The number of index threads the inference endpoint should use. Defaults: 8 (optional) `--bootstrap-timeout` `` -: Timeout in minutes for the inference endpoint creation. Defaults: 4 (Default: null) +: Timeout in minutes for the inference endpoint creation. Defaults: 4 (optional) -`--index-name-prefix` `` -: The prefix for the computed index/alias names. Defaults: semantic-docs (Default: null) +`--index-name-prefix` `` +: The prefix for the computed index/alias names. Defaults: semantic-docs (optional) `--buffer-size` `` -: The number of documents to send to ES as part of the bulk. Defaults: 100 (Default: null) +: The number of documents to send to ES as part of the bulk. Defaults: 100 (optional) `--max-retries` `` -: The number of times failed bulk items should be retried. Defaults: 3 (Default: null) +: The number of times failed bulk items should be retried. Defaults: 3 (optional) `--debug-mode` `` -: Buffer ES request/responses for better error messages and pass ?pretty to all requests (Default: null) +: Buffer ES request/responses for better error messages and pass ?pretty to all requests (optional) -`--proxy-address` `` -: Route requests through a proxy server (Default: null) +`--proxy-address` `` +: Route requests through a proxy server (optional) -`--proxy-password` `` -: Proxy server password (Default: null) +`--proxy-password` `` +: Proxy server password (optional) -`--proxy-username` `` -: Proxy server username (Default: null) +`--proxy-username` `` +: Proxy server username (optional) `--disable-ssl-verification` `` -: Disable SSL certificate validation (EXPERT OPTION) (Default: null) +: Disable SSL certificate validation (EXPERT OPTION) (optional) -`--certificate-fingerprint` `` -: Pass a self-signed certificate fingerprint to validate the SSL connection (Default: null) +`--certificate-fingerprint` `` +: Pass a self-signed certificate fingerprint to validate the SSL connection (optional) -`--certificate-path` `` -: Pass a self-signed certificate to validate the SSL connection (Default: null) +`--certificate-path` `` +: Pass a self-signed certificate to validate the SSL connection (optional) `--certificate-not-root` `` -: If the certificate is not root but only part of the validation chain pass this (Default: null) \ No newline at end of file +: If the certificate is not root but only part of the validation chain pass this (optional) \ No newline at end of file diff --git a/docs/cli/assembler-navigation-validate-link-reference.md b/docs/cli/assembler/assembler-navigation-validate-link-reference.md similarity index 60% rename from docs/cli/assembler-navigation-validate-link-reference.md rename to docs/cli/assembler/assembler-navigation-validate-link-reference.md index ad69081d1..c06ca4dc6 100644 --- a/docs/cli/assembler-navigation-validate-link-reference.md +++ b/docs/cli/assembler/assembler-navigation-validate-link-reference.md @@ -1,3 +1,7 @@ +--- +navigation_title: "navigation validate-link-reference" +--- + # assembler navigation validate-link-reference Validate all published links in links.json do not collide with navigation path_prefixes and all urls are unique. @@ -5,10 +9,10 @@ Validate all published links in links.json do not collide with navigation path_p ## Usage ``` -assembler navigation validate-link-reference [arguments...] [-h|--help] [--version] +docs-builder assembler navigation validate-link-reference [arguments...] [-h|--help] [--version] ``` ## Arguments -`[0] ` +`[0] ` : Path to `links.json` defaults to '.artifacts/docs/html/links.json' \ No newline at end of file diff --git a/docs/cli/assembler-navigation-validate.md b/docs/cli/assembler/assembler-navigation-validate.md similarity index 54% rename from docs/cli/assembler-navigation-validate.md rename to docs/cli/assembler/assembler-navigation-validate.md index d063ab438..d438f9b3c 100644 --- a/docs/cli/assembler-navigation-validate.md +++ b/docs/cli/assembler/assembler-navigation-validate.md @@ -1,3 +1,7 @@ +--- +navigation_title: "navigation validate" +--- + # assembler navigation validate Validates navigation.yml does not contain colliding path prefixes and all urls are unique @@ -5,5 +9,5 @@ Validates navigation.yml does not contain colliding path prefixes and all urls a ## Usage ``` -assembler navigation validate [-h|--help] [--version] +docs-builder assembler navigation validate [-h|--help] [--version] ``` \ No newline at end of file diff --git a/docs/cli/assembler-serve.md b/docs/cli/assembler/assembler-serve.md similarity index 55% rename from docs/cli/assembler-serve.md rename to docs/cli/assembler/assembler-serve.md index c2184b7f6..e96797cca 100644 --- a/docs/cli/assembler-serve.md +++ b/docs/cli/assembler/assembler-serve.md @@ -1,3 +1,7 @@ +--- +navigation_title: "serve" +--- + # assembler serve Serve the output of an assembler build @@ -5,7 +9,7 @@ Serve the output of an assembler build ## Usage ``` -assembler serve [options...] [-h|--help] [--version] +docs-builder assembler serve [options...] [-h|--help] [--version] ``` ## Options @@ -13,5 +17,5 @@ assembler serve [options...] [-h|--help] [--version] `--port` `` : Port to serve the documentation. (Default: 4000) -`--path` `` -: (Default: null) \ No newline at end of file +`--path` `` +: (optional) \ No newline at end of file diff --git a/docs/cli/assembler/index.md b/docs/cli/assembler/index.md new file mode 100644 index 000000000..e43e896a9 --- /dev/null +++ b/docs/cli/assembler/index.md @@ -0,0 +1,5 @@ +--- +navigation_title: "assembler" +--- + +# The assembler namespace \ No newline at end of file diff --git a/docs/cli/generate.md b/docs/cli/docset/build.md similarity index 78% rename from docs/cli/generate.md rename to docs/cli/docset/build.md index ce0aba91a..c071f51c7 100644 --- a/docs/cli/generate.md +++ b/docs/cli/docset/build.md @@ -5,7 +5,7 @@ Converts a source Markdown folder or file to an output folder ## Usage ``` -[command] [options...] [-h|--help] [--version] +docs-builder [command] [options...] [-h|--help] [--version] ``` ## Global Options @@ -14,32 +14,32 @@ Converts a source Markdown folder or file to an output folder ## Options -`-p|--path ` -: Defaults to the`{pwd}/docs` folder (Default: null) +`-p|--path ` +: Defaults to the`{pwd}/docs` folder (optional) -`-o|--output ` -: Defaults to `.artifacts/html` (Default: null) +`-o|--output ` +: Defaults to `.artifacts/html` (optional) -`--path-prefix` `` -: Specifies the path prefix for urls (Default: null) +`--path-prefix` `` +: Specifies the path prefix for urls (optional) `--force` `` -: Force a full rebuild of the destination folder (Default: null) +: Force a full rebuild of the destination folder (optional) `--strict` `` -: Treat warnings as errors and fail the build on warnings (Default: null) +: Treat warnings as errors and fail the build on warnings (optional) `--allow-indexing` `` -: Allow indexing and following of HTML files (Default: null) +: Allow indexing and following of HTML files (optional) `--metadata-only` `` -: Only emit documentation metadata to output, ignored if 'exporters' is also set (Default: null) +: Only emit documentation metadata to output, ignored if 'exporters' is also set (optional) `--exporters` `?>` -: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (Default: null) +: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (optional) -`--canonical-base-url` `` -: The base URL for the canonical url tag (Default: null) +`--canonical-base-url` `` +: The base URL for the canonical url tag (optional) ## Commands diff --git a/docs/cli/diff-validate.md b/docs/cli/docset/diff-validate.md similarity index 53% rename from docs/cli/diff-validate.md rename to docs/cli/docset/diff-validate.md index 17c1b8a80..e29f5a06a 100644 --- a/docs/cli/diff-validate.md +++ b/docs/cli/docset/diff-validate.md @@ -5,10 +5,10 @@ Validates redirect updates in the current branch using the redirect file against ## Usage ``` -diff validate [options...] [-h|--help] [--version] +docs-builder diff validate [options...] [-h|--help] [--version] ``` ## Options -`-p|--path ` -: Defaults to the`{pwd}/docs` folder (Default: null) \ No newline at end of file +`-p|--path ` +: Defaults to the`{pwd}/docs` folder (optional) \ No newline at end of file diff --git a/docs/cli/index-command.md b/docs/cli/docset/index-command.md similarity index 52% rename from docs/cli/index-command.md rename to docs/cli/docset/index-command.md index 8ebd521c8..833e6a8a6 100644 --- a/docs/cli/index-command.md +++ b/docs/cli/docset/index-command.md @@ -5,67 +5,67 @@ Index a single documentation set to Elasticsearch, calls `docs-builder --exporte ## Usage ``` -index [options...] [-h|--help] [--version] +docs-builder index [options...] [-h|--help] [--version] ``` ## Options -`-es|--endpoint ` -: Elasticsearch endpoint, alternatively set env DOCUMENTATION_ELASTIC_URL (Default: null) +`-es|--endpoint ` +: Elasticsearch endpoint, alternatively set env DOCUMENTATION_ELASTIC_URL (optional) -`--path` `` -: path to the documentation folder, defaults to pwd. (Default: null) +`--path` `` +: path to the documentation folder, defaults to pwd. (optional) -`--api-key` `` -: Elasticsearch API key, alternatively set env DOCUMENTATION_ELASTIC_APIKEY (Default: null) +`--api-key` `` +: Elasticsearch API key, alternatively set env DOCUMENTATION_ELASTIC_APIKEY (optional) -`--username` `` -: Elasticsearch username (basic auth), alternatively set env DOCUMENTATION_ELASTIC_USERNAME (Default: null) +`--username` `` +: Elasticsearch username (basic auth), alternatively set env DOCUMENTATION_ELASTIC_USERNAME (optional) -`--password` `` -: Elasticsearch password (basic auth), alternatively set env DOCUMENTATION_ELASTIC_PASSWORD (Default: null) +`--password` `` +: Elasticsearch password (basic auth), alternatively set env DOCUMENTATION_ELASTIC_PASSWORD (optional) `--no-semantic` `` -: Index without semantic fields (Default: null) +: Index without semantic fields (optional) `--search-num-threads` `` -: The number of search threads the inference endpoint should use. Defaults: 8 (Default: null) +: The number of search threads the inference endpoint should use. Defaults: 8 (optional) `--index-num-threads` `` -: The number of index threads the inference endpoint should use. Defaults: 8 (Default: null) +: The number of index threads the inference endpoint should use. Defaults: 8 (optional) `--bootstrap-timeout` `` -: Timeout in minutes for the inference endpoint creation. Defaults: 4 (Default: null) +: Timeout in minutes for the inference endpoint creation. Defaults: 4 (optional) -`--index-name-prefix` `` -: The prefix for the computed index/alias names. Defaults: semantic-docs (Default: null) +`--index-name-prefix` `` +: The prefix for the computed index/alias names. Defaults: semantic-docs (optional) `--buffer-size` `` -: The number of documents to send to ES as part of the bulk. Defaults: 100 (Default: null) +: The number of documents to send to ES as part of the bulk. Defaults: 100 (optional) `--max-retries` `` -: The number of times failed bulk items should be retried. Defaults: 3 (Default: null) +: The number of times failed bulk items should be retried. Defaults: 3 (optional) `--debug-mode` `` -: Buffer ES request/responses for better error messages and pass ?pretty to all requests (Default: null) +: Buffer ES request/responses for better error messages and pass ?pretty to all requests (optional) -`--proxy-address` `` -: Route requests through a proxy server (Default: null) +`--proxy-address` `` +: Route requests through a proxy server (optional) -`--proxy-password` `` -: Proxy server password (Default: null) +`--proxy-password` `` +: Proxy server password (optional) -`--proxy-username` `` -: Proxy server username (Default: null) +`--proxy-username` `` +: Proxy server username (optional) `--disable-ssl-verification` `` -: Disable SSL certificate validation (EXPERT OPTION) (Default: null) +: Disable SSL certificate validation (EXPERT OPTION) (optional) -`--certificate-fingerprint` `` -: Pass a self-signed certificate fingerprint to validate the SSL connection (Default: null) +`--certificate-fingerprint` `` +: Pass a self-signed certificate fingerprint to validate the SSL connection (optional) -`--certificate-path` `` -: Pass a self-signed certificate to validate the SSL connection (Default: null) +`--certificate-path` `` +: Pass a self-signed certificate to validate the SSL connection (optional) `--certificate-not-root` `` -: If the certificate is not root but only part of the validation chain pass this (Default: null) \ No newline at end of file +: If the certificate is not root but only part of the validation chain pass this (optional) \ No newline at end of file diff --git a/docs/cli/docset/index.md b/docs/cli/docset/index.md new file mode 100644 index 000000000..c456dee22 --- /dev/null +++ b/docs/cli/docset/index.md @@ -0,0 +1,5 @@ +--- +navigation_title: "documentation set" +--- + +# Documentation set commands \ No newline at end of file diff --git a/docs/cli/mv.md b/docs/cli/docset/mv.md similarity index 61% rename from docs/cli/mv.md rename to docs/cli/docset/mv.md index 4afc570ef..ec803baf9 100644 --- a/docs/cli/mv.md +++ b/docs/cli/docset/mv.md @@ -5,7 +5,7 @@ Move a file from one location to another and update all links in the documentati ## Usage ``` -mv [arguments...] [options...] [-h|--help] [--version] +docs-builder mv [arguments...] [options...] [-h|--help] [--version] ``` ## Arguments @@ -19,7 +19,7 @@ mv [arguments...] [options...] [-h|--help] [--version] ## Options `--dry-run` `` -: Dry run the move operation (Default: null) +: Dry run the move operation (optional) -`-p|--path ` -: Defaults to the`{pwd}` folder (Default: null) \ No newline at end of file +`-p|--path ` +: Defaults to the`{pwd}` folder (optional) \ No newline at end of file diff --git a/docs/cli/serve.md b/docs/cli/docset/serve.md similarity index 77% rename from docs/cli/serve.md rename to docs/cli/docset/serve.md index a77cb4c72..c3284eb18 100644 --- a/docs/cli/serve.md +++ b/docs/cli/docset/serve.md @@ -6,13 +6,13 @@ File systems changes will be reflected without having to restart the server. ## Usage ``` -serve [options...] [-h|--help] [--version] +docs-builder serve [options...] [-h|--help] [--version] ``` ## Options -`-p|--path ` -: Path to serve the documentation. Defaults to the`{pwd}/docs` folder (Default: null) +`-p|--path ` +: Path to serve the documentation. Defaults to the`{pwd}/docs` folder (optional) `--port` `` : Port to serve the documentation. (Default: 3000) \ No newline at end of file diff --git a/docs/cli/inbound-links-validate.md b/docs/cli/inbound-links-validate.md deleted file mode 100644 index 16e36710c..000000000 --- a/docs/cli/inbound-links-validate.md +++ /dev/null @@ -1,17 +0,0 @@ -# inbound-links validate - -Validate all published cross_links in all published links.json files. - -## Usage - -``` -inbound-links validate [options...] [-h|--help] [--version] -``` - -## Options - -`--from` `` -: (Default: null) - -`--to` `` -: (Default: null) \ No newline at end of file diff --git a/docs/cli/index.md b/docs/cli/index.md index 5a454f483..0d92b0c57 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1,5 +1,5 @@ --- -navigation_title: docs-builder +navigation_title: docs-builder CLI --- # Command line interface diff --git a/docs/cli/inbound-links-validate-all.md b/docs/cli/links/inbound-links-validate-all.md similarity index 64% rename from docs/cli/inbound-links-validate-all.md rename to docs/cli/links/inbound-links-validate-all.md index 5f4cc0a91..3563db79d 100644 --- a/docs/cli/inbound-links-validate-all.md +++ b/docs/cli/links/inbound-links-validate-all.md @@ -5,5 +5,5 @@ Validate all published cross_links in all published links.json files. ## Usage ``` -inbound-links validate-all [-h|--help] [--version] +docs-builder inbound-links validate-all [-h|--help] [--version] ``` \ No newline at end of file diff --git a/docs/cli/inbound-links-validate-link-reference.md b/docs/cli/links/inbound-links-validate-link-reference.md similarity index 54% rename from docs/cli/inbound-links-validate-link-reference.md rename to docs/cli/links/inbound-links-validate-link-reference.md index 502f4ec0a..b9eaca3c2 100644 --- a/docs/cli/inbound-links-validate-link-reference.md +++ b/docs/cli/links/inbound-links-validate-link-reference.md @@ -5,13 +5,13 @@ Validate a locally published links.json file against all published links.json fi ## Usage ``` -inbound-links validate-link-reference [options...] [-h|--help] [--version] +docs-builder inbound-links validate-link-reference [options...] [-h|--help] [--version] ``` ## Options -`--file` `` -: Path to `links.json` defaults to '.artifacts/docs/html/links.json' (Default: null) +`--file` `` +: Path to `links.json` defaults to '.artifacts/docs/html/links.json' (optional) -`-p|--path ` -: Defaults to the `{pwd}` folder (Default: null) \ No newline at end of file +`-p|--path ` +: Defaults to the `{pwd}` folder (optional) \ No newline at end of file diff --git a/docs/cli/links/inbound-links-validate.md b/docs/cli/links/inbound-links-validate.md new file mode 100644 index 000000000..80036eec2 --- /dev/null +++ b/docs/cli/links/inbound-links-validate.md @@ -0,0 +1,17 @@ +# inbound-links validate + +Validate all published cross_links in all published links.json files. + +## Usage + +``` +docs-builder inbound-links validate [options...] [-h|--help] [--version] +``` + +## Options + +`--from` `` +: (optional) + +`--to` `` +: (optional) \ No newline at end of file From 335d7a6e70a7fada202b24d7c1819fb8e9274ebd Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 16:34:39 +0200 Subject: [PATCH 03/86] stage changes --- docs/cli/assembler/index.md | 61 ++++++++++++++++++++++++++++++++++++- docs/cli/docset/build.md | 2 +- docs/cli/docset/index.md | 23 +++++++++++++- docs/cli/index.md | 61 ++++++++++++++++++++++++------------- docs/cli/links/index.md | 15 +++++++++ 5 files changed, 137 insertions(+), 25 deletions(-) create mode 100644 docs/cli/links/index.md diff --git a/docs/cli/assembler/index.md b/docs/cli/assembler/index.md index e43e896a9..6c92bac9e 100644 --- a/docs/cli/assembler/index.md +++ b/docs/cli/assembler/index.md @@ -2,4 +2,63 @@ navigation_title: "assembler" --- -# The assembler namespace \ No newline at end of file +# Assembler commands + +Assembler builds bring together all isolated builds and turn them into the overall documentation that gets published. + +If you want to build the latest documentation, you can do so using the following commands + +:::{note} +When assembling using the `config init --local` option, it's advised to create an empty directory to run these commands in. +This creates a dedicated workspace for the assembler build and any local changes that you might want to test. +::: + +```bash +docs-builder assembler config init --local +docs-builder assemble --serve +``` + +The full assembled documentation should now be running at http://localhost:4000. + +The [assemble](assemble.md) command is syntactic sugar over the following commands: + +```bash +docs-builder assembler config init --local +docs-builder assembler clone +docs-builder assembler build +docs-builder assembler serve +``` + +Which may be more appropriate to call in isolation depending on the workflow you are going for. + +All `assembler` commans take an `--environment ` argument that defaults to 'dev' but can be set e.g to 'prod' to +build the production documentation. See [assembler.yml](../../configure/site/index.md) configuration for which environments are +available + +## Build commands + +- [assemble](assemble.md) +- [assembler build](assembler-build.md) +- [assembler clone](assembler-clone.md) +- [assembler config init](assembler-config-init.md) +- [assembler index](assembler-index.md) +- [assembler serve](assembler-serve.md) + +## Specialized build commands + +- [assembler bloom-filter create](assembler-bloom-filter-create.md) +- [assembler bloom-filter lookup](assembler-bloom-filter-lookup.md) + +## Validation commands + +- [assembler content-source match](assembler-content-source-match.md) +- [assembler content-source validate](assembler-content-source-validate.md) +- [assembler navigation validate](assembler-navigation-validate.md) +- [assembler navigation validate-link-reference](assembler-navigation-validate-link-reference.md) + +## Deploy commands + +- [assembler deploy apply](assembler-deploy-apply.md) +- [assembler deploy plan](assembler-deploy-plan.md) +- [assembler deploy update-redirects](assembler-deploy-update-redirects.md) + diff --git a/docs/cli/docset/build.md b/docs/cli/docset/build.md index c071f51c7..fcac7e3da 100644 --- a/docs/cli/docset/build.md +++ b/docs/cli/docset/build.md @@ -1,4 +1,4 @@ -# generate (root command) +# build Converts a source Markdown folder or file to an output folder diff --git a/docs/cli/docset/index.md b/docs/cli/docset/index.md index c456dee22..fc11c183c 100644 --- a/docs/cli/docset/index.md +++ b/docs/cli/docset/index.md @@ -2,4 +2,25 @@ navigation_title: "documentation set" --- -# Documentation set commands \ No newline at end of file +# Documentation Set Commands + +An isolated build means building a single documentation set. + +A `Documentation Set` is defined as a folder containing a [docset.yml](../configure/content-set/index.md) file. + +These commands are typically what you interface with when you are working on the documentation of a single repository locally. + +## Isolated build commands + +`build` is the default command so you can just run `docs-builder` to build a single documentation set. `docs-builder` will +locate the `docset.yml` anywhere in the directory tree automatically and build the documentation. + +- [build](docset/build.md) - build a single documentation set (incrementally) +- [serve](docset/serve.md) - partial build and serve documentation as needed at http://localhost:3000 +- [index](docset/index-command.md) - ingest a single documentation set to an Elasticsearch index. + +## Refactor commands + +- [mv](docset/mv.md) - move a file or folder to a new location. This will rewrite all links in all files too. +- [diff validate](docset/diff-validate.md) - validate that local changes are reflected in [redirects.yml](../contribute/redirects.md) + diff --git a/docs/cli/index.md b/docs/cli/index.md index 0d92b0c57..84db961d4 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -4,27 +4,44 @@ navigation_title: docs-builder CLI # Command line interface -- assemble -- assembler bloom-filter create -- assembler bloom-filter lookup -- assembler build -- assembler clone -- assembler config init -- assembler content-source match -- assembler content-source validate -- assembler deploy apply -- assembler deploy plan -- assembler deploy update-redirects -- assembler index -- assembler navigation validate -- assembler navigation validate-link-reference -- assembler serve -- diff validate -- inbound-links validate -- inbound-links validate-all -- inbound-links validate-link-reference -- index -- mv -- serve +`docs-builder` is the binary used to invoke various commands. +These commands can be roughly grouped into three main categories +- [Isolated commands](#isolated-commands) +- [Link commands](#link-commands) +- [Assembler commands](#assembler-commands) +### Global options + +The following options are available for all commands: + +`--log-level ` +: Change the log level one of ( `trace`, `debug`, `info`, `warn`, `error`, `critical`). Defaults to `info` + +`--config-source` or `-c` +: Explicitly set the configuration source one of `local`, `remote` or `embedded`. Defaults to `local` if available + other wise `embedded` + +## Isolated Commands + +An isolated build means building a single documentation set. + +A `Documentation Set` is defined as a folder containing a [docset.yml](../configure/content-set/index.md) file. + +These commands are typically what you interface with when you are working on the documentation of a single repository locally. + +[See available CLI commands for documentation sets](docset/index.md) + +## Link Commands + +Outbound links, those going from the documentation set to other sources, are validated as part of the build process. + +Inbound links, those going from other sources to the documentation set, are validated using specialized commands. + +[See available CLI commands for inbound links](links/index.md) + +## Assembler Commands + +Assembler builds bring together all isolated builds and turn them into the overall documentation that gets published. + +[See available CLI commands for assembler](assembler/index.md) diff --git a/docs/cli/links/index.md b/docs/cli/links/index.md new file mode 100644 index 000000000..60f838ba3 --- /dev/null +++ b/docs/cli/links/index.md @@ -0,0 +1,15 @@ +--- +navigation_title: links +--- + +# Inbound Links + +Outbound links, those going from the documentation set to other sources, are validated as part of the build process. + +Inbound links, those going from other sources to the documentation set, are validated using specialized commands. + +### Inbound link validation commands + +- [inbound-links validate-all](links/inbound-links-validate-all.md) - validate all inbounds links as published to the links registry. +- [inbound-links validate](links/inbound-links-validate.md) - validate inbound links from and to specific repositories +- [inbound-links validate-link-reference](links/inbound-links-validate-link-reference.md) - validate a local link reference artifact from [build](docset/build.md) with the published registry From 9b65802d4dcdfb0655c1f14dfecf1438d1a3b0f2 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 18:51:56 +0200 Subject: [PATCH 04/86] Finish documenting cli commands --- docs/cli/assembler/assemble.md | 45 ++++++++- .../assembler-bloom-filter-create.md | 8 +- .../assembler-bloom-filter-lookup.md | 2 +- docs/cli/assembler/assembler-build.md | 27 +++++- docs/cli/assembler/assembler-clone.md | 4 +- docs/cli/assembler/assembler-config-init.md | 12 ++- .../assembler-content-source-match.md | 24 ++++- .../assembler-content-source-validate.md | 2 + docs/cli/assembler/assembler-deploy-apply.md | 2 +- docs/cli/assembler/assembler-deploy-plan.md | 2 +- ...bler-navigation-validate-link-reference.md | 2 + .../assembler-navigation-validate.md | 2 +- docs/cli/assembler/assembler-serve.md | 2 +- docs/cli/docset/build.md | 92 +++++-------------- docs/cli/docset/diff-validate.md | 6 +- docs/cli/docset/mv.md | 6 +- docs/cli/docset/serve.md | 7 +- .../Commands/IsolatedBuildCommand.cs | 2 +- 18 files changed, 154 insertions(+), 93 deletions(-) diff --git a/docs/cli/assembler/assemble.md b/docs/cli/assembler/assemble.md index 135cc499d..e8c5bcc8a 100644 --- a/docs/cli/assembler/assemble.md +++ b/docs/cli/assembler/assemble.md @@ -1,6 +1,6 @@ # assemble -Do a full assembler clone and assembler build in one swoop +Do a full assembler clone, build and optional serving of the full documentation in one swoop ## Usage @@ -8,6 +8,49 @@ Do a full assembler clone and assembler build in one swoop docs-builder assemble [options...] [-h|--help] [--version] ``` + + +## Usage examples + +The following will clone the repository, build the documentation and serve it on port 4000 using the embedded configuration inside the `docs-builder` binary. + +```bash +docs-builder assemble --serve +``` + +This single command is equivalent to the following commands: + +```bash +docs-builder assembler clone +docs-builder assembler build +docs-builder assembler serve +``` + +### Using a local workspace for assembler builds + +Where this command really shines is when you want to create a temporary workspace folder to validate: + +* changes to [site wide configuration](../../configure/site/index.md) +* changes to one or more repositories and their effect on the assembler build. + +To do that inside an empty folder, call: + +```bash +docs-builder assembler config init --local +docs-builder assemble --serve +``` + +This will source the latest configuration from [The `config` folder on the `main` branch of `docs-builder`](https://github.com/elastic/docs-builder/tree/main/config) +and place them inside the `$(pwd)/config` folder. + +Now when you call `docs-builder assemble` rather than using the embedded configuration, it will use local one that one you just created. +You can be explicit about the configuration source to use: + +```bash +docs-builder assembler config init --local +docs-builder assemble --serve -c local +``` + ## Options `--strict` `` diff --git a/docs/cli/assembler/assembler-bloom-filter-create.md b/docs/cli/assembler/assembler-bloom-filter-create.md index 968a2536b..cda2ec4a2 100644 --- a/docs/cli/assembler/assembler-bloom-filter-create.md +++ b/docs/cli/assembler/assembler-bloom-filter-create.md @@ -4,7 +4,13 @@ navigation_title: "bloom-filter create" # assembler bloom-filter create -Generate the bloom filter binary file +Generates a bloom filter that gets embedded into the `docs-builder` binary. + +This bloom filter is used to determine whether a document's `mapped_page` in the frontmatter exists in + +the project of [legacy-url-mappings](../../configure/site/legacy-url-mappings.md) + +The existence determines how the document history selector should be populated. ## Usage diff --git a/docs/cli/assembler/assembler-bloom-filter-lookup.md b/docs/cli/assembler/assembler-bloom-filter-lookup.md index 3164f5a9c..bdb302712 100644 --- a/docs/cli/assembler/assembler-bloom-filter-lookup.md +++ b/docs/cli/assembler/assembler-bloom-filter-lookup.md @@ -3,7 +3,7 @@ navigation_title: "bloom-filter lookup" --- # assembler bloom-filter lookup -Lookup whether a path exists in the bloomfilter +Test command to assert if an old V2 url matches with our bloom filter ## Usage diff --git a/docs/cli/assembler/assembler-build.md b/docs/cli/assembler/assembler-build.md index bceaa633b..6134277a1 100644 --- a/docs/cli/assembler/assembler-build.md +++ b/docs/cli/assembler/assembler-build.md @@ -4,7 +4,14 @@ navigation_title: "build" # assembler build -Builds all repositories +:::note +This command requires that you've previously ran `docs-builder assembler clone` to clone the documentation sets. +If you clone using a certain `--environment` you must also use that same `--environment` when building. +::: + +Builds all the documentation sets and assembles them into an assembled complete documentation site that's ready to be deployed. + +It uses [the site configuration files](../../configure/site/index.md) to direct how the documentation sets should be assembled. ## Usage @@ -26,5 +33,19 @@ docs-builder assembler build [options...] [-h|--help] [--version] `--show-hints` `` : Show hints from all documentation sets during assembler build (optional) -`--exporters` `?>` -: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (optional) \ No newline at end of file +`--exporters` `` +: Set available exporters: + + * html + * es, + * config, + * links, + * state, + * llm, + * redirect, + * metadata, + * default + * none. + + Defaults to (html, llm, config, links, state, redirect) or 'default'. (optional) + diff --git a/docs/cli/assembler/assembler-clone.md b/docs/cli/assembler/assembler-clone.md index 3469bc13d..0a555990f 100644 --- a/docs/cli/assembler/assembler-clone.md +++ b/docs/cli/assembler/assembler-clone.md @@ -4,7 +4,9 @@ navigation_title: "clone" # assembler clone -Clones all repositories +Clones all repositories. Defaults to `$(pwd)/.artifacts/checkouts/{content_source}`. + +The `content_source` is the `content_source` of the `--environment` option as configured in `assembly.yaml` ## Usage diff --git a/docs/cli/assembler/assembler-config-init.md b/docs/cli/assembler/assembler-config-init.md index ea40dc237..b113be0e4 100644 --- a/docs/cli/assembler/assembler-config-init.md +++ b/docs/cli/assembler/assembler-config-init.md @@ -4,7 +4,17 @@ navigation_title: "config init" # assembler config init -Clone the configuration folder +Sources the configuration from [The `config` folder on the `main` branch of `docs-builder`](https://github.com/elastic/docs-builder/tree/main/config) + +By default, the configuration is placed in a special application folder as its main usages is to be used by CI environments. + +* OSX: `~/Library/Application Support/docs-builder` [NSApplicationSupportDirectory](https://developer.apple.com/documentation/foundation/filemanager/searchpathdirectory/applicationsupportdirectory) +* Linux: `~/.config/docs-builder` +* Windows: `%APPDATA%\docs-builder` + +You can also use the `--local` option to save the configuration locally in the current working directory. This exposes a great way to assemble the full documentation locally in an empty directory. + +See [using assemble to create local workspaces](assemble.md#using-a-local-workspace-for-assembler-builds) for more information. ## Usage diff --git a/docs/cli/assembler/assembler-content-source-match.md b/docs/cli/assembler/assembler-content-source-match.md index 79f2bb890..67781a42a 100644 --- a/docs/cli/assembler/assembler-content-source-match.md +++ b/docs/cli/assembler/assembler-content-source-match.md @@ -4,16 +4,30 @@ navigation_title: "content-source match" # assembler content-source match +This command is used to match a repository and branch to a content source it will emit the following `$GITHUB_OUTPUT`: + +* `content-source-match` - whether the branch is a configured content source +* `content-source-next` - whether the branch is the next content source +* `content-source-current` - whether the branch is the current content source +* `content-source-speculative` - whether the branch is a speculative content source. + +#### Speculative builds + +If branches follow semantic versioning, if a branch is cut that is greater than the current version, it will be considered a speculative build. +`docs-builer`'s shared workflow will trigger even if it's not specified as a content source in `assembler.yml`. + +This allows a branch `links.json` to be published to the `Link Service` a head of time before it's configured as a content source. + ## Usage ``` -docs-builder assembler content-source match [arguments...] [-h|--help] [--version] +docs-builder assembler content-source match [-h|--help] [--version] ``` ## Arguments -`[0] ` -: +` +: The name of the `elastic/` repository you want to match if it should be build on CI -`[1] ` -: \ No newline at end of file +` +: The branch you want to match if it should be build on CI` \ No newline at end of file diff --git a/docs/cli/assembler/assembler-content-source-validate.md b/docs/cli/assembler/assembler-content-source-validate.md index e1742c7bf..661269a81 100644 --- a/docs/cli/assembler/assembler-content-source-validate.md +++ b/docs/cli/assembler/assembler-content-source-validate.md @@ -4,6 +4,8 @@ navigation_title: "content-source validate" # assembler content-source validate +Validates that the configured content source branches are publishing succesfully to the `Links Service`. + ## Usage ``` diff --git a/docs/cli/assembler/assembler-deploy-apply.md b/docs/cli/assembler/assembler-deploy-apply.md index 4e2af8a50..ce1c0df27 100644 --- a/docs/cli/assembler/assembler-deploy-apply.md +++ b/docs/cli/assembler/assembler-deploy-apply.md @@ -4,7 +4,7 @@ navigation_title: "deploy apply" # assembler deploy apply -Applies a sync plan +Applies an incremental synchronization plan created by [`docs-builder assembler deploy plan`](./assembler-deploy-plan). ## Usage diff --git a/docs/cli/assembler/assembler-deploy-plan.md b/docs/cli/assembler/assembler-deploy-plan.md index 83a86d4e6..cf4e5c5e7 100644 --- a/docs/cli/assembler/assembler-deploy-plan.md +++ b/docs/cli/assembler/assembler-deploy-plan.md @@ -4,7 +4,7 @@ navigation_title: "deploy plan" # assembler deploy plan -Creates a sync plan +Creates an incremental synchronization plan by comparing the reote `--s3-bucket-name` with the local output of the build. ## Usage diff --git a/docs/cli/assembler/assembler-navigation-validate-link-reference.md b/docs/cli/assembler/assembler-navigation-validate-link-reference.md index c06ca4dc6..678724217 100644 --- a/docs/cli/assembler/assembler-navigation-validate-link-reference.md +++ b/docs/cli/assembler/assembler-navigation-validate-link-reference.md @@ -6,6 +6,8 @@ navigation_title: "navigation validate-link-reference" Validate all published links in links.json do not collide with navigation path_prefixes and all urls are unique. +Read more about [navigation](../../configure/site/navigation.md). + ## Usage ``` diff --git a/docs/cli/assembler/assembler-navigation-validate.md b/docs/cli/assembler/assembler-navigation-validate.md index d438f9b3c..4e897d41e 100644 --- a/docs/cli/assembler/assembler-navigation-validate.md +++ b/docs/cli/assembler/assembler-navigation-validate.md @@ -4,7 +4,7 @@ navigation_title: "navigation validate" # assembler navigation validate -Validates navigation.yml does not contain colliding path prefixes and all urls are unique +Validates [navigation.yml](../../configure/site/navigation.md) does not contain colliding path prefixes and all urls are unique ## Usage diff --git a/docs/cli/assembler/assembler-serve.md b/docs/cli/assembler/assembler-serve.md index e96797cca..805d1b438 100644 --- a/docs/cli/assembler/assembler-serve.md +++ b/docs/cli/assembler/assembler-serve.md @@ -4,7 +4,7 @@ navigation_title: "serve" # assembler serve -Serve the output of an assembler build +Serve the output of an assembler build on `http://localhost:4000/` ## Usage diff --git a/docs/cli/docset/build.md b/docs/cli/docset/build.md index fcac7e3da..d300c6ee9 100644 --- a/docs/cli/docset/build.md +++ b/docs/cli/docset/build.md @@ -1,6 +1,12 @@ # build -Converts a source Markdown folder or file to an output folder +Builds a local documentation set folder. + +Repeated invocations will do incremental builds of only the changed files unless: + +* The base branch has changed +* The state file in the output folder has been removed +* The `--force` option is specified. ## Usage @@ -35,76 +41,22 @@ docs-builder [command] [options...] [-h|--help] [--version] `--metadata-only` `` : Only emit documentation metadata to output, ignored if 'exporters' is also set (optional) -`--exporters` `?>` -: Set available exporters: html, es, config, links, state, llm, redirect, metadata, none. Defaults to (html, config, links, state, redirect) or 'default'. (optional) - -`--canonical-base-url` `` -: The base URL for the canonical url tag (optional) - -## Commands - -`assemble` -: Do a full assembler clone and assembler build in one swoop - -`assembler bloom-filter create` -: Generate the bloom filter binary file - -`assembler bloom-filter lookup` -: Lookup whether path exists in the bloomfilter - -`assembler build` -: Builds all repositories - -`assembler clone` -: Clones all repositories - -`assembler config init` -: Clone the configuration folder - -`assembler content-source match` -: +`--exporters` `` +: Set available exporters: -`assembler content-source validate` -: + * html + * es, + * config, + * links, + * state, + * llm, + * redirect, + * metadata, + * default + * none. -`assembler deploy apply` -: Applies a sync plan + Defaults to (html, llm, config, links, state, redirect) or 'default'. (optional) -`assembler deploy plan` -: Creates a sync plan -`assembler deploy update-redirects` -: Refreshes the redirects mapping in Cloudfront's KeyValueStore - -`assembler index` -: Index documentation to Elasticsearch, calls `docs-builder assembler build --exporters elasticsearch`. Exposes more options - -`assembler navigation validate` -: Validates navigation.yml does not contain colliding path prefixes and all urls are unique - -`assembler navigation validate-link-reference` -: Validate all published links in links.json do not collide with navigation path_prefixes and all urls are unique. - -`assembler serve` -: Serve the output of an assembler build - -`diff validate` -: Validates redirect updates in the current branch using the redirect file against changes reported by git. - -`inbound-links validate` -: Validate all published cross_links in all published links.json files. - -`inbound-links validate-all` -: Validate all published cross_links in all published links.json files. - -`inbound-links validate-link-reference` -: Validate a locally published links.json file against all published links.json files in the registry - -`index` -: Index a single documentation set to Elasticsearch, calls `docs-builder --exporters elasticsearch`. Exposes more options - -`mv` -: Move a file from one location to another and update all links in the documentation - -`serve` -: Continuously serve a documentation folder at http://localhost:3000. File systems changes will be reflected without having to restart the server. \ No newline at end of file +`--canonical-base-url` `` +: The base URL for the canonical url tag (optional) \ No newline at end of file diff --git a/docs/cli/docset/diff-validate.md b/docs/cli/docset/diff-validate.md index e29f5a06a..02c97d84b 100644 --- a/docs/cli/docset/diff-validate.md +++ b/docs/cli/docset/diff-validate.md @@ -1,6 +1,10 @@ # diff validate -Validates redirect updates in the current branch using the redirect file against changes reported by git. +Gathers the local changes by inspecting the git log, stashed and unstashed changes. + +It currently validates the following: + +* Ensures that renames and deletions are reflected in [redirects.yml](../../contribute/redirects.md) ## Usage diff --git a/docs/cli/docset/mv.md b/docs/cli/docset/mv.md index ec803baf9..173563b1a 100644 --- a/docs/cli/docset/mv.md +++ b/docs/cli/docset/mv.md @@ -1,6 +1,6 @@ # mv -Move a file from one location to another and update all links in the documentation +Move a file or folder from one location to another and update all links in the documentation ## Usage @@ -11,10 +11,10 @@ docs-builder mv [arguments...] [options...] [-h|--help] [--version] ## Arguments `[0] ` -: The source file or folder path to move from +: The source file or folder path to move from (required) `[1] ` -: The target file or folder path to move to +: The target file or folder path to move to (required) ## Options diff --git a/docs/cli/docset/serve.md b/docs/cli/docset/serve.md index c3284eb18..018b995fe 100644 --- a/docs/cli/docset/serve.md +++ b/docs/cli/docset/serve.md @@ -1,7 +1,12 @@ # serve Continuously serve a documentation folder at http://localhost:3000. -File systems changes will be reflected without having to restart the server. + +When running `docs-builder serve`, the documentation is not built in full. +Each page will be build on the fly continuously when requested in the browser. + +The `serve` command is also `live reload` enabled so that file systems changes will be reflected without having to restart the server. +This includes changes to the documentation files, the navigation, or the configuration files. ## Usage diff --git a/src/tooling/docs-builder/Commands/IsolatedBuildCommand.cs b/src/tooling/docs-builder/Commands/IsolatedBuildCommand.cs index 4673fc5d0..0dd4514d6 100644 --- a/src/tooling/docs-builder/Commands/IsolatedBuildCommand.cs +++ b/src/tooling/docs-builder/Commands/IsolatedBuildCommand.cs @@ -23,7 +23,7 @@ IConfigurationContext configurationContext ) { /// - /// Converts a source Markdown folder or file to an output folder + /// Builds a source documentation set folder. /// global options: /// --log-level level /// From 69bf2d2b164e9889e6af837ecdea12d36d5846a6 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 18:58:32 +0200 Subject: [PATCH 05/86] Cleanup migration --- docs/_docset.yml | 4 --- docs/cli/index.md | 2 +- docs/migration/freeze/gh-action.md | 32 ------------------------ docs/migration/freeze/index.md | 40 ------------------------------ docs/migration/index.md | 4 +-- 5 files changed, 3 insertions(+), 79 deletions(-) delete mode 100644 docs/migration/freeze/gh-action.md delete mode 100644 docs/migration/freeze/index.md diff --git a/docs/_docset.yml b/docs/_docset.yml index 5833e223a..47df630a8 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -139,10 +139,6 @@ toc: - folder: migration children: - file: index.md - - folder: freeze - children: - - file: index.md - - file: gh-action.md - file: syntax.md - file: ia.md - file: versioning.md diff --git a/docs/cli/index.md b/docs/cli/index.md index 84db961d4..158c27d56 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1,5 +1,5 @@ --- -navigation_title: docs-builder CLI +navigation_title: CLI (docs-builder) --- # Command line interface diff --git a/docs/migration/freeze/gh-action.md b/docs/migration/freeze/gh-action.md deleted file mode 100644 index 8c32e3f1e..000000000 --- a/docs/migration/freeze/gh-action.md +++ /dev/null @@ -1,32 +0,0 @@ -# GH Action - -## Overview - -The documentation team will use a GitHub Action to enforce the content freeze by adding comments to pull requests that modify `.asciidoc` files. It complements the use of `CODEOWNERS` to ensure changes during a freeze period are reviewed and approved by the `@docs-freeze-team`. - -## How It Works -1. **Trigger**: The Action is triggered on pull request events (`opened`, `reopened`, or `synchronize`). -2. **Check Changes**: It checks the diff between the latest commits to detect modifications to `.asciidoc` files. -3. **Add Comment**: If changes are detected, the Action posts a comment in the pull request, reminding the contributor of the freeze. - -```yaml -name: Comment on PR for .asciidoc changes - -on: - pull_request: - types: - - synchronize - - opened - - reopened - branches: - - main - - master - - "9.0" - -jobs: - comment-on-asciidoc-change: - permissions: - contents: read - pull-requests: write - uses: elastic/docs-builder/.github/workflows/comment-on-asciidoc-changes.yml@main -``` diff --git a/docs/migration/freeze/index.md b/docs/migration/freeze/index.md deleted file mode 100644 index b4d03a011..000000000 --- a/docs/migration/freeze/index.md +++ /dev/null @@ -1,40 +0,0 @@ -# Documentation Freeze - -:::{important} -During the documentation freeze, maintaining consistency and avoiding conflicts is key. To discourage documentation changes from merging during the documentation freeze, a [GH Action](./gh-action.md) is being added to all repositories with public-facing documentation. -::: - -During the documentation freeze, the Docs team will focus almost entirely on migration tasks to ensure all content is successfully migrated and will handle only emergency documentation requests and release-related activities. When the migration is complete, the docs team will assess any documentation requests that were submitted during the documentation freeze and ensure that they're still relevant in the new information architecture and format. - -:::{note} -The documentation freeze does not block you from merging asciidoc changes. However, you are strongly discouraged from merging changes to these files as any changes will not be carried forward in the migration and will be lost forever. -::: - -## Timeline - -* **29-Jan**: Merge all open Docs PRs by 12AM PST -* **30-Jan**: Documentation freeze begins for all public-facing Docs on main/master -* **20-Feb**: Documentation freeze ends -* **25-Mar**: 9.0.0 Docs + Elastic Docs v3 GA - -### Details - -:::{important} -We are freezing only the main/master public-facing Docs. You can continue to make changes to the 8.x Docs by creating PRs in the 8.x branches. -::: - -Before we migrate on 30-Jan, we will close all unmerged Docs PRs targeting main/master. When the freeze ends, you can open a new PR if the changes are still needed. - -We will not close PRs targeting main/master that also include code changes. After the freeze begins, merged PRs targeting main/master branches that include AsciiDoc changes will not be migrated. When the freeze ends, all 9.0.0 Docs changes will be made to the migrated Markdown Docs files. - -### During the freeze: - -* If you make Docs changes to the main/master branches, GitHub Actions will warn against merging the changes. -* You can make 8.x Docs changes by creating PRs in the relevant 8.x branches. -* For 9.0.0 Docs changes, [open an issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) in [elastic/docs-content](https://github.com/elastic/docs-content/issues) and we’ll incorporate the changes post migration. -* The Docs Team will focus exclusively on migrating content, with the exception of the following: - * Stack-versioned release notes, including 8.18.0, 9.0.0-beta1, -rc1, and -rc2 - * Serverless changelog - * Cloud Hosted and ECE release notes - -For any questions and emergency Docs requests, post in the [#docs](https://elastic.slack.com/archives/C0JF80CJZ) Slack channel. diff --git a/docs/migration/index.md b/docs/migration/index.md index d9749743a..265b53ed5 100644 --- a/docs/migration/index.md +++ b/docs/migration/index.md @@ -1,11 +1,11 @@ --- -navigation_title: Migration +navigation_title: Migration from Asciidoc --- # Migration to docs-builder :::{important} -We are enforcing a [Documentation Freeze](./freeze/index.md) while we migrate docs between our two build systems. +All repositories have been migrated to `docs-builder` however older branches may still be using `asciidoc`. ::: Migrating to Elastic Docs V3 is more than just moving to a new documentation build system. This migration includes: From 1daf6c891012407773b3539d22cb44c52290ca7c Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 19:05:22 +0200 Subject: [PATCH 06/86] touchups --- docs/cli/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli/index.md b/docs/cli/index.md index 158c27d56..f9d9410a3 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -7,7 +7,7 @@ navigation_title: CLI (docs-builder) `docs-builder` is the binary used to invoke various commands. These commands can be roughly grouped into three main categories -- [Isolated commands](#isolated-commands) +- [Documentation Set commands](#documentation-set-commands) - [Link commands](#link-commands) - [Assembler commands](#assembler-commands) @@ -22,9 +22,9 @@ The following options are available for all commands: : Explicitly set the configuration source one of `local`, `remote` or `embedded`. Defaults to `local` if available other wise `embedded` -## Isolated Commands +## Documentation Set Commands -An isolated build means building a single documentation set. +Commands that operate over a single documentation set. A `Documentation Set` is defined as a folder containing a [docset.yml](../configure/content-set/index.md) file. @@ -42,6 +42,6 @@ Inbound links, those going from other sources to the documentation set, are vali ## Assembler Commands -Assembler builds bring together all isolated builds and turn them into the overall documentation that gets published. +Assembler builds bring together all isolated documentation set builds and turn them into the overall documentation that gets published. [See available CLI commands for assembler](assembler/index.md) From a030f8524c39c4ecc6141cb867feb4b0627c7328 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 20:06:47 +0200 Subject: [PATCH 07/86] stage --- docs/_docset.yml | 3 +++ docs/cli/assembler/assembler-config-init.md | 2 +- docs/migration/index.md | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/_docset.yml b/docs/_docset.yml index 47df630a8..775bd804f 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -46,6 +46,9 @@ toc: - file: branching-strategy.md - file: add-repo.md - file: release-new-version.md + - folder: building-blocks + children: + - file: index.md - folder: configure children: - file: index.md diff --git a/docs/cli/assembler/assembler-config-init.md b/docs/cli/assembler/assembler-config-init.md index b113be0e4..cc23be77a 100644 --- a/docs/cli/assembler/assembler-config-init.md +++ b/docs/cli/assembler/assembler-config-init.md @@ -10,7 +10,7 @@ By default, the configuration is placed in a special application folder as its m * OSX: `~/Library/Application Support/docs-builder` [NSApplicationSupportDirectory](https://developer.apple.com/documentation/foundation/filemanager/searchpathdirectory/applicationsupportdirectory) * Linux: `~/.config/docs-builder` -* Windows: `%APPDATA%\docs-builder` +* {icon}`logo_windows` Windows: `%APPDATA%\docs-builder` You can also use the `--local` option to save the configuration locally in the current working directory. This exposes a great way to assemble the full documentation locally in an empty directory. diff --git a/docs/migration/index.md b/docs/migration/index.md index 265b53ed5..f385921da 100644 --- a/docs/migration/index.md +++ b/docs/migration/index.md @@ -1,5 +1,5 @@ --- -navigation_title: Migration from Asciidoc +navigation_title: Asciidoc Migration --- # Migration to docs-builder From 8ed7a3bc916d3f93c4c8ce1f92179e0f1cbc3d54 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 20:15:53 +0200 Subject: [PATCH 08/86] stage --- docs/building-blocks/index.md | 69 +++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/building-blocks/index.md diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md new file mode 100644 index 000000000..b1be46bf1 --- /dev/null +++ b/docs/building-blocks/index.md @@ -0,0 +1,69 @@ +--- +navigation_title: Building Blocks +--- + +# Building Blocks + +This section explains all the building blocks that are used to build the documentation. + +## Documentation Set + +A single folder containing the documentation of a single repository. At a minimum, this folder should contain: + +* `docset.yml` file +* `index.md` file + +See [docset.yml](../configure/content-set/index.md) for more configuration details. + +## Assembled Documentation + +The product of building many documentation sets and weaving them in to a global navigation producing the fully assembled documentation site. + +See [site configuration](../configure/site/index.md) for more details on the actual configuration. + +## Distributed documentation + +The purpose of separating building documentation sets and assembling them is to allow for distributed builds. + +Each build of documentation set produces a `links.json` (Link Index) file that contains all the linkable resources in the repository. +This `links.json` file is then published to a central location (Link Service) everytime a repository successfully builds on its respective default integration branch. + +For example, [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) represents all linkable resources in the Elasticsearch repository. + +This allows us to: + +* Validate outbound and inbound links ahead of time, even during local `docs-builder` builds. +* Snapshot assembled 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. + +## Link Service + +The central location where all the Link Index files are published. This is a simple S3 bucket fronted by CloudFront. + +## Link Index + +Each repository's branch will get in individual Link Index file in the `Link Serve` representing all linkable resources of that repository's branch. +See, for example: [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json). +This file is used to resolve [Outbound Crosslinks](#outbound-crosslinks) and [Inbound Crosslinks](#inbound-crosslinks). + +## Link Registry + +A [single file](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json) that contains all the [Link Index files](#link-index) for all the repositories. +This is file is published everytime [Link Index](#link-index) files are published to the Link Service. The update is handled by an AWS Lambda function that listens to SQS triggers by S3 events. + +## Outbound Crosslinks + +Outbound crosslinks are links from the documentation set that's being built to others. If both repositories publish to the same `Link Service`, they can link to each other using the `://` syntax. + +Read more about general link syntax in the [](../syntax/links.md) section. + +## Inbound Crosslinks + +Inbound crosslinks are links from other documentation sets to the one that's being built. + +If both repositories publish to the same `Link Service`, they can link to each other using the `://` syntax. + +Read more about general link syntax in the [](../syntax/links.md) section. + +Using our [Link Service](#link-service), we can validate if deletions or renames of files in the documentation set break other repositories ahead of time. From 0bfe1344449fdb54083b0cd279a4bfe5d9f352df Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Tue, 30 Sep 2025 20:28:48 +0200 Subject: [PATCH 09/86] First pass of claude over building blocks --- docs/_docset.yml | 8 ++ .../assembled-documentation.md | 50 +++++++ .../distributed-documentation.md | 63 +++++++++ docs/building-blocks/documentation-set.md | 49 +++++++ docs/building-blocks/inbound-crosslinks.md | 129 ++++++++++++++++++ docs/building-blocks/index.md | 69 ++++------ docs/building-blocks/link-index.md | 86 ++++++++++++ docs/building-blocks/link-registry.md | 78 +++++++++++ docs/building-blocks/link-service.md | 59 ++++++++ docs/building-blocks/outbound-crosslinks.md | 109 +++++++++++++++ 10 files changed, 658 insertions(+), 42 deletions(-) create mode 100644 docs/building-blocks/assembled-documentation.md create mode 100644 docs/building-blocks/distributed-documentation.md create mode 100644 docs/building-blocks/documentation-set.md create mode 100644 docs/building-blocks/inbound-crosslinks.md create mode 100644 docs/building-blocks/link-index.md create mode 100644 docs/building-blocks/link-registry.md create mode 100644 docs/building-blocks/link-service.md create mode 100644 docs/building-blocks/outbound-crosslinks.md diff --git a/docs/_docset.yml b/docs/_docset.yml index 775bd804f..2e20447fa 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -49,6 +49,14 @@ toc: - folder: building-blocks children: - file: index.md + - file: documentation-set.md + - file: assembled-documentation.md + - file: distributed-documentation.md + - file: link-service.md + - file: link-index.md + - file: link-registry.md + - file: outbound-crosslinks.md + - file: inbound-crosslinks.md - folder: configure children: - file: index.md diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md new file mode 100644 index 000000000..8505653cf --- /dev/null +++ b/docs/building-blocks/assembled-documentation.md @@ -0,0 +1,50 @@ +--- +navigation_title: Assembled Documentation +--- + +# Assembled Documentation + +**Assembled documentation** is the product of building many [documentation sets](documentation-set.md) and weaving them into a global navigation to produce the fully assembled documentation site. + +## How it works + +The assembler: + +1. Clones multiple documentation repositories +2. Builds each documentation set independently +3. Combines them according to a global navigation configuration +4. Produces a unified documentation website + +## Benefits + +By assembling multiple documentation sets together, you can: + +* **Centralize navigation** - Present a unified experience across multiple repositories +* **Cross-link content** - Link between different documentation sets seamlessly +* **Version coordination** - Control which versions of different repositories appear together +* **Product-level organization** - Organize documentation by product rather than repository + +## Configuration + +Assembled documentation is configured through the site configuration, which defines: + +* Which repositories to include +* What versions of each repository to build +* How to organize the global navigation +* URL structure and routing + +See [Site Configuration](../configure/site/index.md) for complete details on configuring assembled documentation. + +## Build process + +The typical build process for assembled documentation: + +1. **Clone** - Clone all configured repositories using `docs-builder assembler clone` +2. **Build** - Build all documentation sets using `docs-builder assembler build` +3. **Export** - Export the assembled site in various formats (HTML, Elasticsearch index, etc.) + +## Related concepts + +* [Documentation Set](documentation-set.md) - The individual units being assembled +* [Distributed Documentation](distributed-documentation.md) - How documentation sets work independently +* [Link Registry](link-registry.md) - How the assembler knows what to include diff --git a/docs/building-blocks/distributed-documentation.md b/docs/building-blocks/distributed-documentation.md new file mode 100644 index 000000000..b0a65d4fc --- /dev/null +++ b/docs/building-blocks/distributed-documentation.md @@ -0,0 +1,63 @@ +--- +navigation_title: Distributed Documentation +--- + +# Distributed Documentation + +**Distributed documentation** is the architectural approach that allows documentation sets to be built independently while still enabling cross-repository linking and validation. + +## Purpose + +The separation between building individual documentation sets and assembling them enables distributed builds, where: + +* Each repository builds its own documentation independently +* Builds don't block each other +* Teams maintain full autonomy over their documentation +* Cross-repository links are validated without requiring synchronized builds + +## How it works + +### Link Index publication + +Each time a documentation set is built successfully on its default integration branch, it produces and publishes a `links.json` file ([Link Index](link-index.md)) to a central location ([Link Service](link-service.md)). + +This Link Index contains all the linkable resources in that repository at that specific commit. + +### Example + +For instance, [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) represents all linkable resources in the Elasticsearch repository's main branch. + +## Benefits + +This distributed approach provides several key advantages: + +### Link validation + +* **Outbound links** - Validate links to other repositories ahead of time, even during local `docs-builder` builds +* **Inbound links** - Know when changes to your documentation would break links from other repositories + +### Resilient builds + +* **Isolation** - Documentation errors in one repository won't affect builds of other repositories +* **Fallback mechanism** - When a repository has build failures on its integration branch, the assembler falls back to the last known good commit +* **Snapshot builds** - Assembled builds only use commits that successfully produced a Link Index + +### Independent iteration + +* Teams can iterate on their documentation independently +* No coordination required for routine updates +* Faster feedback loops for documentation changes + +## Architecture components + +The distributed documentation system relies on several key components: + +* [Link Index](link-index.md) - Per-repository file of linkable resources +* [Link Service](link-service.md) - Central storage for Link Index files +* [Link Registry](link-registry.md) - Catalog of all available Link Index files +* [Outbound Crosslinks](outbound-crosslinks.md) - Links from one repository to another +* [Inbound Crosslinks](inbound-crosslinks.md) - Links from other repositories to yours + +## Local development + +Even during local development, `docs-builder` can access the Link Service to validate cross-repository links without requiring you to clone and build all related repositories. diff --git a/docs/building-blocks/documentation-set.md b/docs/building-blocks/documentation-set.md new file mode 100644 index 000000000..5ed4dc2a5 --- /dev/null +++ b/docs/building-blocks/documentation-set.md @@ -0,0 +1,49 @@ +--- +navigation_title: Documentation Set +--- + +# Documentation Set + +A **documentation set** is a single folder containing the documentation of a single repository. This is the fundamental unit of documentation in the docs-builder system. + +## Minimum requirements + +At a minimum, a documentation set folder must contain: + +* `docset.yml` - The configuration file that defines the structure and metadata of the documentation set +* `index.md` - The entry point or landing page for the documentation set + +## Purpose + +Documentation sets allow each repository to maintain its own documentation independently. Each set can be: + +* Built independently +* Versioned separately +* Maintained by different teams +* Published to its own schedule + +## Structure + +A typical documentation set might look like: + +``` +my-repo/ +└── docs/ + ├── docset.yml + ├── index.md + ├── getting-started.md + ├── configuration/ + │ ├── index.md + │ └── advanced.md + └── reference/ + └── api.md +``` + +## Configuration + +The `docset.yml` file controls how the documentation set is structured and built. See [Content Set Configuration](../configure/content-set/index.md) for complete configuration details. + +## Related concepts + +* [Assembled Documentation](assembled-documentation.md) - How multiple documentation sets are combined +* [Link Index](link-index.md) - How documentation sets publish their linkable resources diff --git a/docs/building-blocks/inbound-crosslinks.md b/docs/building-blocks/inbound-crosslinks.md new file mode 100644 index 000000000..9a7fe42ff --- /dev/null +++ b/docs/building-blocks/inbound-crosslinks.md @@ -0,0 +1,129 @@ +--- +navigation_title: Inbound Crosslinks +--- + +# Inbound Crosslinks + +**Inbound crosslinks** are links from other documentation sets to yours. Understanding and validating inbound crosslinks helps prevent breaking links in other repositories when you make changes. + +## Purpose + +Inbound crosslink validation allows you to: + +* **Detect breaking changes** - Know when renaming or deleting a file will break links from other repositories +* **Prevent regressions** - Avoid publishing changes that break documentation elsewhere +* **Coordinate changes** - Understand dependencies before making structural changes + +## How it works + +When you build your documentation, `docs-builder` can validate inbound crosslinks by: + +1. **Fetching your published Link Index** - Gets your repository's [Link Index](link-index.md) from the [Link Service](link-service.md) +2. **Comparing with local changes** - Compares your current local state with the published Link Index +3. **Detecting differences** - Identifies files that have been moved, renamed, or deleted +4. **Checking references** - Queries the Link Service to see if other repositories link to the changed files +5. **Reporting warnings** - Alerts you to potential breaking changes + +## Validation commands + +### Validate all inbound links + +Check all inbound crosslinks for your repository: + +```bash +docs-builder inbound-links validate-all +``` + +### Validate specific link reference + +Validate a locally built `links.json` against all published Link Index files: + +```bash +docs-builder inbound-links validate-link-reference --file .artifacts/docs/html/links.json +``` + +### Validate with filters + +Check inbound links from specific repositories or to specific resources: + +```bash +docs-builder inbound-links validate --from elasticsearch --to kibana +``` + +## Common scenarios + +### Moving a file + +If you move a file that other repositories link to: + +1. Create a redirect from the old path to the new path +2. Update your documentation's redirect configuration +3. Run inbound link validation to ensure the redirect works +4. Notify teams that maintain repositories with inbound links + +### Deleting a file + +Before deleting a file: + +1. Run inbound link validation to see if other repositories link to it +2. If there are inbound links, coordinate with those teams first +3. Consider leaving a redirect to related content +4. Update the other repositories to remove or update their links + +### Renaming headings + +Heading anchors are part of the Link Index. If other repositories link to specific headings in your documentation: + +1. Validate inbound links before renaming +2. Consider keeping old heading anchors if heavily linked +3. Document the change if coordination is needed + +## Integration with CI/CD + +You can integrate inbound link validation into your CI/CD pipeline: + +```yaml +- name: Validate inbound links + run: | + docs-builder inbound-links validate-link-reference \ + --file .artifacts/docs/html/links.json +``` + +This will fail the build if you're about to break links from other repositories. + +## Best practices + +### Set up redirects + +When moving or renaming files, always set up redirects: + +```yaml +# In your documentation's configuration +redirects: + - from: /old-path/file.html + to: /new-path/file.html +``` + +### Communicate changes + +If you need to make a breaking change: + +1. Run inbound link validation to identify affected repositories +2. File issues or notify maintainers of affected repositories +3. Coordinate the change timing +4. Provide redirect mappings or alternative URLs + +### Validate before merging + +Make inbound link validation part of your review process: + +* Run validation locally before creating a PR +* Include validation in CI checks +* Review validation results before merging + +## Related concepts + +* [Outbound Crosslinks](outbound-crosslinks.md) - Links from your documentation to others +* [Link Index](link-index.md) - How your linkable resources are tracked +* [Link Service](link-service.md) - Where inbound link information is stored +* [Distributed Documentation](distributed-documentation.md) - The architecture enabling this validation diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index b1be46bf1..2591e3aa6 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -4,66 +4,51 @@ navigation_title: Building Blocks # Building Blocks -This section explains all the building blocks that are used to build the documentation. +This section explains the core concepts and building blocks that make up the docs-builder architecture. Understanding these concepts will help you work effectively with distributed documentation and cross-repository linking. -## Documentation Set +## Core concepts -A single folder containing the documentation of a single repository. At a minimum, this folder should contain: +### [Documentation Set](documentation-set.md) -* `docset.yml` file -* `index.md` file +The fundamental unit of documentation - a single folder containing the documentation for one repository. Each documentation set can be built, versioned, and maintained independently. -See [docset.yml](../configure/content-set/index.md) for more configuration details. +### [Assembled Documentation](assembled-documentation.md) -## Assembled Documentation +The product of combining multiple documentation sets into a unified documentation website with global navigation. This enables a seamless user experience across multiple repositories. -The product of building many documentation sets and weaving them in to a global navigation producing the fully assembled documentation site. +### [Distributed Documentation](distributed-documentation.md) -See [site configuration](../configure/site/index.md) for more details on the actual configuration. +The architectural approach that allows documentation sets to be built independently while maintaining link integrity across repositories. This enables teams to work autonomously without blocking each other. -## Distributed documentation +## Link management infrastructure -The purpose of separating building documentation sets and assembling them is to allow for distributed builds. +### [Link Service](link-service.md) -Each build of documentation set produces a `links.json` (Link Index) file that contains all the linkable resources in the repository. -This `links.json` file is then published to a central location (Link Service) everytime a repository successfully builds on its respective default integration branch. +The central S3-backed service where Link Index files are published and stored. This enables distributed validation and build resilience. -For example, [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) represents all linkable resources in the Elasticsearch repository. +### [Link Index](link-index.md) -This allows us to: +A JSON file (`links.json`) containing all linkable resources for a specific repository branch. Published to the Link Service after each successful build. -* Validate outbound and inbound links ahead of time, even during local `docs-builder` builds. -* Snapshot assembled 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. +### [Link Registry](link-registry.md) -## Link Service +A catalog file listing all available Link Index files across all repositories and branches. Used by the assembler to coordinate builds and by documentation builds for validation. -The central location where all the Link Index files are published. This is a simple S3 bucket fronted by CloudFront. +## Cross-repository linking -## Link Index +### [Outbound Crosslinks](outbound-crosslinks.md) -Each repository's branch will get in individual Link Index file in the `Link Serve` representing all linkable resources of that repository's branch. -See, for example: [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json). -This file is used to resolve [Outbound Crosslinks](#outbound-crosslinks) and [Inbound Crosslinks](#inbound-crosslinks). +Links from your documentation to other documentation sets. Validated against published Link Index files to ensure they're correct. -## Link Registry +### [Inbound Crosslinks](inbound-crosslinks.md) -A [single file](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json) that contains all the [Link Index files](#link-index) for all the repositories. -This is file is published everytime [Link Index](#link-index) files are published to the Link Service. The update is handled by an AWS Lambda function that listens to SQS triggers by S3 events. +Links from other documentation sets to yours. Validated to prevent breaking changes when you move or delete content. -## Outbound Crosslinks +## How it all works together -Outbound crosslinks are links from the documentation set that's being built to others. If both repositories publish to the same `Link Service`, they can link to each other using the `://` syntax. - -Read more about general link syntax in the [](../syntax/links.md) section. - -## Inbound Crosslinks - -Inbound crosslinks are links from other documentation sets to the one that's being built. - -If both repositories publish to the same `Link Service`, they can link to each other using the `://` syntax. - -Read more about general link syntax in the [](../syntax/links.md) section. - -Using our [Link Service](#link-service), we can validate if deletions or renames of files in the documentation set break other repositories ahead of time. +1. Each repository builds its documentation set independently +2. Successful builds publish a Link Index to the Link Service +3. The Link Registry catalogs all available Link Index files +4. Documentation builds validate crosslinks using these Link Index files +5. The assembler combines documentation sets using the Link Registry +6. Teams can work independently while maintaining link integrity across repositories diff --git a/docs/building-blocks/link-index.md b/docs/building-blocks/link-index.md new file mode 100644 index 000000000..51de5bc1e --- /dev/null +++ b/docs/building-blocks/link-index.md @@ -0,0 +1,86 @@ +--- +navigation_title: Link Index +--- + +# Link Index + +A **Link Index** is a JSON file (`links.json`) that contains all the linkable resources for a specific repository branch. + +## Purpose + +The Link Index enables: + +* **Cross-repository linking** - Other documentation sets can link to your content +* **Link validation** - Validate that links to your content are correct +* **Inbound link detection** - Know when other repositories link to your content +* **Distributed builds** - Build documentation independently while maintaining link integrity + +## Structure + +Each repository branch gets its own Link Index file in the [Link Service](link-service.md), organized by: + +* **Organization** - e.g., `elastic` +* **Repository** - e.g., `elasticsearch` +* **Branch** - e.g., `main`, `8.x`, `7.17` + +## Example + +View [Elasticsearch's main branch Link Index](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) to see a real example. + +The Link Index contains: + +* All documentation pages in the repository +* Headings within those pages +* Anchors and linkable elements +* Version information +* Metadata about the build + +## Generation + +The Link Index is automatically generated during a documentation build: + +1. `docs-builder` builds the documentation set +2. During the build, all linkable resources are tracked +3. After a successful build, a `links.json` file is written to `.artifacts/docs/html/links.json` +4. CI/CD publishes this file to the [Link Service](link-service.md) + +## Usage + +### Resolving outbound crosslinks + +When you use a crosslink like `elasticsearch://reference/api/search.md`, `docs-builder`: + +1. Fetches the Elasticsearch Link Index from the Link Service +2. Looks up the path in the index +3. Validates the link exists +4. Resolves it to the correct URL + +### Validating inbound crosslinks + +When building your documentation, `docs-builder` can: + +1. Fetch your repository's Link Index from previous builds +2. Compare with your current local changes +3. Detect if you've moved or deleted files that other repositories link to +4. Warn about breaking changes + +## File location + +During a build, the Link Index is written to: + +``` +.artifacts/docs/html/links.json +``` + +After publishing, it's available at: + +``` +https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/{org}/{repo}/{branch}/links.json +``` + +## Related concepts + +* [Link Service](link-service.md) - Where Link Index files are stored +* [Link Registry](link-registry.md) - Catalog of all Link Index files +* [Outbound Crosslinks](outbound-crosslinks.md) - Links that use the Link Index +* [Inbound Crosslinks](inbound-crosslinks.md) - Links to resources in the Link Index diff --git a/docs/building-blocks/link-registry.md b/docs/building-blocks/link-registry.md new file mode 100644 index 000000000..4461fe328 --- /dev/null +++ b/docs/building-blocks/link-registry.md @@ -0,0 +1,78 @@ +--- +navigation_title: Link Registry +--- + +# Link Registry + +The **Link Registry** is a single JSON file that serves as a catalog of all available [Link Index](link-index.md) files across all repositories. + +## Purpose + +The Link Registry provides: + +* **Discovery** - A single file to query for all available documentation across all repositories and branches +* **Efficiency** - Avoid scanning the entire [Link Service](link-service.md) to find available Link Index files +* **Assembler coordination** - The assembler uses this to determine which repositories and versions are available to build + +## Location + +The Link Registry is available at: + +``` +https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json +``` + +## Structure + +The Link Registry contains: + +* List of all organizations (e.g., `elastic`) +* Repositories within each organization (e.g., `elasticsearch`, `kibana`) +* Branches for each repository (e.g., `main`, `8.x`, `7.17`) +* Metadata about each Link Index: + * Last updated timestamp + * Commit SHA that produced the Link Index + * URL to the Link Index file + +## Maintenance + +The Link Registry is automatically maintained: + +1. A repository's CI/CD pipeline publishes a new `links.json` to the Link Service +2. The S3 bucket triggers an SQS message +3. An AWS Lambda function listens to these SQS messages +4. The Lambda function updates the Link Registry to include or update the entry for the new Link Index + +This process ensures the registry stays in sync with published Link Index files without manual intervention. + +## Usage + +### By the assembler + +When running `docs-builder assembler clone` or `docs-builder assembler build`: + +1. The assembler fetches the Link Registry +2. It determines which repositories and versions to clone/build based on the site configuration +3. It uses the commit SHAs from the registry to clone specific versions +4. It falls back to the last known good commit if a repository's current state has build failures + +### By documentation builds + +During a documentation build: + +1. `docs-builder` fetches the Link Registry +2. It determines which Link Index files to download for cross-repository validation +3. It validates all crosslinks against the appropriate Link Index files + +## Benefits + +* **Single source of truth** - One file to check for all available documentation +* **Performance** - Fast lookup without scanning the entire Link Service +* **Automation** - Maintained automatically via Lambda functions +* **Resilience** - Represents only successful builds with valid Link Indexes + +## Related concepts + +* [Link Service](link-service.md) - Where the Link Registry is stored +* [Link Index](link-index.md) - The files cataloged by the Link Registry +* [Assembled Documentation](assembled-documentation.md) - Uses the Link Registry to coordinate builds diff --git a/docs/building-blocks/link-service.md b/docs/building-blocks/link-service.md new file mode 100644 index 000000000..fbb7800ed --- /dev/null +++ b/docs/building-blocks/link-service.md @@ -0,0 +1,59 @@ +--- +navigation_title: Link Service +--- + +# Link Service + +The **Link Service** is the central location where all [Link Index](link-index.md) files are published and stored. + +## Architecture + +The Link Service is implemented as: + +* **Storage** - An S3 bucket containing all Link Index files +* **CDN** - CloudFront fronting the S3 bucket for fast global access +* **Access** - Publicly accessible for read operations + +## Purpose + +The Link Service enables: + +* **Distributed validation** - Any documentation build can validate cross-repository links without cloning all repositories +* **Link discovery** - Find what resources are available in other repositories +* **Build resilience** - Assembler builds can reference the last known good state of each repository +* **Decentralized publishing** - Each repository publishes its own Link Index independently + +## URL structure + +Link Index files are organized by repository and branch: + +``` +https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/{org}/{repo}/{branch}/links.json +``` + +For example: +* [Elasticsearch main branch](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) +* [Kibana main branch](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/kibana/main/links.json) + +## Publishing process + +When a documentation build completes successfully on a default integration branch: + +1. The build generates a `links.json` file +2. The CI/CD pipeline publishes the file to the Link Service +3. An AWS Lambda function triggers on the S3 event +4. The Lambda updates the [Link Registry](link-registry.md) to include the new Link Index + +## Access during builds + +During both local and CI builds, `docs-builder`: + +* Fetches relevant Link Index files from the Link Service +* Validates outbound crosslinks against these indexes +* Validates that inbound crosslinks won't be broken by local changes + +## Related concepts + +* [Link Index](link-index.md) - The files stored in the Link Service +* [Link Registry](link-registry.md) - The catalog of all Link Index files +* [Distributed Documentation](distributed-documentation.md) - Why the Link Service exists diff --git a/docs/building-blocks/outbound-crosslinks.md b/docs/building-blocks/outbound-crosslinks.md new file mode 100644 index 000000000..8d65f2579 --- /dev/null +++ b/docs/building-blocks/outbound-crosslinks.md @@ -0,0 +1,109 @@ +--- +navigation_title: Outbound Crosslinks +--- + +# Outbound Crosslinks + +**Outbound crosslinks** are links from your documentation set to other documentation sets in different repositories. + +## Purpose + +Outbound crosslinks allow you to: + +* Link to documentation in other repositories +* Maintain those links even as the target repository evolves +* Validate links during local builds +* Get warnings if target content is moved or deleted + +## Syntax + +If both repositories publish to the same [Link Service](link-service.md), they can link to each other using the crosslink syntax: + +```markdown +[Link text](repository-name://path/to/file.md) +``` + +For example: + +```markdown +See the [Search API documentation](elasticsearch://reference/api/search.md) +``` + +## How it works + +When `docs-builder` encounters a crosslink: + +1. **Parse** - Extracts the repository name and path from the link +2. **Fetch** - Downloads the target repository's [Link Index](link-index.md) from the Link Service +3. **Resolve** - Looks up the path in the Link Index to get the actual URL +4. **Validate** - Verifies the link exists and generates a warning if not +5. **Transform** - Replaces the crosslink with the resolved URL in the output + +## Validation + +During a build, `docs-builder`: + +* **Validates immediately** - Checks all outbound crosslinks against published Link Index files +* **Reports errors** - Warns about broken links before you publish +* **Suggests fixes** - If a file was moved, the Link Index may include redirect information + +### Local validation + +Even during local development, you can validate outbound crosslinks: + +```bash +docs-builder --path ./docs +``` + +This will: +* Fetch Link Index files from the Link Service +* Validate all crosslinks in your local documentation +* Report any broken links + +## Configuration + +To enable crosslinks to a repository, add it to your `docset.yml`: + +```yaml +cross_links: + - elasticsearch + - kibana + - fleet +``` + +## Best practices + +### Link to files, not URLs + +**Good:** +```markdown +[Search API](elasticsearch://reference/api/search.md) +``` + +**Bad:** +```markdown +[Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html) +``` + +The crosslink syntax is resilient to: +* URL structure changes +* File moves (if redirects are configured) +* Version differences + +### Link to headings + +You can link to specific headings within a page: + +```markdown +[Query DSL](elasticsearch://reference/query-dsl.md#match-query) +``` + +### Specify versions + +For assembled documentation, the assembler handles version mapping. For local builds, crosslinks resolve to the default branch of the target repository. + +## Related concepts + +* [Inbound Crosslinks](inbound-crosslinks.md) - Links from other repositories to yours +* [Link Index](link-index.md) - How crosslinks are resolved +* [Links syntax](../syntax/links.md) - Complete link syntax documentation From 7887ee2d2840418c2b4de263fb9376d11873550c Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 10:50:10 +0200 Subject: [PATCH 10/86] Expanded building blocks --- docs/_docset.yml | 2 +- .../assembled-documentation.md | 34 +++++++------- .../distributed-documentation.md | 6 +-- docs/building-blocks/inbound-crosslinks.md | 25 ++++------ docs/building-blocks/index.md | 6 +-- .../{link-registry.md => link-catalog.md} | 30 ++++++------ docs/building-blocks/link-index.md | 2 +- docs/building-blocks/link-service.md | 4 +- docs/building-blocks/outbound-crosslinks.md | 46 +++++++++---------- 9 files changed, 71 insertions(+), 84 deletions(-) rename docs/building-blocks/{link-registry.md => link-catalog.md} (70%) diff --git a/docs/_docset.yml b/docs/_docset.yml index 2e20447fa..436f5dade 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -54,7 +54,7 @@ toc: - file: distributed-documentation.md - file: link-service.md - file: link-index.md - - file: link-registry.md + - file: link-catalog.md - file: outbound-crosslinks.md - file: inbound-crosslinks.md - folder: configure diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md index 8505653cf..33020aaa1 100644 --- a/docs/building-blocks/assembled-documentation.md +++ b/docs/building-blocks/assembled-documentation.md @@ -11,40 +11,40 @@ navigation_title: Assembled Documentation The assembler: 1. Clones multiple documentation repositories -2. Builds each documentation set independently -3. Combines them according to a global navigation configuration +2. Reads its [configuration files](../configure/site/index.md) and builds [a global navigation](../configure/site/navigation.md) +3. Builds each documentation set independently using the global configuration and navigation to inform path prefixes 4. Produces a unified documentation website -## Benefits - -By assembling multiple documentation sets together, you can: - -* **Centralize navigation** - Present a unified experience across multiple repositories -* **Cross-link content** - Link between different documentation sets seamlessly -* **Version coordination** - Control which versions of different repositories appear together -* **Product-level organization** - Organize documentation by product rather than repository - ## Configuration Assembled documentation is configured through the site configuration, which defines: -* Which repositories to include -* What versions of each repository to build -* How to organize the global navigation -* URL structure and routing +* [assembler.yml](../configure/site/index.md) Which repositories to include and [their branching strategy](../contribute/branching-strategy.md) +* [navigation.yml](../configure/site/index.md) Navigation and url prefixes for TOC's. +* [versions.yml](../configure/site/versions.md) Defines the various versioning schemes of products/solutions being documented +* [products.yml](../configure/site/products.md) Defines the product catalog (id, name) and ties it to a specific versioning scheme See [Site Configuration](../configure/site/index.md) for complete details on configuring assembled documentation. +Important to note that `docs-builder` makes no assumptions about how repositories, products, solutions and versions tie into each other. + ## Build process The typical build process for assembled documentation: 1. **Clone** - Clone all configured repositories using `docs-builder assembler clone` 2. **Build** - Build all documentation sets using `docs-builder assembler build` -3. **Export** - Export the assembled site in various formats (HTML, Elasticsearch index, etc.) +3. **Serve** - Serve the documentation on http://localhost:4000 using `docs-builder assembler serve` + +This uses the embedded configuration files inside the `docs-builder` binary. To build a specific configuration: + +1. **Init Config** - Fetch the latest config to `$(pwd)/config` `docs-builder assembler config init --local` +2. **Clone** - Clone all configured repositories using `docs-builder assembler clone --local` +3. **Build** - Build all documentation sets using `docs-builder assembler build --local` +4. **Serve** - Serve the documentation on http://localhost:4000 using `docs-builder assembler serve` ## Related concepts * [Documentation Set](documentation-set.md) - The individual units being assembled * [Distributed Documentation](distributed-documentation.md) - How documentation sets work independently -* [Link Registry](link-registry.md) - How the assembler knows what to include +* [Link Catalog](link-catalog.md) - How the assembler knows what to include diff --git a/docs/building-blocks/distributed-documentation.md b/docs/building-blocks/distributed-documentation.md index b0a65d4fc..8258e004f 100644 --- a/docs/building-blocks/distributed-documentation.md +++ b/docs/building-blocks/distributed-documentation.md @@ -4,7 +4,7 @@ navigation_title: Distributed Documentation # Distributed Documentation -**Distributed documentation** is the architectural approach that allows documentation sets to be built independently while still enabling cross-repository linking and validation. +**Distributed documentation** is the architectural approach that allows repositories to build their own documentation independently. ## Purpose @@ -54,10 +54,10 @@ The distributed documentation system relies on several key components: * [Link Index](link-index.md) - Per-repository file of linkable resources * [Link Service](link-service.md) - Central storage for Link Index files -* [Link Registry](link-registry.md) - Catalog of all available Link Index files +* [Link Catalog](link-catalog.md) - Catalog of all available Link Index files * [Outbound Crosslinks](outbound-crosslinks.md) - Links from one repository to another * [Inbound Crosslinks](inbound-crosslinks.md) - Links from other repositories to yours ## Local development -Even during local development, `docs-builder` can access the Link Service to validate cross-repository links without requiring you to clone and build all related repositories. +Even during local development, `docs-builder` can access the [Link Service](link-service.md) to validate cross-repository links without requiring you to clone and build all related repositories. diff --git a/docs/building-blocks/inbound-crosslinks.md b/docs/building-blocks/inbound-crosslinks.md index 9a7fe42ff..e661c7f65 100644 --- a/docs/building-blocks/inbound-crosslinks.md +++ b/docs/building-blocks/inbound-crosslinks.md @@ -16,19 +16,18 @@ Inbound crosslink validation allows you to: ## How it works -When you build your documentation, `docs-builder` can validate inbound crosslinks by: +A regular [build](../cli/docset/build.md) of a documentation set won't validate inbound links automatically. -1. **Fetching your published Link Index** - Gets your repository's [Link Index](link-index.md) from the [Link Service](link-service.md) -2. **Comparing with local changes** - Compares your current local state with the published Link Index -3. **Detecting differences** - Identifies files that have been moved, renamed, or deleted -4. **Checking references** - Queries the Link Service to see if other repositories link to the changed files -5. **Reporting warnings** - Alerts you to potential breaking changes +You have to use the [inbound-links validate-link-reference](../cli/links/inbound-links-validate-link-reference.md) after a build to validate all inbound links. + +The reason for this is that validating all inbound links has to download all published [Link Index](link-index.md) files +for the current [Content Source](../configure/content-sources.md). ## Validation commands ### Validate all inbound links -Check all inbound crosslinks for your repository: +Check all inbound links for all published [Link Index](link-index.md) files declared in the [Link Catalog](link-catalog.md) ```bash docs-builder inbound-links validate-all @@ -39,6 +38,7 @@ docs-builder inbound-links validate-all Validate a locally built `links.json` against all published Link Index files: ```bash +docs-builder inbound-links validate-link-reference docs-builder inbound-links validate-link-reference --file .artifacts/docs/html/links.json ``` @@ -80,16 +80,7 @@ Heading anchors are part of the Link Index. If other repositories link to specif ## Integration with CI/CD -You can integrate inbound link validation into your CI/CD pipeline: - -```yaml -- name: Validate inbound links - run: | - docs-builder inbound-links validate-link-reference \ - --file .artifacts/docs/html/links.json -``` - -This will fail the build if you're about to break links from other repositories. +Our preview CI job will run inbound link validation automatically. ## Best practices diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index 2591e3aa6..49e6cab38 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -30,7 +30,7 @@ The central S3-backed service where Link Index files are published and stored. T A JSON file (`links.json`) containing all linkable resources for a specific repository branch. Published to the Link Service after each successful build. -### [Link Registry](link-registry.md) +### [Link Catalog](link-catalog.md) A catalog file listing all available Link Index files across all repositories and branches. Used by the assembler to coordinate builds and by documentation builds for validation. @@ -48,7 +48,7 @@ Links from other documentation sets to yours. Validated to prevent breaking chan 1. Each repository builds its documentation set independently 2. Successful builds publish a Link Index to the Link Service -3. The Link Registry catalogs all available Link Index files +3. The Link Catalog catalogs all available Link Index files 4. Documentation builds validate crosslinks using these Link Index files -5. The assembler combines documentation sets using the Link Registry +5. The assembler combines documentation sets using the Link Catalog 6. Teams can work independently while maintaining link integrity across repositories diff --git a/docs/building-blocks/link-registry.md b/docs/building-blocks/link-catalog.md similarity index 70% rename from docs/building-blocks/link-registry.md rename to docs/building-blocks/link-catalog.md index 4461fe328..866a5bbb6 100644 --- a/docs/building-blocks/link-registry.md +++ b/docs/building-blocks/link-catalog.md @@ -1,14 +1,14 @@ --- -navigation_title: Link Registry +navigation_title: Link Catalog --- -# Link Registry +# Link Catalog -The **Link Registry** is a single JSON file that serves as a catalog of all available [Link Index](link-index.md) files across all repositories. +The **Link Catalog** is a single JSON file that serves as a catalog of all available [Link Index](link-index.md) files across all repositories. ## Purpose -The Link Registry provides: +The Link Catalog provides: * **Discovery** - A single file to query for all available documentation across all repositories and branches * **Efficiency** - Avoid scanning the entire [Link Service](link-service.md) to find available Link Index files @@ -16,7 +16,7 @@ The Link Registry provides: ## Location -The Link Registry is available at: +The Link Catalog is available at: ``` https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json @@ -24,7 +24,7 @@ https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json ## Structure -The Link Registry contains: +The Link Catalog contains: * List of all organizations (e.g., `elastic`) * Repositories within each organization (e.g., `elasticsearch`, `kibana`) @@ -36,14 +36,14 @@ The Link Registry contains: ## Maintenance -The Link Registry is automatically maintained: +The Link Catalog is automatically maintained: 1. A repository's CI/CD pipeline publishes a new `links.json` to the Link Service 2. The S3 bucket triggers an SQS message 3. An AWS Lambda function listens to these SQS messages -4. The Lambda function updates the Link Registry to include or update the entry for the new Link Index +4. The Lambda function updates the Link Catalog to include or update the entry for the new Link Index -This process ensures the registry stays in sync with published Link Index files without manual intervention. +This process ensures the catalog stays in sync with published Link Index files without manual intervention. ## Usage @@ -51,16 +51,16 @@ This process ensures the registry stays in sync with published Link Index files When running `docs-builder assembler clone` or `docs-builder assembler build`: -1. The assembler fetches the Link Registry +1. The assembler fetches the Link Catalog 2. It determines which repositories and versions to clone/build based on the site configuration -3. It uses the commit SHAs from the registry to clone specific versions +3. It uses the commit SHAs from the catalog to clone specific versions 4. It falls back to the last known good commit if a repository's current state has build failures ### By documentation builds During a documentation build: -1. `docs-builder` fetches the Link Registry +1. `docs-builder` fetches the Link Catalog 2. It determines which Link Index files to download for cross-repository validation 3. It validates all crosslinks against the appropriate Link Index files @@ -73,6 +73,6 @@ During a documentation build: ## Related concepts -* [Link Service](link-service.md) - Where the Link Registry is stored -* [Link Index](link-index.md) - The files cataloged by the Link Registry -* [Assembled Documentation](assembled-documentation.md) - Uses the Link Registry to coordinate builds +* [Link Service](link-service.md) - Where the Link Catalog is stored +* [Link Index](link-index.md) - The files cataloged by the Link Catalog +* [Assembled Documentation](assembled-documentation.md) - Uses the Link Catalog to coordinate builds diff --git a/docs/building-blocks/link-index.md b/docs/building-blocks/link-index.md index 51de5bc1e..b12bad7da 100644 --- a/docs/building-blocks/link-index.md +++ b/docs/building-blocks/link-index.md @@ -81,6 +81,6 @@ https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/{org}/{repo}/{branch} ## Related concepts * [Link Service](link-service.md) - Where Link Index files are stored -* [Link Registry](link-registry.md) - Catalog of all Link Index files +* [Link Catalog](link-catalog.md) - Catalog of all Link Index files * [Outbound Crosslinks](outbound-crosslinks.md) - Links that use the Link Index * [Inbound Crosslinks](inbound-crosslinks.md) - Links to resources in the Link Index diff --git a/docs/building-blocks/link-service.md b/docs/building-blocks/link-service.md index fbb7800ed..b3129cc43 100644 --- a/docs/building-blocks/link-service.md +++ b/docs/building-blocks/link-service.md @@ -42,7 +42,7 @@ When a documentation build completes successfully on a default integration branc 1. The build generates a `links.json` file 2. The CI/CD pipeline publishes the file to the Link Service 3. An AWS Lambda function triggers on the S3 event -4. The Lambda updates the [Link Registry](link-registry.md) to include the new Link Index +4. The Lambda updates the [Link Catalog](link-catalog.md) to include the new Link Index ## Access during builds @@ -55,5 +55,5 @@ During both local and CI builds, `docs-builder`: ## Related concepts * [Link Index](link-index.md) - The files stored in the Link Service -* [Link Registry](link-registry.md) - The catalog of all Link Index files +* [Link Catalog](link-catalog.md) - The catalog of all Link Index files * [Distributed Documentation](distributed-documentation.md) - Why the Link Service exists diff --git a/docs/building-blocks/outbound-crosslinks.md b/docs/building-blocks/outbound-crosslinks.md index 8d65f2579..0fb913880 100644 --- a/docs/building-blocks/outbound-crosslinks.md +++ b/docs/building-blocks/outbound-crosslinks.md @@ -31,38 +31,31 @@ See the [Search API documentation](elasticsearch://reference/api/search.md) ## How it works +You have to explicitly opt in to another repository's `Link Index` by adding it to your `docset.yml` file: + +```yaml +cross_links: + - docs-content +``` + + When `docs-builder` encounters a crosslink: 1. **Parse** - Extracts the repository name and path from the link -2. **Fetch** - Downloads the target repository's [Link Index](link-index.md) from the Link Service -3. **Resolve** - Looks up the path in the Link Index to get the actual URL -4. **Validate** - Verifies the link exists and generates a warning if not -5. **Transform** - Replaces the crosslink with the resolved URL in the output +3. **Resolve** - Looks up the path in the locally cached [Link Index](link-index.md) to get the actual URL +4. **Validate** - Verifies the link exists and generates an error if not +5. **Transform** - Replaces the crosslink with the fully resolved URL in the output ## Validation During a build, `docs-builder`: -* **Validates immediately** - Checks all outbound crosslinks against published Link Index files -* **Reports errors** - Warns about broken links before you publish -* **Suggests fixes** - If a file was moved, the Link Index may include redirect information - -### Local validation - -Even during local development, you can validate outbound crosslinks: - -```bash -docs-builder --path ./docs -``` - -This will: -* Fetch Link Index files from the Link Service -* Validate all crosslinks in your local documentation -* Report any broken links +* **Validates immediately** - Checks all outbound cross-links against locally fetched [Link Index](link-index.md) files +* **Reports errors** - Reports errors about broken links before you publish ## Configuration -To enable crosslinks to a repository, add it to your `docset.yml`: +To enable cross-links to a repository, add it to your `docset.yml`: ```yaml cross_links: @@ -71,6 +64,13 @@ cross_links: - fleet ``` +This instructs `docs-builder` to fetch the `Link Index` from the [Link Service](link-service.md) during the build process which are then cached locally. +`docs-builder` will validate locally cached `Link Index` files against the remote `Link Index` files on each build fetching updates as needed. + +Now you can create crosslinks e.g `elasticsearch://path/to/file.md` + +The explicit opt-in prevents each repository build having the fetch all the links for all the repositories in the [`Link Catalog`](link-catalog.md) of which there may be many. + ## Best practices ### Link to files, not URLs @@ -98,10 +98,6 @@ You can link to specific headings within a page: [Query DSL](elasticsearch://reference/query-dsl.md#match-query) ``` -### Specify versions - -For assembled documentation, the assembler handles version mapping. For local builds, crosslinks resolve to the default branch of the target repository. - ## Related concepts * [Inbound Crosslinks](inbound-crosslinks.md) - Links from other repositories to yours From 6d7f430450c25dedf852a6a5f45ddbae189d0ebd Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 12:08:23 +0200 Subject: [PATCH 11/86] update building blocks --- docs/building-blocks/index.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index 49e6cab38..a4bdaab89 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -44,6 +44,25 @@ Links from your documentation to other documentation sets. Validated against pub Links from other documentation sets to yours. Validated to prevent breaking changes when you move or delete content. +## Navigation + +### Documentation Set Navigation + +A documentation set is responsible for defining how files are organized in the navigation. This is done by defining a `toc` section in the `docset.yml` file. +If the `toc` section becomes to big folders can define a dedicated `toc.yml` file to organize the files and link them in their parent `toc.yml` or `docset.yml` file. + +Read more details in the reference for [docset.yml](../configure/content-set/index.md) + +### Global Navigation + +The global navigation is defined in the [`navigation.yml`](../configure/site/navigation.md) file. +This navigation only concerns itself with `toc` sections defined in either `docset.yml` or `toc.yml` files. +These `toc` sections can be reorganized independently of their position in the documentation set navigation. + +Dangling `toc` sections are **not** allowed and the assembler build will report an error if it finds any. All `toc` sections must be linked in `navigation.yml`. + +Read more details in the reference for [navigation.yml](../configure/site/navigation.md) + ## How it all works together 1. Each repository builds its documentation set independently From 9a9f20b2d377b62faaa9da0ff82b641574cbfa93 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 12:34:14 +0200 Subject: [PATCH 12/86] update building blocks --- docs/building-blocks/index.md | 72 ++++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index a4bdaab89..983c000f3 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -49,17 +49,79 @@ Links from other documentation sets to yours. Validated to prevent breaking chan ### Documentation Set Navigation A documentation set is responsible for defining how files are organized in the navigation. This is done by defining a `toc` section in the `docset.yml` file. -If the `toc` section becomes to big folders can define a dedicated `toc.yml` file to organize the files and link them in their parent `toc.yml` or `docset.yml` file. + +```yaml +toc: + - file: index.md + - folder: contribute + children: + - file: index.md + - file: locally.md + children: + - file: page.md +``` + +If the `toc` section becomes too unwieldy folders can define a dedicated `toc.yml` file to organize their files and link them in their parent `toc.yml` or `docset.yml` file. + +```yaml +toc: + - file: index.md + - folder: contribute + children: + - file: index.md + - file: locally.md + children: + - file: page.md + - toc: development +``` + +Where `development/toc.yml` is defined as: + +```yaml +toc: + - file: index.md + - toc: link-validation +``` + +:::{note} +The folder name `development` is not repeated in the `toc.yml` file this allows for easier renames of the folder itself. +::: Read more details in the reference for [docset.yml](../configure/content-set/index.md) ### Global Navigation -The global navigation is defined in the [`navigation.yml`](../configure/site/navigation.md) file. -This navigation only concerns itself with `toc` sections defined in either `docset.yml` or `toc.yml` files. -These `toc` sections can be reorganized independently of their position in the documentation set navigation. +The global navigation is defined in the [`navigation.yml`](../configure/site/navigation.md) file. It follows a very similar +`toc` configuration structure to the documentation set navigation. + +It comes, however, with the following restrictions: + +* It may only link to `toc.yml` or `docset.yml` files + +```yaml +toc: + - toc: get-started + - toc: elasticsearch-net:// + - toc: extend + children: + - toc: kibana://extend + path_prefix: extend/kibana + - toc: logstash://extend + path_prefix: extend/logstash + - toc: beats://extend +``` + +Some syntactic notes: + +* The toc uses a similar [cross-link syntax to links](../syntax/links.md) +* The `./docset.yml` or `/toc.yml` suffix is implied, assembler will find the correct file for you. +* The narrative repository `elastic/docs-content` is 'special' so omitting `scheme://` implies `docs-content://`. + +These `toc` sections can be reorganized independently of their position in their origin documentation set navigation. +This allows sections from different repositories to be grouped together in the global navigation. -Dangling `toc` sections are **not** allowed and the assembler build will report an error if it finds any. All `toc` sections must be linked in `navigation.yml`. +All `toc` sections must be linked in `navigation.yml`. +Dangling `toc` sections are **not** allowed and the assembler build will report an error if it finds any. Read more details in the reference for [navigation.yml](../configure/site/navigation.md) From 0c617c5f222aee94c84954a2eb8c6a459c2dab60 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 12:52:18 +0200 Subject: [PATCH 13/86] Include navigation building blocks --- docs/_docset.yml | 2 + .../documentation-set-navigation.md | 236 ++++++++++++++++++ docs/building-blocks/global-navigation.md | 193 ++++++++++++++ docs/building-blocks/index.md | 85 +------ 4 files changed, 438 insertions(+), 78 deletions(-) create mode 100644 docs/building-blocks/documentation-set-navigation.md create mode 100644 docs/building-blocks/global-navigation.md diff --git a/docs/_docset.yml b/docs/_docset.yml index 436f5dade..e2bd86d51 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -57,6 +57,8 @@ toc: - file: link-catalog.md - file: outbound-crosslinks.md - file: inbound-crosslinks.md + - file: documentation-set-navigation.md + - file: global-navigation.md - folder: configure children: - file: index.md diff --git a/docs/building-blocks/documentation-set-navigation.md b/docs/building-blocks/documentation-set-navigation.md new file mode 100644 index 000000000..3adf88b50 --- /dev/null +++ b/docs/building-blocks/documentation-set-navigation.md @@ -0,0 +1,236 @@ +--- +navigation_title: Documentation Set Navigation +--- + +# Documentation Set Navigation + +**Documentation set navigation** defines how files within a single documentation set are organized and structured. Each documentation set is responsible for its own internal navigation hierarchy. + +## Purpose + +Documentation set navigation allows repository maintainers to: + +* **Organize content** - Define the logical structure of their documentation +* **Control hierarchy** - Determine which pages are nested under others +* **Create sections** - Group related content together +* **Maintain autonomy** - Structure documentation independently of other repositories + +## Basic structure + +Navigation is defined in the `toc` (table of contents) section of the `docset.yml` file: + +```yaml +toc: + - file: index.md + - folder: contribute + children: + - file: index.md + - file: locally.md + children: + - file: page.md +``` + +## TOC node types + +The `toc` section supports several node types: + +### File nodes + +Reference a single markdown file: + +```yaml +- file: getting-started.md +``` + +Files can also have nested children: + +```yaml +- file: locally.md + children: + - file: page.md +``` + +### Folder nodes + +Group related files together: + +```yaml +- folder: configuration + children: + - file: index.md + - file: basic.md +``` + +`children` is optional for `folder` nodes. This will include all files in the folder. +This is especially useful during development when you are unsure how to structure your documentation. + +Once `children` is defined, it must reference all `.md` files in the folder. The build will fail if +it detects any dangling documentation files. + +### Hidden files + +Hide pages from navigation while keeping them accessible: + +```yaml +- hidden: deprecated-page.md +``` + +### Named TOC sections + +For larger documentation sets, create named TOC sections that can be referenced in [global navigation](global-navigation.md): + +```yaml +toc: + - file: index.md + - toc: development +``` + +This will include the `toc` section defined in `development/toc.yml`:` + +## Dedicated toc.yml files + +When a `toc` section becomes too unwieldy, folders can define a dedicated `toc.yml` file to organize their files and link them in their parent `toc.yml` or `docset.yml` file. + +### Example with nested TOC + +In your `docset.yml`: + +```yaml +toc: + - file: index.md + - folder: contribute + children: + - file: index.md + - file: locally.md + children: + - file: page.md + - toc: development +``` + +Then create `development/toc.yml`: + +```yaml +toc: + - file: index.md + - toc: link-validation +``` + +:::{note} +The folder name `development` is not repeated in the `toc.yml` file. This allows for easier renames of the folder itself. +::: + +### Benefits of separate toc.yml files + +* **Modularity** - Each section can be maintained independently +* **Cleaner docset.yml** - Keep the main file focused and readable +* **Easier refactoring** - Rename folders without updating TOC references +* **Team ownership** - Different teams can manage different TOC sections + +## File paths + +All file paths in the `toc` section are relative to the documentation set root (where `docset.yml` is located): + +```yaml +toc: + - file: index.md # docs/index.md + - folder: api + children: + - file: index.md # docs/api/index.md + - file: authentication.md # docs/api/authentication.md +``` + +## Navigation metadata + +You can customize how items appear in the navigation: + +### Custom titles + +The navigation title defaults to a markdown's page first `h1` heading. + +To present the file differently in the navigation, add a `navigation_title` metadata field. + +```markdown +--- +title: Getting Started with the Documentation Builder +navigation_title: Quick Start +--- +``` + +There is no way to set `title` in the `docset.yml` file. This is by design to keep a page's data +contained in its file. + +## Relationship to global navigation + +When building [assembled documentation](assembled-documentation.md), the documentation set navigation becomes a component of the [global navigation](global-navigation.md): + +* **Documentation set navigation** defines the structure **within** a repository +* **Global navigation** defines **how repositories are organized** relative to each other + +Named `toc` sections in `docset.yml` can be referenced and reorganized in the global `navigation.yml` file without affecting the documentation set's internal structure. + +## Best practices + +### Keep it organized + +* Group related content in folders +* Use descriptive folder and file names +* Maintain a logical hierarchy + +The folder names and hierarchy are reflected directly in the URL structure. + +### Use index files + +Always include an `index.md` in folders: + +```yaml +- folder: api + children: + - file: index.md # Overview of API documentation + - file: endpoints.md + - file: authentication.md +``` + +### Limit nesting depth + +Avoid deeply nested structures (more than three to four levels) to maintain navigation clarity. + +### Use toc.yml for large sections + +When a section contains many files or becomes complex, extract it to a dedicated `toc.yml`: + +``` +docs/ +├── docset.yml +├── index.md +└── development/ + ├── toc.yml # Define development section structure here + ├── index.md + └── link-validation/ + └── toc.yml # Nested TOC section +``` + +### Name TOC sections meaningfully + +Use clear, descriptive names for TOC sections: + +**Good:** +```yaml +- toc: api-reference +- toc: getting-started +- toc: troubleshooting +``` + +**Bad:** +```yaml +- toc: section1 +- toc: misc +- toc: other +``` + +These names will end up in the URL structure of the published documentation + +## Related concepts + +* [Global Navigation](global-navigation.md) - How documentation sets are organized in assembled documentation +* [Content Set Configuration](../configure/content-set/index.md) - Complete `docset.yml` reference +* [Navigation Configuration](../configure/content-set/navigation.md) - Detailed navigation options diff --git a/docs/building-blocks/global-navigation.md b/docs/building-blocks/global-navigation.md new file mode 100644 index 000000000..223bd0ffb --- /dev/null +++ b/docs/building-blocks/global-navigation.md @@ -0,0 +1,193 @@ +--- +navigation_title: Global Navigation +--- + +# Global Navigation + +**Global navigation** defines how multiple documentation sets are organized and presented together in [assembled documentation](assembled-documentation.md). It creates a unified navigation structure across all repositories. + +## Purpose + +Global navigation enables: + +* **Unified experience** - Present documentation from multiple repositories as a cohesive whole +* **Flexible organization** - Arrange documentation by product, feature, or audience rather than by repository +* **Independent evolution** - Reorganize global structure without changing documentation sets +* **Cross-repository grouping** - Combine related content from different repositories + +## Configuration + +Global navigation is defined in the `navigation.yml` file, which is part of the [site configuration](../configure/site/index.md). It follows a very similar `toc` configuration structure to [documentation set navigation](documentation-set-navigation.md). + +## Key differences from documentation set navigation + +Global navigation has specific restrictions: + +* **It may only link to `toc.yml` or `docset.yml` files** - You cannot reference individual markdown files +* **Uses crosslink syntax** - References to other repositories use the `repository://` syntax +* **Requires all TOC sections** - Dangling TOC sections are not allowed + +## Basic structure + +```yaml +toc: + - toc: get-started + - toc: elasticsearch-net:// + - toc: extend + children: + - toc: kibana://extend + path_prefix: extend/kibana + - toc: logstash://extend + path_prefix: extend/logstash + - toc: beats://extend +``` + +## Syntax notes + +### Crosslink syntax + +The TOC uses a similar [cross-link syntax to links](../syntax/links.md): + +```yaml +- toc: elasticsearch-net:// # References entire repository +- toc: kibana://extend # References 'extend' TOC section from kibana +``` + +### Implied suffixes + +The `./docset.yml` or `/toc.yml` suffix is implied - the assembler will find the correct file for you: + +### Special repository handling + +The narrative repository `elastic/docs-content` is 'special', so omitting `scheme://` implies `docs-content://`: + +```yaml +- toc: get-started # Implies docs-content://get-started +- toc: elasticsearch://setup # Explicitly from elasticsearch repository +``` + +## Path prefixes + +You must explicitly provide a URL path prefix when including a `toc`. + +```yaml +- toc: extend + children: + - toc: kibana://extend + path_prefix: extend/kibana # Override default path + - toc: logstash://extend + path_prefix: extend/logstash + - toc: beats://extend + path_prefix: extend/beats +``` + +This allows you to: +* Group content from different repositories under a common path +* Avoid URL conflicts when combining repositories +* Create product-specific URL structures + +## Reorganization independence + +These `toc` sections can be reorganized independently of their position in their origin documentation set navigation. This allows sections from different repositories to be grouped together in the global navigation. + +### Example: Cross-repository organization + +You can create a unified section that combines content from multiple repositories: + +```yaml +toc: + - toc: monitoring + children: + - toc: elasticsearch://monitoring + path_prefix: monitoring/elasticsearch + - toc: kibana://monitoring + path_prefix: monitoring/kibana + - toc: beats://monitoring + path_prefix: monitoring/beats +``` + +Even though each repository defines its own `monitoring` section, the global navigation presents them as a cohesive monitoring guide. + +## Dangling TOC sections + +All `toc` sections must be linked in `navigation.yml`. + +**Dangling `toc` sections are not allowed** and the assembler build will report an error if it finds any. + +This ensures: +* No content is accidentally excluded from the site +* Navigation references are always valid +* Documentation coverage is complete +* Every TOC section defined in a `docset.yml` appears somewhere in the global navigation + +### Example of validation + +If a repository defines: + +```yaml +# my-repo/docs/docset.yml +toc: + - file: index.md + - toc: getting-started + - toc: advanced +``` + +Then `navigation.yml` must reference both `getting-started` and `advanced`: + +```yaml +# navigation.yml +toc: + - toc: my-repo://getting-started + - toc: my-repo://advanced +``` + +If either is missing, the build will fail with an error about dangling TOC sections. + +## Validation + +When building assembled documentation, `docs-builder` validates: + +* All referenced TOC sections exist +* No TOC sections are dangling (unreferenced) +* Path prefixes don't conflict +* Crosslink references resolve correctly + +Validation errors will cause the assembler build to fail. + +## Navigation metadata + +You can customize how sections appear in global navigation: + +### Nested organization + +Create nested navigation structures: + +```yaml +toc: + - toc: getting-started + children: + - toc: elasticsearch://quickstart + - toc: kibana://quickstart + - toc: reference + children: + - toc: elasticsearch://apis + - toc: elasticsearch://settings +``` + +## Build process integration + +During an assembler build: + +1. `docs-builder` reads `navigation.yml` +2. It resolves all TOC section references across repositories +3. It validates that all sections are accounted for (no dangling sections) +4. It builds each documentation set with knowledge of its global path prefix +5. It generates the final site with unified navigation + +## Related concepts + +* [Documentation Set Navigation](documentation-set-navigation.md) - How individual repositories organize their content +* [Assembled Documentation](assembled-documentation.md) - The build process that uses global navigation +* [Site Configuration](../configure/site/index.md) - Complete site configuration reference +* [Navigation Configuration](../configure/site/navigation.md) - Detailed navigation.yml reference +* [Cross-link syntax](../syntax/links.md) - Understanding the repository:// syntax diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index 983c000f3..f571ad0f2 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -46,84 +46,13 @@ Links from other documentation sets to yours. Validated to prevent breaking chan ## Navigation -### Documentation Set Navigation - -A documentation set is responsible for defining how files are organized in the navigation. This is done by defining a `toc` section in the `docset.yml` file. - -```yaml -toc: - - file: index.md - - folder: contribute - children: - - file: index.md - - file: locally.md - children: - - file: page.md -``` - -If the `toc` section becomes too unwieldy folders can define a dedicated `toc.yml` file to organize their files and link them in their parent `toc.yml` or `docset.yml` file. - -```yaml -toc: - - file: index.md - - folder: contribute - children: - - file: index.md - - file: locally.md - children: - - file: page.md - - toc: development -``` - -Where `development/toc.yml` is defined as: - -```yaml -toc: - - file: index.md - - toc: link-validation -``` - -:::{note} -The folder name `development` is not repeated in the `toc.yml` file this allows for easier renames of the folder itself. -::: - -Read more details in the reference for [docset.yml](../configure/content-set/index.md) - -### Global Navigation - -The global navigation is defined in the [`navigation.yml`](../configure/site/navigation.md) file. It follows a very similar -`toc` configuration structure to the documentation set navigation. - -It comes, however, with the following restrictions: - -* It may only link to `toc.yml` or `docset.yml` files - -```yaml -toc: - - toc: get-started - - toc: elasticsearch-net:// - - toc: extend - children: - - toc: kibana://extend - path_prefix: extend/kibana - - toc: logstash://extend - path_prefix: extend/logstash - - toc: beats://extend -``` - -Some syntactic notes: - -* The toc uses a similar [cross-link syntax to links](../syntax/links.md) -* The `./docset.yml` or `/toc.yml` suffix is implied, assembler will find the correct file for you. -* The narrative repository `elastic/docs-content` is 'special' so omitting `scheme://` implies `docs-content://`. - -These `toc` sections can be reorganized independently of their position in their origin documentation set navigation. -This allows sections from different repositories to be grouped together in the global navigation. - -All `toc` sections must be linked in `navigation.yml`. -Dangling `toc` sections are **not** allowed and the assembler build will report an error if it finds any. - -Read more details in the reference for [navigation.yml](../configure/site/navigation.md) +### [Documentation Set Navigation](documentation-set-navigation.md) + +How individual documentation sets organize their content through TOC sections in `docset.yml` and `toc.yml` files. Each repository controls its own internal navigation structure, including file and folder organization. + +### [Global Navigation](global-navigation.md) + +How multiple documentation sets are organized together in assembled documentation through `navigation.yml`. Uses crosslink syntax to reference TOC sections from different repositories and enables cross-repository content organization. ## How it all works together From e593ff0f394f0f4ce63da2c961379d86f7dc17ef Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 13:02:35 +0200 Subject: [PATCH 14/86] Small touchups --- docs/building-blocks/link-catalog.md | 6 +++--- docs/building-blocks/link-service.md | 11 +++++++++-- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/building-blocks/link-catalog.md b/docs/building-blocks/link-catalog.md index 866a5bbb6..a8705be16 100644 --- a/docs/building-blocks/link-catalog.md +++ b/docs/building-blocks/link-catalog.md @@ -32,6 +32,7 @@ The Link Catalog contains: * Metadata about each Link Index: * Last updated timestamp * Commit SHA that produced the Link Index + * ETAG of the Link Index file * URL to the Link Index file ## Maintenance @@ -52,9 +53,8 @@ This process ensures the catalog stays in sync with published Link Index files w When running `docs-builder assembler clone` or `docs-builder assembler build`: 1. The assembler fetches the Link Catalog -2. It determines which repositories and versions to clone/build based on the site configuration +2. It determines which repositories and versions to clone/build based on the [site configuration](../configure/site/index.md) 3. It uses the commit SHAs from the catalog to clone specific versions -4. It falls back to the last known good commit if a repository's current state has build failures ### By documentation builds @@ -62,7 +62,7 @@ During a documentation build: 1. `docs-builder` fetches the Link Catalog 2. It determines which Link Index files to download for cross-repository validation -3. It validates all crosslinks against the appropriate Link Index files +3. It validates all cross-links against the appropriate Link Index files ## Benefits diff --git a/docs/building-blocks/link-service.md b/docs/building-blocks/link-service.md index b3129cc43..e45ab097f 100644 --- a/docs/building-blocks/link-service.md +++ b/docs/building-blocks/link-service.md @@ -4,13 +4,20 @@ navigation_title: Link Service # Link Service -The **Link Service** is the central location where all [Link Index](link-index.md) files are published and stored. +The **Link Service** is the central location that stores: + +* All [Link Index](link-index.md) files for all the repositories and branches that are published. +* The [Link Catalog](link-catalog.md), a single JSON file that contains references to all the `Link Index` files. + +We only have one link service today for all public documentation. + +* https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/ ## Architecture The Link Service is implemented as: -* **Storage** - An S3 bucket containing all Link Index files +* **Storage** - An S3 bucket * **CDN** - CloudFront fronting the S3 bucket for fast global access * **Access** - Publicly accessible for read operations From 2e0cfd4d6ca3393c9bef68fb2161c717ea6e47da Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 13:14:53 +0200 Subject: [PATCH 15/86] update redirects --- docs/_redirects.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_redirects.yml b/docs/_redirects.yml index e3ed6e726..df2983983 100644 --- a/docs/_redirects.yml +++ b/docs/_redirects.yml @@ -1,4 +1,6 @@ redirects: + 'migration/freeze/gh-action.md' : 'index.md' + 'migration/freeze/index.md' : 'index.md' 'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md' 'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md' 'testing/redirects/6th-page.md': From ea397463714854da333f0a2673b539b37dc98884 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 14:12:02 +0200 Subject: [PATCH 16/86] Apply suggestions from code review Co-authored-by: Fabrizio Ferri-Benedetti --- .../assembled-documentation.md | 50 ++++++++++--------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md index 33020aaa1..1ed3e2515 100644 --- a/docs/building-blocks/assembled-documentation.md +++ b/docs/building-blocks/assembled-documentation.md @@ -1,50 +1,52 @@ --- -navigation_title: Assembled Documentation +navigation_title: Assembled documentation --- -# Assembled Documentation +# Assembled documentation -**Assembled documentation** is the product of building many [documentation sets](documentation-set.md) and weaving them into a global navigation to produce the fully assembled documentation site. +Assembled documentation is the product of building many [documentation sets](documentation-set.md) and weaving them into a global navigation to produce the fully assembled documentation site. ## How it works The assembler: -1. Clones multiple documentation repositories -2. Reads its [configuration files](../configure/site/index.md) and builds [a global navigation](../configure/site/navigation.md) -3. Builds each documentation set independently using the global configuration and navigation to inform path prefixes -4. Produces a unified documentation website +1. Clones multiple documentation repositories. +2. Reads the [configuration files](../configure/site/index.md) and builds [a global navigation](../configure/site/navigation.md). +3. Builds each documentation set independently using the global configuration and navigation to inform path prefixes. +4. Produces a unified documentation website. ## Configuration Assembled documentation is configured through the site configuration, which defines: -* [assembler.yml](../configure/site/index.md) Which repositories to include and [their branching strategy](../contribute/branching-strategy.md) -* [navigation.yml](../configure/site/index.md) Navigation and url prefixes for TOC's. -* [versions.yml](../configure/site/versions.md) Defines the various versioning schemes of products/solutions being documented -* [products.yml](../configure/site/products.md) Defines the product catalog (id, name) and ties it to a specific versioning scheme +* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md) +* [navigation.yml](../configure/site/index.md): Navigation and url prefixes for TOC's. +* [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented +* [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme -See [Site Configuration](../configure/site/index.md) for complete details on configuring assembled documentation. +Refer to [Site Configuration](../configure/site/index.md) for details on configuring assembled documentation. -Important to note that `docs-builder` makes no assumptions about how repositories, products, solutions and versions tie into each other. +:::{important} +The `docs-builder` command makes no assumptions about how repositories, products, solutions and versions tie into each other. +::: ## Build process -The typical build process for assembled documentation: +The typical build process for assembled documentation consists of three steps: -1. **Clone** - Clone all configured repositories using `docs-builder assembler clone` -2. **Build** - Build all documentation sets using `docs-builder assembler build` -3. **Serve** - Serve the documentation on http://localhost:4000 using `docs-builder assembler serve` +1. Clone all configured repositories using `docs-builder assembler clone`. +2. Build all documentation sets using `docs-builder assembler build`. +3. Serve the documentation on http://localhost:4000 using `docs-builder assembler serve`. This uses the embedded configuration files inside the `docs-builder` binary. To build a specific configuration: -1. **Init Config** - Fetch the latest config to `$(pwd)/config` `docs-builder assembler config init --local` -2. **Clone** - Clone all configured repositories using `docs-builder assembler clone --local` -3. **Build** - Build all documentation sets using `docs-builder assembler build --local` -4. **Serve** - Serve the documentation on http://localhost:4000 using `docs-builder assembler serve` +1. Fetch the latest config to `$(pwd)/config` `docs-builder assembler config init --local`. +2. Clone all configured repositories using `docs-builder assembler clone --local`. +3. Build all documentation sets using `docs-builder assembler build --local`. +4. Serve the documentation on http://localhost:4000 using `docs-builder assembler serve`. ## Related concepts -* [Documentation Set](documentation-set.md) - The individual units being assembled -* [Distributed Documentation](distributed-documentation.md) - How documentation sets work independently -* [Link Catalog](link-catalog.md) - How the assembler knows what to include +* [Documentation set](documentation-set.md): The individual units being assembled. +* [Distributed documentation](distributed-documentation.md): How documentation sets work independently. +* [Link catalog](link-catalog.md): How the assembler knows what to include. From b3b5309d652e2f7360c610eb16b1c1c582d7cebf Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 14:17:35 +0200 Subject: [PATCH 17/86] Sentence case --- docs/building-blocks/distributed-documentation.md | 4 ++-- docs/building-blocks/documentation-set-navigation.md | 4 ++-- docs/building-blocks/documentation-set.md | 4 ++-- docs/building-blocks/global-navigation.md | 4 ++-- docs/building-blocks/inbound-crosslinks.md | 4 ++-- docs/building-blocks/index.md | 4 ++-- docs/building-blocks/link-catalog.md | 4 ++-- docs/building-blocks/link-index.md | 4 ++-- docs/building-blocks/link-service.md | 4 ++-- docs/building-blocks/outbound-crosslinks.md | 4 ++-- 10 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/building-blocks/distributed-documentation.md b/docs/building-blocks/distributed-documentation.md index 8258e004f..dc06f34c6 100644 --- a/docs/building-blocks/distributed-documentation.md +++ b/docs/building-blocks/distributed-documentation.md @@ -1,8 +1,8 @@ --- -navigation_title: Distributed Documentation +navigation_title: Distributed documentation --- -# Distributed Documentation +# Distributed documentation **Distributed documentation** is the architectural approach that allows repositories to build their own documentation independently. diff --git a/docs/building-blocks/documentation-set-navigation.md b/docs/building-blocks/documentation-set-navigation.md index 3adf88b50..40cbac2e3 100644 --- a/docs/building-blocks/documentation-set-navigation.md +++ b/docs/building-blocks/documentation-set-navigation.md @@ -1,8 +1,8 @@ --- -navigation_title: Documentation Set Navigation +navigation_title: Documentation set navigation --- -# Documentation Set Navigation +# Documentation set navigation **Documentation set navigation** defines how files within a single documentation set are organized and structured. Each documentation set is responsible for its own internal navigation hierarchy. diff --git a/docs/building-blocks/documentation-set.md b/docs/building-blocks/documentation-set.md index 5ed4dc2a5..53da16a48 100644 --- a/docs/building-blocks/documentation-set.md +++ b/docs/building-blocks/documentation-set.md @@ -1,8 +1,8 @@ --- -navigation_title: Documentation Set +navigation_title: Documentation set --- -# Documentation Set +# Documentation set A **documentation set** is a single folder containing the documentation of a single repository. This is the fundamental unit of documentation in the docs-builder system. diff --git a/docs/building-blocks/global-navigation.md b/docs/building-blocks/global-navigation.md index 223bd0ffb..cb86efe55 100644 --- a/docs/building-blocks/global-navigation.md +++ b/docs/building-blocks/global-navigation.md @@ -1,8 +1,8 @@ --- -navigation_title: Global Navigation +navigation_title: Global navigation --- -# Global Navigation +# Global navigation **Global navigation** defines how multiple documentation sets are organized and presented together in [assembled documentation](assembled-documentation.md). It creates a unified navigation structure across all repositories. diff --git a/docs/building-blocks/inbound-crosslinks.md b/docs/building-blocks/inbound-crosslinks.md index e661c7f65..c7a489b91 100644 --- a/docs/building-blocks/inbound-crosslinks.md +++ b/docs/building-blocks/inbound-crosslinks.md @@ -1,8 +1,8 @@ --- -navigation_title: Inbound Crosslinks +navigation_title: Inbound cross-links --- -# Inbound Crosslinks +# Inbound cross-links **Inbound crosslinks** are links from other documentation sets to yours. Understanding and validating inbound crosslinks helps prevent breaking links in other repositories when you make changes. diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index f571ad0f2..671ae2df3 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -1,8 +1,8 @@ --- -navigation_title: Building Blocks +navigation_title: Building blocks --- -# Building Blocks +# Building blocks This section explains the core concepts and building blocks that make up the docs-builder architecture. Understanding these concepts will help you work effectively with distributed documentation and cross-repository linking. diff --git a/docs/building-blocks/link-catalog.md b/docs/building-blocks/link-catalog.md index a8705be16..a77060173 100644 --- a/docs/building-blocks/link-catalog.md +++ b/docs/building-blocks/link-catalog.md @@ -1,8 +1,8 @@ --- -navigation_title: Link Catalog +navigation_title: Link catalog --- -# Link Catalog +# Link catalog The **Link Catalog** is a single JSON file that serves as a catalog of all available [Link Index](link-index.md) files across all repositories. diff --git a/docs/building-blocks/link-index.md b/docs/building-blocks/link-index.md index b12bad7da..074ab4c49 100644 --- a/docs/building-blocks/link-index.md +++ b/docs/building-blocks/link-index.md @@ -1,8 +1,8 @@ --- -navigation_title: Link Index +navigation_title: Link index --- -# Link Index +# Link index A **Link Index** is a JSON file (`links.json`) that contains all the linkable resources for a specific repository branch. diff --git a/docs/building-blocks/link-service.md b/docs/building-blocks/link-service.md index e45ab097f..a4f2dd337 100644 --- a/docs/building-blocks/link-service.md +++ b/docs/building-blocks/link-service.md @@ -1,8 +1,8 @@ --- -navigation_title: Link Service +navigation_title: Link service --- -# Link Service +# Link service The **Link Service** is the central location that stores: diff --git a/docs/building-blocks/outbound-crosslinks.md b/docs/building-blocks/outbound-crosslinks.md index 0fb913880..09d58fdbd 100644 --- a/docs/building-blocks/outbound-crosslinks.md +++ b/docs/building-blocks/outbound-crosslinks.md @@ -1,8 +1,8 @@ --- -navigation_title: Outbound Crosslinks +navigation_title: Outbound crosslinks --- -# Outbound Crosslinks +# Outbound crosslinks **Outbound crosslinks** are links from your documentation set to other documentation sets in different repositories. From eb5f50d130a54f014b86475b6539caf07135763c Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 14:26:34 +0200 Subject: [PATCH 18/86] fix links --- docs/_docset.yml | 4 ++-- .../distributed-documentation.md | 4 ++-- ...d-crosslinks.md => inbound-cross-links.md} | 6 ++--- docs/building-blocks/index.md | 8 +++---- docs/building-blocks/link-index.md | 10 ++++----- docs/building-blocks/link-service.md | 4 ++-- ...-crosslinks.md => outbound-cross-links.md} | 22 +++++++++---------- docs/cli/assembler/assembler-deploy-apply.md | 2 +- docs/cli/docset/index.md | 12 +++++----- docs/cli/links/index.md | 6 ++--- docs/configure/content-set/index.md | 8 +++---- 11 files changed, 43 insertions(+), 43 deletions(-) rename docs/building-blocks/{inbound-crosslinks.md => inbound-cross-links.md} (91%) rename docs/building-blocks/{outbound-crosslinks.md => outbound-cross-links.md} (77%) diff --git a/docs/_docset.yml b/docs/_docset.yml index e2bd86d51..bad2fe7e4 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -55,8 +55,8 @@ toc: - file: link-service.md - file: link-index.md - file: link-catalog.md - - file: outbound-crosslinks.md - - file: inbound-crosslinks.md + - file: outbound-cross-links.md + - file: inbound-cross-links.md - file: documentation-set-navigation.md - file: global-navigation.md - folder: configure diff --git a/docs/building-blocks/distributed-documentation.md b/docs/building-blocks/distributed-documentation.md index dc06f34c6..eeb799e2d 100644 --- a/docs/building-blocks/distributed-documentation.md +++ b/docs/building-blocks/distributed-documentation.md @@ -55,8 +55,8 @@ The distributed documentation system relies on several key components: * [Link Index](link-index.md) - Per-repository file of linkable resources * [Link Service](link-service.md) - Central storage for Link Index files * [Link Catalog](link-catalog.md) - Catalog of all available Link Index files -* [Outbound Crosslinks](outbound-crosslinks.md) - Links from one repository to another -* [Inbound Crosslinks](inbound-crosslinks.md) - Links from other repositories to yours +* [Outbound Cross-links](outbound-cross-links.md) - Links from one repository to another +* [Inbound Cross-links](inbound-cross-links.md) - Links from other repositories to yours ## Local development diff --git a/docs/building-blocks/inbound-crosslinks.md b/docs/building-blocks/inbound-cross-links.md similarity index 91% rename from docs/building-blocks/inbound-crosslinks.md rename to docs/building-blocks/inbound-cross-links.md index c7a489b91..0cedfb17f 100644 --- a/docs/building-blocks/inbound-crosslinks.md +++ b/docs/building-blocks/inbound-cross-links.md @@ -4,11 +4,11 @@ navigation_title: Inbound cross-links # Inbound cross-links -**Inbound crosslinks** are links from other documentation sets to yours. Understanding and validating inbound crosslinks helps prevent breaking links in other repositories when you make changes. +**Inbound cross-links** are links from other documentation sets to yours. Understanding and validating inbound cross-links helps prevent breaking links in other repositories when you make changes. ## Purpose -Inbound crosslink validation allows you to: +Inbound cross-link validation allows you to: * **Detect breaking changes** - Know when renaming or deleting a file will break links from other repositories * **Prevent regressions** - Avoid publishing changes that break documentation elsewhere @@ -114,7 +114,7 @@ Make inbound link validation part of your review process: ## Related concepts -* [Outbound Crosslinks](outbound-crosslinks.md) - Links from your documentation to others +* [Outbound Cross-links](outbound-cross-links.md) - Links from your documentation to others * [Link Index](link-index.md) - How your linkable resources are tracked * [Link Service](link-service.md) - Where inbound link information is stored * [Distributed Documentation](distributed-documentation.md) - The architecture enabling this validation diff --git a/docs/building-blocks/index.md b/docs/building-blocks/index.md index 671ae2df3..087ffc58f 100644 --- a/docs/building-blocks/index.md +++ b/docs/building-blocks/index.md @@ -36,11 +36,11 @@ A catalog file listing all available Link Index files across all repositories an ## Cross-repository linking -### [Outbound Crosslinks](outbound-crosslinks.md) +### [Outbound Cross-links](outbound-cross-links.md) Links from your documentation to other documentation sets. Validated against published Link Index files to ensure they're correct. -### [Inbound Crosslinks](inbound-crosslinks.md) +### [Inbound Cross-links](inbound-cross-links.md) Links from other documentation sets to yours. Validated to prevent breaking changes when you move or delete content. @@ -52,13 +52,13 @@ How individual documentation sets organize their content through TOC sections in ### [Global Navigation](global-navigation.md) -How multiple documentation sets are organized together in assembled documentation through `navigation.yml`. Uses crosslink syntax to reference TOC sections from different repositories and enables cross-repository content organization. +How multiple documentation sets are organized together in assembled documentation through `navigation.yml`. Uses cross-link syntax to reference TOC sections from different repositories and enables cross-repository content organization. ## How it all works together 1. Each repository builds its documentation set independently 2. Successful builds publish a Link Index to the Link Service 3. The Link Catalog catalogs all available Link Index files -4. Documentation builds validate crosslinks using these Link Index files +4. Documentation builds validate cross-links using these Link Index files 5. The assembler combines documentation sets using the Link Catalog 6. Teams can work independently while maintaining link integrity across repositories diff --git a/docs/building-blocks/link-index.md b/docs/building-blocks/link-index.md index 074ab4c49..a0b2a4a96 100644 --- a/docs/building-blocks/link-index.md +++ b/docs/building-blocks/link-index.md @@ -46,16 +46,16 @@ The Link Index is automatically generated during a documentation build: ## Usage -### Resolving outbound crosslinks +### Resolving outbound cross-links -When you use a crosslink like `elasticsearch://reference/api/search.md`, `docs-builder`: +When you use a cross-link like `elasticsearch://reference/api/search.md`, `docs-builder`: 1. Fetches the Elasticsearch Link Index from the Link Service 2. Looks up the path in the index 3. Validates the link exists 4. Resolves it to the correct URL -### Validating inbound crosslinks +### Validating inbound cross-links When building your documentation, `docs-builder` can: @@ -82,5 +82,5 @@ https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/{org}/{repo}/{branch} * [Link Service](link-service.md) - Where Link Index files are stored * [Link Catalog](link-catalog.md) - Catalog of all Link Index files -* [Outbound Crosslinks](outbound-crosslinks.md) - Links that use the Link Index -* [Inbound Crosslinks](inbound-crosslinks.md) - Links to resources in the Link Index +* [Outbound Cross-links](outbound-cross-links.md) - Links that use the Link Index +* [Inbound Cross-links](inbound-cross-links.md) - Links to resources in the Link Index diff --git a/docs/building-blocks/link-service.md b/docs/building-blocks/link-service.md index a4f2dd337..7d173f212 100644 --- a/docs/building-blocks/link-service.md +++ b/docs/building-blocks/link-service.md @@ -56,8 +56,8 @@ When a documentation build completes successfully on a default integration branc During both local and CI builds, `docs-builder`: * Fetches relevant Link Index files from the Link Service -* Validates outbound crosslinks against these indexes -* Validates that inbound crosslinks won't be broken by local changes +* Validates outbound cross-links against these indexes +* Validates that inbound cross-links won't be broken by local changes ## Related concepts diff --git a/docs/building-blocks/outbound-crosslinks.md b/docs/building-blocks/outbound-cross-links.md similarity index 77% rename from docs/building-blocks/outbound-crosslinks.md rename to docs/building-blocks/outbound-cross-links.md index 09d58fdbd..07353b1e3 100644 --- a/docs/building-blocks/outbound-crosslinks.md +++ b/docs/building-blocks/outbound-cross-links.md @@ -1,14 +1,14 @@ --- -navigation_title: Outbound crosslinks +navigation_title: Outbound cross-links --- -# Outbound crosslinks +# Outbound cross-links -**Outbound crosslinks** are links from your documentation set to other documentation sets in different repositories. +**Outbound cross-links** are links from your documentation set to other documentation sets in different repositories. ## Purpose -Outbound crosslinks allow you to: +Outbound cross-links allow you to: * Link to documentation in other repositories * Maintain those links even as the target repository evolves @@ -17,7 +17,7 @@ Outbound crosslinks allow you to: ## Syntax -If both repositories publish to the same [Link Service](link-service.md), they can link to each other using the crosslink syntax: +If both repositories publish to the same [Link Service](link-service.md), they can link to each other using the cross-link syntax: ```markdown [Link text](repository-name://path/to/file.md) @@ -39,12 +39,12 @@ cross_links: ``` -When `docs-builder` encounters a crosslink: +When `docs-builder` encounters a cross-link: 1. **Parse** - Extracts the repository name and path from the link 3. **Resolve** - Looks up the path in the locally cached [Link Index](link-index.md) to get the actual URL 4. **Validate** - Verifies the link exists and generates an error if not -5. **Transform** - Replaces the crosslink with the fully resolved URL in the output +5. **Transform** - Replaces the cross-link with the fully resolved URL in the output ## Validation @@ -67,7 +67,7 @@ cross_links: This instructs `docs-builder` to fetch the `Link Index` from the [Link Service](link-service.md) during the build process which are then cached locally. `docs-builder` will validate locally cached `Link Index` files against the remote `Link Index` files on each build fetching updates as needed. -Now you can create crosslinks e.g `elasticsearch://path/to/file.md` +Now you can create cross-links e.g `elasticsearch://path/to/file.md` The explicit opt-in prevents each repository build having the fetch all the links for all the repositories in the [`Link Catalog`](link-catalog.md) of which there may be many. @@ -85,7 +85,7 @@ The explicit opt-in prevents each repository build having the fetch all the link [Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html) ``` -The crosslink syntax is resilient to: +The cross-link syntax is resilient to: * URL structure changes * File moves (if redirects are configured) * Version differences @@ -100,6 +100,6 @@ You can link to specific headings within a page: ## Related concepts -* [Inbound Crosslinks](inbound-crosslinks.md) - Links from other repositories to yours -* [Link Index](link-index.md) - How crosslinks are resolved +* [Inbound Cross-links](inbound-cross-links.md) - Links from other repositories to yours +* [Link Index](link-index.md) - How cross-links are resolved * [Links syntax](../syntax/links.md) - Complete link syntax documentation diff --git a/docs/cli/assembler/assembler-deploy-apply.md b/docs/cli/assembler/assembler-deploy-apply.md index ce1c0df27..4e745387a 100644 --- a/docs/cli/assembler/assembler-deploy-apply.md +++ b/docs/cli/assembler/assembler-deploy-apply.md @@ -4,7 +4,7 @@ navigation_title: "deploy apply" # assembler deploy apply -Applies an incremental synchronization plan created by [`docs-builder assembler deploy plan`](./assembler-deploy-plan). +Applies an incremental synchronization plan created by [`docs-builder assembler deploy plan`](./assembler-deploy-plan.md). ## Usage diff --git a/docs/cli/docset/index.md b/docs/cli/docset/index.md index fc11c183c..d3e794c05 100644 --- a/docs/cli/docset/index.md +++ b/docs/cli/docset/index.md @@ -6,7 +6,7 @@ navigation_title: "documentation set" An isolated build means building a single documentation set. -A `Documentation Set` is defined as a folder containing a [docset.yml](../configure/content-set/index.md) file. +A `Documentation Set` is defined as a folder containing a [docset.yml](../../configure/content-set/index.md) file. These commands are typically what you interface with when you are working on the documentation of a single repository locally. @@ -15,12 +15,12 @@ These commands are typically what you interface with when you are working on the `build` is the default command so you can just run `docs-builder` to build a single documentation set. `docs-builder` will locate the `docset.yml` anywhere in the directory tree automatically and build the documentation. -- [build](docset/build.md) - build a single documentation set (incrementally) -- [serve](docset/serve.md) - partial build and serve documentation as needed at http://localhost:3000 -- [index](docset/index-command.md) - ingest a single documentation set to an Elasticsearch index. +- [build](build.md) - build a single documentation set (incrementally) +- [serve](serve.md) - partial build and serve documentation as needed at http://localhost:3000 +- [index](index-command.md) - ingest a single documentation set to an Elasticsearch index. ## Refactor commands -- [mv](docset/mv.md) - move a file or folder to a new location. This will rewrite all links in all files too. -- [diff validate](docset/diff-validate.md) - validate that local changes are reflected in [redirects.yml](../contribute/redirects.md) +- [mv](mv.md) - move a file or folder to a new location. This will rewrite all links in all files too. +- [diff validate](diff-validate.md) - validate that local changes are reflected in [redirects.yml](../../contribute/redirects.md) diff --git a/docs/cli/links/index.md b/docs/cli/links/index.md index 60f838ba3..002dbfbe7 100644 --- a/docs/cli/links/index.md +++ b/docs/cli/links/index.md @@ -10,6 +10,6 @@ Inbound links, those going from other sources to the documentation set, are vali ### Inbound link validation commands -- [inbound-links validate-all](links/inbound-links-validate-all.md) - validate all inbounds links as published to the links registry. -- [inbound-links validate](links/inbound-links-validate.md) - validate inbound links from and to specific repositories -- [inbound-links validate-link-reference](links/inbound-links-validate-link-reference.md) - validate a local link reference artifact from [build](docset/build.md) with the published registry +- [inbound-links validate-all](inbound-links-validate-all.md) - validate all inbounds links as published to the links registry. +- [inbound-links validate](inbound-links-validate.md) - validate inbound links from and to specific repositories +- [inbound-links validate-link-reference](inbound-links-validate-link-reference.md) - validate a local link reference artifact from [build](../docset/build.md) with the published registry diff --git a/docs/configure/content-set/index.md b/docs/configure/content-set/index.md index 30586e711..f813d3de2 100644 --- a/docs/configure/content-set/index.md +++ b/docs/configure/content-set/index.md @@ -8,10 +8,10 @@ Elastic documentation is spread across multiple repositories. Each repository ca A content set in `docs-builder` is equivalent to an AsciiDoc book. At this level, the system consists of: -| System property | Asciidoc | V3 | -| -------------------- | -------------------- | -------------------- | -| **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams | -| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | `docset.yml` and/or `toc.yml` file(s) | +| System property | Asciidoc | V3 | +|--------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| +| **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams | +| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | `docset.yml` and/or `toc.yml` file(s) | ## Learn more From 73d827f8ca1d7093e6f1eb72cecd1dee67958184 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Wed, 1 Oct 2025 14:42:26 +0200 Subject: [PATCH 19/86] List items full stop --- .../assembled-documentation.md | 12 ++--- .../distributed-documentation.md | 34 +++++++------- .../documentation-set-navigation.md | 32 ++++++------- docs/building-blocks/documentation-set.md | 16 +++---- docs/building-blocks/global-navigation.md | 46 +++++++++---------- docs/building-blocks/inbound-cross-links.md | 28 +++++------ docs/building-blocks/link-catalog.md | 34 +++++++------- docs/building-blocks/link-index.md | 32 ++++++------- docs/building-blocks/link-service.md | 32 ++++++------- docs/building-blocks/outbound-cross-links.md | 24 +++++----- docs/cli/assembler/assemble.md | 2 +- docs/cli/assembler/assembler-config-init.md | 6 +-- .../assembler-content-source-match.md | 6 +-- docs/cli/docset/build.md | 4 +- docs/cli/docset/diff-validate.md | 2 +- docs/configure/content-set/index.md | 6 +-- docs/configure/index.md | 10 ++-- docs/configure/site/content.md | 8 ++-- .../cumulative-docs/badge-placement.md | 10 ++-- .../cumulative-docs/example-scenarios.md | 12 ++--- 20 files changed, 178 insertions(+), 178 deletions(-) diff --git a/docs/building-blocks/assembled-documentation.md b/docs/building-blocks/assembled-documentation.md index 1ed3e2515..171314350 100644 --- a/docs/building-blocks/assembled-documentation.md +++ b/docs/building-blocks/assembled-documentation.md @@ -19,10 +19,10 @@ The assembler: Assembled documentation is configured through the site configuration, which defines: -* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md) +* [assembler.yml](../configure/site/index.md): Which repositories to include and [their branching strategy](../contribute/branching-strategy.md). * [navigation.yml](../configure/site/index.md): Navigation and url prefixes for TOC's. -* [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented -* [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme +* [versions.yml](../configure/site/versions.md): Defines the various versioning schemes of products/solutions being documented. +* [products.yml](../configure/site/products.md): Defines the product catalog (id, name) and ties it to a specific versioning scheme. Refer to [Site Configuration](../configure/site/index.md) for details on configuring assembled documentation. @@ -47,6 +47,6 @@ This uses the embedded configuration files inside the `docs-builder` binary. To ## Related concepts -* [Documentation set](documentation-set.md): The individual units being assembled. -* [Distributed documentation](distributed-documentation.md): How documentation sets work independently. -* [Link catalog](link-catalog.md): How the assembler knows what to include. +* [Documentation Set](documentation-set.md): The individual units being assembled. +* [Distributed Documentation](distributed-documentation.md): How documentation sets work independently. +* [Link Catalog](link-catalog.md): How the assembler knows what to include. diff --git a/docs/building-blocks/distributed-documentation.md b/docs/building-blocks/distributed-documentation.md index eeb799e2d..0f801faa3 100644 --- a/docs/building-blocks/distributed-documentation.md +++ b/docs/building-blocks/distributed-documentation.md @@ -10,10 +10,10 @@ navigation_title: Distributed documentation The separation between building individual documentation sets and assembling them enables distributed builds, where: -* Each repository builds its own documentation independently -* Builds don't block each other -* Teams maintain full autonomy over their documentation -* Cross-repository links are validated without requiring synchronized builds +* Each repository builds its own documentation independently. +* Builds don't block each other. +* Teams maintain full autonomy over their documentation. +* Cross-repository links are validated without requiring synchronized builds. ## How it works @@ -33,30 +33,30 @@ This distributed approach provides several key advantages: ### Link validation -* **Outbound links** - Validate links to other repositories ahead of time, even during local `docs-builder` builds -* **Inbound links** - Know when changes to your documentation would break links from other repositories +* **Outbound links** - Validate links to other repositories ahead of time, even during local `docs-builder` builds. +* **Inbound links** - Know when changes to your documentation would break links from other repositories. ### Resilient builds -* **Isolation** - Documentation errors in one repository won't affect builds of other repositories -* **Fallback mechanism** - When a repository has build failures on its integration branch, the assembler falls back to the last known good commit -* **Snapshot builds** - Assembled builds only use commits that successfully produced a Link Index +* **Isolation** - Documentation errors in one repository won't affect builds of other repositories. +* **Fallback mechanism** - When a repository has build failures on its integration branch, the assembler falls back to the last known good commit. +* **Snapshot builds** - Assembled builds only use commits that successfully produced a Link Index. ### Independent iteration -* Teams can iterate on their documentation independently -* No coordination required for routine updates -* Faster feedback loops for documentation changes +* Teams can iterate on their documentation independently. +* No coordination required for routine updates. +* Faster feedback loops for documentation changes. ## Architecture components The distributed documentation system relies on several key components: -* [Link Index](link-index.md) - Per-repository file of linkable resources -* [Link Service](link-service.md) - Central storage for Link Index files -* [Link Catalog](link-catalog.md) - Catalog of all available Link Index files -* [Outbound Cross-links](outbound-cross-links.md) - Links from one repository to another -* [Inbound Cross-links](inbound-cross-links.md) - Links from other repositories to yours +* [Link Index](link-index.md) - Per-repository file of linkable resources. +* [Link Service](link-service.md) - Central storage for Link Index files. +* [Link Catalog](link-catalog.md) - Catalog of all available Link Index files. +* [Outbound Cross-links](outbound-cross-links.md) - Links from one repository to another. +* [Inbound Cross-links](inbound-cross-links.md) - Links from other repositories to yours. ## Local development diff --git a/docs/building-blocks/documentation-set-navigation.md b/docs/building-blocks/documentation-set-navigation.md index 40cbac2e3..68860584c 100644 --- a/docs/building-blocks/documentation-set-navigation.md +++ b/docs/building-blocks/documentation-set-navigation.md @@ -10,10 +10,10 @@ navigation_title: Documentation set navigation Documentation set navigation allows repository maintainers to: -* **Organize content** - Define the logical structure of their documentation -* **Control hierarchy** - Determine which pages are nested under others -* **Create sections** - Group related content together -* **Maintain autonomy** - Structure documentation independently of other repositories +* **Organize content** - Define the logical structure of their documentation. +* **Control hierarchy** - Determine which pages are nested under others. +* **Create sections** - Group related content together. +* **Maintain autonomy** - Structure documentation independently of other repositories. ## Basic structure @@ -121,10 +121,10 @@ The folder name `development` is not repeated in the `toc.yml` file. This allows ### Benefits of separate toc.yml files -* **Modularity** - Each section can be maintained independently -* **Cleaner docset.yml** - Keep the main file focused and readable -* **Easier refactoring** - Rename folders without updating TOC references -* **Team ownership** - Different teams can manage different TOC sections +* **Modularity** - Each section can be maintained independently. +* **Cleaner docset.yml** - Keep the main file focused and readable. +* **Easier refactoring** - Rename folders without updating TOC references. +* **Team ownership** - Different teams can manage different TOC sections. ## File paths @@ -163,8 +163,8 @@ contained in its file. When building [assembled documentation](assembled-documentation.md), the documentation set navigation becomes a component of the [global navigation](global-navigation.md): -* **Documentation set navigation** defines the structure **within** a repository -* **Global navigation** defines **how repositories are organized** relative to each other +* **Documentation set navigation** defines the structure **within** a repository. +* **Global navigation** defines **how repositories are organized** relative to each other. Named `toc` sections in `docset.yml` can be referenced and reorganized in the global `navigation.yml` file without affecting the documentation set's internal structure. @@ -172,9 +172,9 @@ Named `toc` sections in `docset.yml` can be referenced and reorganized in the gl ### Keep it organized -* Group related content in folders -* Use descriptive folder and file names -* Maintain a logical hierarchy +* Group related content in folders. +* Use descriptive folder and file names. +* Maintain a logical hierarchy. The folder names and hierarchy are reflected directly in the URL structure. @@ -231,6 +231,6 @@ These names will end up in the URL structure of the published documentation ## Related concepts -* [Global Navigation](global-navigation.md) - How documentation sets are organized in assembled documentation -* [Content Set Configuration](../configure/content-set/index.md) - Complete `docset.yml` reference -* [Navigation Configuration](../configure/content-set/navigation.md) - Detailed navigation options +* [Global Navigation](global-navigation.md) - How documentation sets are organized in assembled documentation. +* [Content Set Configuration](../configure/content-set/index.md) - Complete `docset.yml` reference. +* [Navigation Configuration](../configure/content-set/navigation.md) - Detailed navigation options. diff --git a/docs/building-blocks/documentation-set.md b/docs/building-blocks/documentation-set.md index 53da16a48..4446fafe4 100644 --- a/docs/building-blocks/documentation-set.md +++ b/docs/building-blocks/documentation-set.md @@ -10,17 +10,17 @@ A **documentation set** is a single folder containing the documentation of a sin At a minimum, a documentation set folder must contain: -* `docset.yml` - The configuration file that defines the structure and metadata of the documentation set -* `index.md` - The entry point or landing page for the documentation set +* `docset.yml` - The configuration file that defines the structure and metadata of the documentation set. +* `index.md` - The entry point or landing page for the documentation set. ## Purpose Documentation sets allow each repository to maintain its own documentation independently. Each set can be: -* Built independently -* Versioned separately -* Maintained by different teams -* Published to its own schedule +* Built independently. +* Versioned separately. +* Maintained by different teams. +* Published to its own schedule. ## Structure @@ -45,5 +45,5 @@ The `docset.yml` file controls how the documentation set is structured and built ## Related concepts -* [Assembled Documentation](assembled-documentation.md) - How multiple documentation sets are combined -* [Link Index](link-index.md) - How documentation sets publish their linkable resources +* [Assembled Documentation](assembled-documentation.md) - How multiple documentation sets are combined. +* [Link Index](link-index.md) - How documentation sets publish their linkable resources. diff --git a/docs/building-blocks/global-navigation.md b/docs/building-blocks/global-navigation.md index cb86efe55..ffca30ac8 100644 --- a/docs/building-blocks/global-navigation.md +++ b/docs/building-blocks/global-navigation.md @@ -10,10 +10,10 @@ navigation_title: Global navigation Global navigation enables: -* **Unified experience** - Present documentation from multiple repositories as a cohesive whole -* **Flexible organization** - Arrange documentation by product, feature, or audience rather than by repository -* **Independent evolution** - Reorganize global structure without changing documentation sets -* **Cross-repository grouping** - Combine related content from different repositories +* **Unified experience** - Present documentation from multiple repositories as a cohesive whole. +* **Flexible organization** - Arrange documentation by product, feature, or audience rather than by repository. +* **Independent evolution** - Reorganize global structure without changing documentation sets. +* **Cross-repository grouping** - Combine related content from different repositories. ## Configuration @@ -23,9 +23,9 @@ Global navigation is defined in the `navigation.yml` file, which is part of the Global navigation has specific restrictions: -* **It may only link to `toc.yml` or `docset.yml` files** - You cannot reference individual markdown files -* **Uses crosslink syntax** - References to other repositories use the `repository://` syntax -* **Requires all TOC sections** - Dangling TOC sections are not allowed +* **It may only link to `toc.yml` or `docset.yml` files** - You cannot reference individual markdown files. +* **Uses crosslink syntax** - References to other repositories use the `repository://` syntax. +* **Requires all TOC sections** - Dangling TOC sections are not allowed. ## Basic structure @@ -82,9 +82,9 @@ You must explicitly provide a URL path prefix when including a `toc`. ``` This allows you to: -* Group content from different repositories under a common path -* Avoid URL conflicts when combining repositories -* Create product-specific URL structures +* Group content from different repositories under a common path. +* Avoid URL conflicts when combining repositories. +* Create product-specific URL structures. ## Reorganization independence @@ -115,10 +115,10 @@ All `toc` sections must be linked in `navigation.yml`. **Dangling `toc` sections are not allowed** and the assembler build will report an error if it finds any. This ensures: -* No content is accidentally excluded from the site -* Navigation references are always valid -* Documentation coverage is complete -* Every TOC section defined in a `docset.yml` appears somewhere in the global navigation +* No content is accidentally excluded from the site. +* Navigation references are always valid. +* Documentation coverage is complete. +* Every TOC section defined in a `docset.yml` appears somewhere in the global navigation. ### Example of validation @@ -147,10 +147,10 @@ If either is missing, the build will fail with an error about dangling TOC secti When building assembled documentation, `docs-builder` validates: -* All referenced TOC sections exist -* No TOC sections are dangling (unreferenced) -* Path prefixes don't conflict -* Crosslink references resolve correctly +* All referenced TOC sections exist. +* No TOC sections are dangling (unreferenced). +* Path prefixes don't conflict. +* Crosslink references resolve correctly. Validation errors will cause the assembler build to fail. @@ -186,8 +186,8 @@ During an assembler build: ## Related concepts -* [Documentation Set Navigation](documentation-set-navigation.md) - How individual repositories organize their content -* [Assembled Documentation](assembled-documentation.md) - The build process that uses global navigation -* [Site Configuration](../configure/site/index.md) - Complete site configuration reference -* [Navigation Configuration](../configure/site/navigation.md) - Detailed navigation.yml reference -* [Cross-link syntax](../syntax/links.md) - Understanding the repository:// syntax +* [Documentation Set Navigation](documentation-set-navigation.md) - How individual repositories organize their content. +* [Assembled Documentation](assembled-documentation.md) - The build process that uses global navigation. +* [Site Configuration](../configure/site/index.md) - Complete site configuration reference. +* [Navigation Configuration](../configure/site/navigation.md) - Detailed navigation.yml reference. +* [Cross-link syntax](../syntax/links.md) - Understanding the `://` syntax. diff --git a/docs/building-blocks/inbound-cross-links.md b/docs/building-blocks/inbound-cross-links.md index 0cedfb17f..de132fc9b 100644 --- a/docs/building-blocks/inbound-cross-links.md +++ b/docs/building-blocks/inbound-cross-links.md @@ -10,9 +10,9 @@ navigation_title: Inbound cross-links Inbound cross-link validation allows you to: -* **Detect breaking changes** - Know when renaming or deleting a file will break links from other repositories -* **Prevent regressions** - Avoid publishing changes that break documentation elsewhere -* **Coordinate changes** - Understand dependencies before making structural changes +* **Detect breaking changes** - Know when renaming or deleting a file will break links from other repositories. +* **Prevent regressions** - Avoid publishing changes that break documentation elsewhere. +* **Coordinate changes** - Understand dependencies before making structural changes. ## How it works @@ -99,22 +99,22 @@ redirects: If you need to make a breaking change: -1. Run inbound link validation to identify affected repositories -2. File issues or notify maintainers of affected repositories -3. Coordinate the change timing -4. Provide redirect mappings or alternative URLs +1. Run inbound link validation to identify affected repositories. +2. File issues or notify maintainers of affected repositories. +3. Coordinate the change timing, +4. Provide redirect mappings or alternative URLs. ### Validate before merging Make inbound link validation part of your review process: -* Run validation locally before creating a PR -* Include validation in CI checks -* Review validation results before merging +* Run validation locally before creating a PR. +* Include validation in CI checks. +* Review validation results before merging. ## Related concepts -* [Outbound Cross-links](outbound-cross-links.md) - Links from your documentation to others -* [Link Index](link-index.md) - How your linkable resources are tracked -* [Link Service](link-service.md) - Where inbound link information is stored -* [Distributed Documentation](distributed-documentation.md) - The architecture enabling this validation +* [Outbound Cross-links](outbound-cross-links.md) - Links from your documentation to others. +* [Link Index](link-index.md) - How your linkable resources are tracked. +* [Link Service](link-service.md) - Where inbound link information is stored. +* [Distributed Documentation](distributed-documentation.md) - The architecture enabling this validation. diff --git a/docs/building-blocks/link-catalog.md b/docs/building-blocks/link-catalog.md index a77060173..a54a6f526 100644 --- a/docs/building-blocks/link-catalog.md +++ b/docs/building-blocks/link-catalog.md @@ -10,9 +10,9 @@ The **Link Catalog** is a single JSON file that serves as a catalog of all avail The Link Catalog provides: -* **Discovery** - A single file to query for all available documentation across all repositories and branches -* **Efficiency** - Avoid scanning the entire [Link Service](link-service.md) to find available Link Index files -* **Assembler coordination** - The assembler uses this to determine which repositories and versions are available to build +* **Discovery** - A single file to query for all available documentation across all repositories and branches. +* **Efficiency** - Avoid scanning the entire [Link Service](link-service.md) to find available Link Index files. +* **Assembler coordination** - The assembler uses this to determine which repositories and versions are available to build. ## Location @@ -26,14 +26,14 @@ https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json The Link Catalog contains: -* List of all organizations (e.g., `elastic`) -* Repositories within each organization (e.g., `elasticsearch`, `kibana`) -* Branches for each repository (e.g., `main`, `8.x`, `7.17`) +* List of all organizations (e.g., `elastic`). +* Repositories within each organization (e.g., `elasticsearch`, `kibana`). +* Branches for each repository (e.g., `main`, `8.x`, `7.17`). * Metadata about each Link Index: - * Last updated timestamp - * Commit SHA that produced the Link Index - * ETAG of the Link Index file - * URL to the Link Index file + * Last updated timestamp. + * Commit SHA that produced the Link Index. + * ETAG of the Link Index file. + * URL to the Link Index file. ## Maintenance @@ -66,13 +66,13 @@ During a documentation build: ## Benefits -* **Single source of truth** - One file to check for all available documentation -* **Performance** - Fast lookup without scanning the entire Link Service -* **Automation** - Maintained automatically via Lambda functions -* **Resilience** - Represents only successful builds with valid Link Indexes +* **Single source of truth** - One file to check for all available documentation. +* **Performance** - Fast lookup without scanning the entire Link Service. +* **Automation** - Maintained automatically via Lambda functions. +* **Resilience** - Represents only successful builds with valid Link Indexes. ## Related concepts -* [Link Service](link-service.md) - Where the Link Catalog is stored -* [Link Index](link-index.md) - The files cataloged by the Link Catalog -* [Assembled Documentation](assembled-documentation.md) - Uses the Link Catalog to coordinate builds +* [Link Service](link-service.md) - Where the Link Catalog is stored. +* [Link Index](link-index.md) - The files cataloged by the Link Catalog. +* [Assembled Documentation](assembled-documentation.md) - Uses the Link Catalog to coordinate builds. diff --git a/docs/building-blocks/link-index.md b/docs/building-blocks/link-index.md index a0b2a4a96..363a672d5 100644 --- a/docs/building-blocks/link-index.md +++ b/docs/building-blocks/link-index.md @@ -10,18 +10,18 @@ A **Link Index** is a JSON file (`links.json`) that contains all the linkable re The Link Index enables: -* **Cross-repository linking** - Other documentation sets can link to your content -* **Link validation** - Validate that links to your content are correct -* **Inbound link detection** - Know when other repositories link to your content -* **Distributed builds** - Build documentation independently while maintaining link integrity +* **Cross-repository linking** - Other documentation sets can link to your content. +* **Link validation** - Validate that links to your content are correct. +* **Inbound link detection** - Know when other repositories link to your content. +* **Distributed builds** - Build documentation independently while maintaining link integrity. ## Structure Each repository branch gets its own Link Index file in the [Link Service](link-service.md), organized by: -* **Organization** - e.g., `elastic` -* **Repository** - e.g., `elasticsearch` -* **Branch** - e.g., `main`, `8.x`, `7.17` +* **Organization** - e.g., `elastic`. +* **Repository** - e.g., `elasticsearch`. +* **Branch** - e.g., `main`, `8.x`, `7.17`. ## Example @@ -29,11 +29,11 @@ View [Elasticsearch's main branch Link Index](https://elastic-docs-link-index.s3 The Link Index contains: -* All documentation pages in the repository -* Headings within those pages -* Anchors and linkable elements -* Version information -* Metadata about the build +* All documentation pages in the repository. +* Headings within those pages. +* Anchors and linkable elements. +* Version information. +* Metadata about the build. ## Generation @@ -80,7 +80,7 @@ https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/{org}/{repo}/{branch} ## Related concepts -* [Link Service](link-service.md) - Where Link Index files are stored -* [Link Catalog](link-catalog.md) - Catalog of all Link Index files -* [Outbound Cross-links](outbound-cross-links.md) - Links that use the Link Index -* [Inbound Cross-links](inbound-cross-links.md) - Links to resources in the Link Index +* [Link Service](link-service.md) - Where Link Index files are stored. +* [Link Catalog](link-catalog.md) - Catalog of all Link Index files. +* [Outbound Cross-links](outbound-cross-links.md) - Links that use the Link Index. +* [Inbound Cross-links](inbound-cross-links.md) - Links to resources in the Link Index. diff --git a/docs/building-blocks/link-service.md b/docs/building-blocks/link-service.md index 7d173f212..691aad532 100644 --- a/docs/building-blocks/link-service.md +++ b/docs/building-blocks/link-service.md @@ -7,7 +7,7 @@ navigation_title: Link service The **Link Service** is the central location that stores: * All [Link Index](link-index.md) files for all the repositories and branches that are published. -* The [Link Catalog](link-catalog.md), a single JSON file that contains references to all the `Link Index` files. +* The [Link Catalog](link-catalog.md), a single JSON file that contains references to all the `Link Index` files. We only have one link service today for all public documentation. @@ -17,18 +17,18 @@ We only have one link service today for all public documentation. The Link Service is implemented as: -* **Storage** - An S3 bucket -* **CDN** - CloudFront fronting the S3 bucket for fast global access -* **Access** - Publicly accessible for read operations +* **Storage** - An S3 bucket. +* **CDN** - CloudFront fronting the S3 bucket for fast global access. +* **Access** - Publicly accessible for read operations. ## Purpose The Link Service enables: -* **Distributed validation** - Any documentation build can validate cross-repository links without cloning all repositories -* **Link discovery** - Find what resources are available in other repositories -* **Build resilience** - Assembler builds can reference the last known good state of each repository -* **Decentralized publishing** - Each repository publishes its own Link Index independently +* **Distributed validation** - Any documentation build can validate cross-repository links without cloning all repositories. +* **Link discovery** - Find what resources are available in other repositories. +* **Build resilience** - Assembler builds can reference the last known good state of each repository. +* **Decentralized publishing** - Each repository publishes its own Link Index independently. ## URL structure @@ -39,8 +39,8 @@ https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/{org}/{repo}/{branch} ``` For example: -* [Elasticsearch main branch](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) -* [Kibana main branch](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/kibana/main/links.json) +* [Elasticsearch main branch](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json). +* [Kibana main branch](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/kibana/main/links.json). ## Publishing process @@ -55,12 +55,12 @@ When a documentation build completes successfully on a default integration branc During both local and CI builds, `docs-builder`: -* Fetches relevant Link Index files from the Link Service -* Validates outbound cross-links against these indexes -* Validates that inbound cross-links won't be broken by local changes +* Fetches relevant Link Index files from the Link Service. +* Validates outbound cross-links against these indexes. +* Validates that inbound cross-links won't be broken by local changes. ## Related concepts -* [Link Index](link-index.md) - The files stored in the Link Service -* [Link Catalog](link-catalog.md) - The catalog of all Link Index files -* [Distributed Documentation](distributed-documentation.md) - Why the Link Service exists +* [Link Index](link-index.md) - The files stored in the Link Service. +* [Link Catalog](link-catalog.md) - The catalog of all Link Index files. +* [Distributed Documentation](distributed-documentation.md) - Why the Link Service exists. diff --git a/docs/building-blocks/outbound-cross-links.md b/docs/building-blocks/outbound-cross-links.md index 07353b1e3..58fe00bfd 100644 --- a/docs/building-blocks/outbound-cross-links.md +++ b/docs/building-blocks/outbound-cross-links.md @@ -10,10 +10,10 @@ navigation_title: Outbound cross-links Outbound cross-links allow you to: -* Link to documentation in other repositories -* Maintain those links even as the target repository evolves -* Validate links during local builds -* Get warnings if target content is moved or deleted +* Link to documentation in other repositories. +* Maintain those links even as the target repository evolves. +* Validate links during local builds. +* Get warnings if target content is moved or deleted. ## Syntax @@ -50,8 +50,8 @@ When `docs-builder` encounters a cross-link: During a build, `docs-builder`: -* **Validates immediately** - Checks all outbound cross-links against locally fetched [Link Index](link-index.md) files -* **Reports errors** - Reports errors about broken links before you publish +* **Validates immediately** - Checks all outbound cross-links against locally fetched [Link Index](link-index.md) files. +* **Reports errors** - Reports errors about broken links before you publish. ## Configuration @@ -86,9 +86,9 @@ The explicit opt-in prevents each repository build having the fetch all the link ``` The cross-link syntax is resilient to: -* URL structure changes -* File moves (if redirects are configured) -* Version differences +* URL structure changes. +* File moves (if redirects are configured). +* Version differences. ### Link to headings @@ -100,6 +100,6 @@ You can link to specific headings within a page: ## Related concepts -* [Inbound Cross-links](inbound-cross-links.md) - Links from other repositories to yours -* [Link Index](link-index.md) - How cross-links are resolved -* [Links syntax](../syntax/links.md) - Complete link syntax documentation +* [Inbound Cross-links](inbound-cross-links.md) - Links from other repositories to yours. +* [Link Index](link-index.md) - How cross-links are resolved. +* [Links syntax](../syntax/links.md) - Complete link syntax documentation. diff --git a/docs/cli/assembler/assemble.md b/docs/cli/assembler/assemble.md index e8c5bcc8a..13058aa0c 100644 --- a/docs/cli/assembler/assemble.md +++ b/docs/cli/assembler/assemble.md @@ -30,7 +30,7 @@ docs-builder assembler serve Where this command really shines is when you want to create a temporary workspace folder to validate: -* changes to [site wide configuration](../../configure/site/index.md) +* changes to [site wide configuration](../../configure/site/index.md). * changes to one or more repositories and their effect on the assembler build. To do that inside an empty folder, call: diff --git a/docs/cli/assembler/assembler-config-init.md b/docs/cli/assembler/assembler-config-init.md index cc23be77a..d1c5e4eb4 100644 --- a/docs/cli/assembler/assembler-config-init.md +++ b/docs/cli/assembler/assembler-config-init.md @@ -8,9 +8,9 @@ Sources the configuration from [The `config` folder on the `main` branch of `doc By default, the configuration is placed in a special application folder as its main usages is to be used by CI environments. -* OSX: `~/Library/Application Support/docs-builder` [NSApplicationSupportDirectory](https://developer.apple.com/documentation/foundation/filemanager/searchpathdirectory/applicationsupportdirectory) -* Linux: `~/.config/docs-builder` -* {icon}`logo_windows` Windows: `%APPDATA%\docs-builder` +* OSX: `~/Library/Application Support/docs-builder` [NSApplicationSupportDirectory](https://developer.apple.com/documentation/foundation/filemanager/searchpathdirectory/applicationsupportdirectory). +* Linux: `~/.config/docs-builder`. +* {icon}`logo_windows` Windows: `%APPDATA%\docs-builder`. You can also use the `--local` option to save the configuration locally in the current working directory. This exposes a great way to assemble the full documentation locally in an empty directory. diff --git a/docs/cli/assembler/assembler-content-source-match.md b/docs/cli/assembler/assembler-content-source-match.md index 67781a42a..ab955ff32 100644 --- a/docs/cli/assembler/assembler-content-source-match.md +++ b/docs/cli/assembler/assembler-content-source-match.md @@ -6,9 +6,9 @@ navigation_title: "content-source match" This command is used to match a repository and branch to a content source it will emit the following `$GITHUB_OUTPUT`: -* `content-source-match` - whether the branch is a configured content source -* `content-source-next` - whether the branch is the next content source -* `content-source-current` - whether the branch is the current content source +* `content-source-match` - whether the branch is a configured content source. +* `content-source-next` - whether the branch is the next content source. +* `content-source-current` - whether the branch is the current content source. * `content-source-speculative` - whether the branch is a speculative content source. #### Speculative builds diff --git a/docs/cli/docset/build.md b/docs/cli/docset/build.md index d300c6ee9..21b29f687 100644 --- a/docs/cli/docset/build.md +++ b/docs/cli/docset/build.md @@ -4,8 +4,8 @@ Builds a local documentation set folder. Repeated invocations will do incremental builds of only the changed files unless: -* The base branch has changed -* The state file in the output folder has been removed +* The base branch has changed. +* The state file in the output folder has been removed. * The `--force` option is specified. ## Usage diff --git a/docs/cli/docset/diff-validate.md b/docs/cli/docset/diff-validate.md index 02c97d84b..59513c5f9 100644 --- a/docs/cli/docset/diff-validate.md +++ b/docs/cli/docset/diff-validate.md @@ -4,7 +4,7 @@ Gathers the local changes by inspecting the git log, stashed and unstashed chang It currently validates the following: -* Ensures that renames and deletions are reflected in [redirects.yml](../../contribute/redirects.md) +* Ensures that renames and deletions are reflected in [redirects.yml](../../contribute/redirects.md). ## Usage diff --git a/docs/configure/content-set/index.md b/docs/configure/content-set/index.md index f813d3de2..1b02e4c17 100644 --- a/docs/configure/content-set/index.md +++ b/docs/configure/content-set/index.md @@ -15,6 +15,6 @@ A content set in `docs-builder` is equivalent to an AsciiDoc book. At this level ## Learn more -* [File structure](./file-structure.md) -* [Navigation](./navigation.md) -* [Attributes](./attributes.md) \ No newline at end of file +* [File structure](./file-structure.md). +* [Navigation](./navigation.md). +* [Attributes](./attributes.md). \ No newline at end of file diff --git a/docs/configure/index.md b/docs/configure/index.md index bdc318f7d..4f7a4b298 100644 --- a/docs/configure/index.md +++ b/docs/configure/index.md @@ -20,8 +20,8 @@ When working with `docs-builder`, there are three levels at which you can config At the site level, you can configure: -* Content sources: where files live -* Global navigation: how navigations are compiled and presented to users +* Content sources: where files live. +* Global navigation: how navigations are compiled and presented to users. [Site configuration](./site/index.md) @@ -29,8 +29,8 @@ At the site level, you can configure: At the content set level, you can configure: -* Content-set-level and sub-content-set-level navigation: how smaller groups of files are organized and presented to users -* Attributes: variables that will be substituted at build-time for pre-defined values +* Content-set-level and sub-content-set-level navigation: how smaller groups of files are organized and presented to users. +* Attributes: variables that will be substituted at build-time for pre-defined values. [Content-set configuration](./content-set/index.md) @@ -38,6 +38,6 @@ At the content set level, you can configure: At the page level, you can configure: -* Frontmatter that influences on-page UX to benefit the user in some way +* Frontmatter that influences on-page UX to benefit the user in some way. [Page configuration](./page.md) \ No newline at end of file diff --git a/docs/configure/site/content.md b/docs/configure/site/content.md index ea344a713..4737cb65f 100644 --- a/docs/configure/site/content.md +++ b/docs/configure/site/content.md @@ -6,10 +6,10 @@ navigation_title: assembler.yml The [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file defines the global documentation site: -* `environments` -* `shared_configuration` -* narrative repository configuration -* reference repository configurations +* `environments`. +* `shared_configuration`. +* narrative repository configuration. +* reference repository configurations. ## `environments` diff --git a/docs/contribute/cumulative-docs/badge-placement.md b/docs/contribute/cumulative-docs/badge-placement.md index abd5cdc5e..f9d127e3a 100644 --- a/docs/contribute/cumulative-docs/badge-placement.md +++ b/docs/contribute/cumulative-docs/badge-placement.md @@ -26,11 +26,11 @@ version and deployment type differences in your docs: % Source: Brandon's PR review comment At a high level, you should follow these badge placement principles: -* Place badges where they're most visible but least disruptive to reading flow -* Consider scanning patterns - readers often scan for relevant information -* Ensure badges don't break the natural flow of content -* Use consistent placement patterns within similar content types -* Consider visual grouping - readers must naturally associate the badge with its corresponding content, no more, no less +* Place badges where they're most visible but least disruptive to reading flow. +* Consider scanning patterns - readers often scan for relevant information. +* Ensure badges don't break the natural flow of content. +* Use consistent placement patterns within similar content types. +* Consider visual grouping - readers must naturally associate the badge with its corresponding content, no more, no less. ## Placement in specific elements diff --git a/docs/contribute/cumulative-docs/example-scenarios.md b/docs/contribute/cumulative-docs/example-scenarios.md index c780a0558..31ef9442a 100644 --- a/docs/contribute/cumulative-docs/example-scenarios.md +++ b/docs/contribute/cumulative-docs/example-scenarios.md @@ -34,8 +34,8 @@ page level in the frontmatter, use section-level `applies_to` badges.