From f0ad3fee722f1109ade55077f615c15dcad66f16 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 30 Sep 2025 13:27:04 +0200 Subject: [PATCH 1/3] Create top-level contribute-docs section, move API docs, fix nav duplication --- .../api-docs/checklist.md | 2 +- .../api-docs/guidelines.md | 4 ++-- .../api-docs/help.md | 4 ++-- .../api-docs/images/api-docs-general-pipeline.png | Bin .../api-docs/images/es-api-docs-pipeline.png | Bin .../api-docs/index.md | 0 .../api-docs/organize-annotate.md | 0 .../api-docs/overview.md | 4 ++-- .../api-docs/quickstart.md | 0 contribute-docs/api-docs/toc.yml | 9 +++++++++ .../api-docs/workflows.md | 0 {extend/contribute => contribute-docs}/index.md | 0 contribute-docs/toc.yml | 11 +++++++++++ docset.yml | 1 + extend/index.md | 2 +- extend/toc.yml | 14 +------------- redirects.yml | 13 ++++++++++++- 17 files changed, 42 insertions(+), 22 deletions(-) rename {extend/contribute => contribute-docs}/api-docs/checklist.md (95%) rename {extend/contribute => contribute-docs}/api-docs/guidelines.md (98%) rename {extend/contribute => contribute-docs}/api-docs/help.md (92%) rename {extend/contribute => contribute-docs}/api-docs/images/api-docs-general-pipeline.png (100%) rename {extend/contribute => contribute-docs}/api-docs/images/es-api-docs-pipeline.png (100%) rename {extend/contribute => contribute-docs}/api-docs/index.md (100%) rename {extend/contribute => contribute-docs}/api-docs/organize-annotate.md (100%) rename {extend/contribute => contribute-docs}/api-docs/overview.md (97%) rename {extend/contribute => contribute-docs}/api-docs/quickstart.md (100%) create mode 100644 contribute-docs/api-docs/toc.yml rename {extend/contribute => contribute-docs}/api-docs/workflows.md (100%) rename {extend/contribute => contribute-docs}/index.md (100%) create mode 100644 contribute-docs/toc.yml diff --git a/extend/contribute/api-docs/checklist.md b/contribute-docs/api-docs/checklist.md similarity index 95% rename from extend/contribute/api-docs/checklist.md rename to contribute-docs/api-docs/checklist.md index a9099fa8eb..3909f018de 100644 --- a/extend/contribute/api-docs/checklist.md +++ b/contribute-docs/api-docs/checklist.md @@ -28,6 +28,6 @@ Use this checklist to verify the quality, completeness, and consistency of your ## Quality assurance - Preview your changes locally before submitting (see [Contribute locally: Elasticsearch quickstart](./quickstart.md)) -- [Lint your API docs](guidelines.md#lint-your-api-docs) to identify and fix issues +- [Lint your API docs](./guidelines.md#lint-your-api-docs) to identify and fix issues - Check all links to ensure they work correctly - Ensure examples are realistic and error-free \ No newline at end of file diff --git a/extend/contribute/api-docs/guidelines.md b/contribute-docs/api-docs/guidelines.md similarity index 98% rename from extend/contribute/api-docs/guidelines.md rename to contribute-docs/api-docs/guidelines.md index 20a8678271..d60d374182 100644 --- a/extend/contribute/api-docs/guidelines.md +++ b/contribute-docs/api-docs/guidelines.md @@ -510,7 +510,7 @@ paths: :::{tab-item} Elasticsearch :sync: elasticsearch -**External documentation links** use the `@ext_doc_id` annotation to connect to narrative guides. This is transformed into an OpenAPI `externalDocs` field in the [compilation process](overview.md#example-elasticsearch): +**External documentation links** use the `@ext_doc_id` annotation to connect to narrative guides. This is transformed into an OpenAPI `externalDocs` field in the [compilation process](./overview.md#example-elasticsearch): ```ts /** @@ -621,7 +621,7 @@ The [Elasticsearch API specification](https://github.com/elastic/elasticsearch-s - **Spectral**: Configuration in `.spectral.yaml` - **Redocly**: Configuration in `redocly.yaml` -Refer to [the Elasticsearch quickstart](quickstart.md#lint-your-docs) to learn how to run the linter locally. +Refer to [the Elasticsearch quickstart](./quickstart.md#lint-your-docs) to learn how to run the linter locally. :::: :::: diff --git a/extend/contribute/api-docs/help.md b/contribute-docs/api-docs/help.md similarity index 92% rename from extend/contribute/api-docs/help.md rename to contribute-docs/api-docs/help.md index fceffef459..00dd7c6cbf 100644 --- a/extend/contribute/api-docs/help.md +++ b/contribute-docs/api-docs/help.md @@ -2,7 +2,7 @@ The API docs workflow is pretty complicated, and there's lots of moving parts. It takes a village to produce excellent API docs, so don't hesitate to ask for help if you get stuck or have questions. -If you're not sure who owns a specific API, check out the [API ownership table](workflows.md) to find the right team. +If you're not sure who owns a specific API, check out the [API ownership table](./workflows.md) to find the right team. ## Report issues @@ -10,7 +10,7 @@ If you're not sure who owns a specific API, check out the [API ownership table]( When you find a bug or gap in the API docs: -- If you're comfortable making the change, open a PR in the [relevant repo](workflows.md) +- If you're comfortable making the change, open a PR in the [relevant repo](./workflows.md) - Alternatively, open an issue in either: - [elastic/docs-content](https://www.github.com/elastic/docs-content/issues) (public repo) - [elastic/docs-content-internal](https://www.github.com/elastic/docs-content-internal/issues) (Elastic employees only) diff --git a/extend/contribute/api-docs/images/api-docs-general-pipeline.png b/contribute-docs/api-docs/images/api-docs-general-pipeline.png similarity index 100% rename from extend/contribute/api-docs/images/api-docs-general-pipeline.png rename to contribute-docs/api-docs/images/api-docs-general-pipeline.png diff --git a/extend/contribute/api-docs/images/es-api-docs-pipeline.png b/contribute-docs/api-docs/images/es-api-docs-pipeline.png similarity index 100% rename from extend/contribute/api-docs/images/es-api-docs-pipeline.png rename to contribute-docs/api-docs/images/es-api-docs-pipeline.png diff --git a/extend/contribute/api-docs/index.md b/contribute-docs/api-docs/index.md similarity index 100% rename from extend/contribute/api-docs/index.md rename to contribute-docs/api-docs/index.md diff --git a/extend/contribute/api-docs/organize-annotate.md b/contribute-docs/api-docs/organize-annotate.md similarity index 100% rename from extend/contribute/api-docs/organize-annotate.md rename to contribute-docs/api-docs/organize-annotate.md diff --git a/extend/contribute/api-docs/overview.md b/contribute-docs/api-docs/overview.md similarity index 97% rename from extend/contribute/api-docs/overview.md rename to contribute-docs/api-docs/overview.md index 043e0722f7..d4211caec9 100644 --- a/extend/contribute/api-docs/overview.md +++ b/contribute-docs/api-docs/overview.md @@ -3,10 +3,10 @@ This page explains at a high-level how API docs work at Elastic today, with context on how this differs from our previous approaches and where we're heading. Use this page to understand the core primitives and workflows that apply across all Elastic teams, so you can contribute effectively. :::{tip} -The API docs use a different system to the main Elastic docs. Refer to [Contribute to Elastic docs](../../contribute/index.md) for an overview of the two systems. +The API docs use a different system to the main Elastic docs. Refer to [Contribute to Elastic docs](../index.md) for an overview of the two systems. ::: -While the implementation details [vary significantly across teams](workflows.md), at a high level: +While the implementation details [vary significantly across teams](./workflows.md), at a high level: - We use [OpenAPI](https://spec.openapis.org/oas/latest.html) files to generate REST API documentation - Our API docs are hosted by [Bump.sh](https://bump.sh/) diff --git a/extend/contribute/api-docs/quickstart.md b/contribute-docs/api-docs/quickstart.md similarity index 100% rename from extend/contribute/api-docs/quickstart.md rename to contribute-docs/api-docs/quickstart.md diff --git a/contribute-docs/api-docs/toc.yml b/contribute-docs/api-docs/toc.yml new file mode 100644 index 0000000000..f83e66dbe0 --- /dev/null +++ b/contribute-docs/api-docs/toc.yml @@ -0,0 +1,9 @@ +toc: + - file: index.md + - file: overview.md + - file: checklist.md + - file: guidelines.md + - file: organize-annotate.md + - file: quickstart.md + - file: workflows.md + - file: help.md diff --git a/extend/contribute/api-docs/workflows.md b/contribute-docs/api-docs/workflows.md similarity index 100% rename from extend/contribute/api-docs/workflows.md rename to contribute-docs/api-docs/workflows.md diff --git a/extend/contribute/index.md b/contribute-docs/index.md similarity index 100% rename from extend/contribute/index.md rename to contribute-docs/index.md diff --git a/contribute-docs/toc.yml b/contribute-docs/toc.yml new file mode 100644 index 0000000000..7aed8c5d7c --- /dev/null +++ b/contribute-docs/toc.yml @@ -0,0 +1,11 @@ +toc: + - file: index.md + - file: api-docs/index.md + children: + - file: api-docs/overview.md + - file: api-docs/checklist.md + - file: api-docs/guidelines.md + - file: api-docs/organize-annotate.md + - file: api-docs/quickstart.md + - file: api-docs/workflows.md + - file: api-docs/help.md \ No newline at end of file diff --git a/docset.yml b/docset.yml index 1060f588db..b8ef13e290 100644 --- a/docset.yml +++ b/docset.yml @@ -78,6 +78,7 @@ toc: - toc: troubleshoot - toc: release-notes - toc: reference + - toc: contribute-docs - toc: extend - file: archive.md - file: versions.md diff --git a/extend/index.md b/extend/index.md index bf6c6b8f43..0b914061cc 100644 --- a/extend/index.md +++ b/extend/index.md @@ -55,4 +55,4 @@ Ready to get started? Explore the [Elastic API Reference]({{apis}}). ## Contributing to Elastic documentation -You can contribute to the Elastic documentation in several ways. Refer to [Contribute to Elastic documentation](./contribute/index.md) for an overview. +You can contribute to the Elastic documentation in several ways. Refer to [Contribute to Elastic documentation](./../contribute-docs/index.md) for an overview. diff --git a/extend/toc.yml b/extend/toc.yml index 01bd216017..f2ab236796 100644 --- a/extend/toc.yml +++ b/extend/toc.yml @@ -1,14 +1,2 @@ toc: - - file: index.md - children: - - file: contribute/index.md - children: - - file: contribute/api-docs/index.md - children: - - file: contribute/api-docs/overview.md - - file: contribute/api-docs/checklist.md - - file: contribute/api-docs/guidelines.md - - file: contribute/api-docs/organize-annotate.md - - file: contribute/api-docs/quickstart.md - - file: contribute/api-docs/workflows.md - - file: contribute/api-docs/help.md \ No newline at end of file + - file: index.md \ No newline at end of file diff --git a/redirects.yml b/redirects.yml index 33c9971abc..8c712f6773 100644 --- a/redirects.yml +++ b/redirects.yml @@ -467,4 +467,15 @@ redirects: 'solutions/observability/apm/jaeger.md': 'solutions/observability/apm/ingest/jaeger.md' 'solutions/observability/apm/monitor-aws-lambda-functions.md': 'solutions/observability/apm/ingest/monitor-aws-lambda-functions.md' # Related to https://github.com/elastic/docs-content/pull/3142 - 'deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md': 'deploy-manage/deploy/self-managed/important-settings-configuration.md' \ No newline at end of file + 'deploy-manage/deploy/self-managed/networkaddress-cache-ttl.md': 'deploy-manage/deploy/self-managed/important-settings-configuration.md' + +# Related to contribute-docs restructure - moved from extend/contribute/ to contribute-docs/ + 'extend/contribute/index.md': 'contribute-docs/index.md' + 'extend/contribute/api-docs/index.md': 'contribute-docs/api-docs/index.md' + 'extend/contribute/api-docs/overview.md': 'contribute-docs/api-docs/overview.md' + 'extend/contribute/api-docs/checklist.md': 'contribute-docs/api-docs/checklist.md' + 'extend/contribute/api-docs/guidelines.md': 'contribute-docs/api-docs/guidelines.md' + 'extend/contribute/api-docs/organize-annotate.md': 'contribute-docs/api-docs/organize-annotate.md' + 'extend/contribute/api-docs/quickstart.md': 'contribute-docs/api-docs/quickstart.md' + 'extend/contribute/api-docs/workflows.md': 'contribute-docs/api-docs/workflows.md' + 'extend/contribute/api-docs/help.md': 'contribute-docs/api-docs/help.md' \ No newline at end of file From f8130f547e8c98139d6a48a0bebd4a6c62acd380 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 30 Sep 2025 16:59:21 +0200 Subject: [PATCH 2/3] Updatenav title --- contribute-docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute-docs/index.md b/contribute-docs/index.md index 3dfb878591..0eabc633f8 100644 --- a/contribute-docs/index.md +++ b/contribute-docs/index.md @@ -1,5 +1,5 @@ --- -navigation_title: Contribute to docs +navigation_title: Contribute to the docs --- # Contribute to Elastic documentation From 24b3b8e05663be62354534c54dbecb043bd9cc96 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 3 Oct 2025 10:27:05 +0200 Subject: [PATCH 3/3] restructure API docs TOC and remove redundant nested toc --- contribute-docs/api-docs/toc.yml | 9 --------- contribute-docs/toc.yml | 17 +++++++++-------- 2 files changed, 9 insertions(+), 17 deletions(-) delete mode 100644 contribute-docs/api-docs/toc.yml diff --git a/contribute-docs/api-docs/toc.yml b/contribute-docs/api-docs/toc.yml deleted file mode 100644 index f83e66dbe0..0000000000 --- a/contribute-docs/api-docs/toc.yml +++ /dev/null @@ -1,9 +0,0 @@ -toc: - - file: index.md - - file: overview.md - - file: checklist.md - - file: guidelines.md - - file: organize-annotate.md - - file: quickstart.md - - file: workflows.md - - file: help.md diff --git a/contribute-docs/toc.yml b/contribute-docs/toc.yml index 7aed8c5d7c..0dca1973ee 100644 --- a/contribute-docs/toc.yml +++ b/contribute-docs/toc.yml @@ -1,11 +1,12 @@ toc: - file: index.md - - file: api-docs/index.md + - folder: api-docs children: - - file: api-docs/overview.md - - file: api-docs/checklist.md - - file: api-docs/guidelines.md - - file: api-docs/organize-annotate.md - - file: api-docs/quickstart.md - - file: api-docs/workflows.md - - file: api-docs/help.md \ No newline at end of file + - file: index.md + - file: overview.md + - file: checklist.md + - file: guidelines.md + - file: organize-annotate.md + - file: quickstart.md + - file: workflows.md + - file: help.md \ No newline at end of file