[docs] Prepare for docs-assembler #125118

colleenmcginnis · 2025-03-18T15:42:52Z

Related to elastic/docs-content#792

Restructure content and create toc.yml files needed by docs-assembler.

Restructured content so all toc.yml can be 2 or fewer levels below the docs/ directory:

I got rid of the docs/reference/data-analysis directory and put the subdirectories up a level (docs/reference/data-analysis/aggregations → docs/reference/aggregations and docs/reference/data-analysis/text-analysis → docs/reference/text-analysis).
I got rid of the docs/reference/ingestion-tools directory and put the subdirectories up a level (docs/reference/ingestion-tools/enrich-processor → docs/reference/enrich-processor and docs/reference/ingestion-tools/search-connectors → docs/reference/search-connectors).

Because of how we need to distribute files throughout the new IA, I think we need to create 9 unique toc.yml files:

docs/reference/aggregations/toc.yml
- After moving all the content that lived at docs/reference/data-analysis/aggregations/* to docs/reference/aggregations/*, I added a toc.yml file that contains just the pages related to aggregations to be inserted into the Data analysis section of the overall IA.
docs/reference/community-contributed/toc.yml
- I moved docs/reference/community-contributed.md to docs/reference/community-contributed/index.md so we could also add a toc.yml file with one page to be inserted into the Elasticsearch and index management / Clients section of the overall IA.
docs/reference/elasticsearch/toc.yml
- I created a new toc.yml that contains just the pages that belong at the top level of the Elasticsearch and index management section in the overall IA.
docs/reference/elasticsearch-plugins/toc.yml
- I created a new toc.yml that contains just the pages that belong in the Elasticsearch plugins section in the overall IA.
docs/reference/enrich-processor/toc.yml
- After moving all the content that lived at docs/reference/ingestion-docs/enrich-processor/* to docs/reference/enrich-processor/*, I added a toc.yml file that contains just the pages related to enrich processors to be inserted into the Ingestion tools section of the overall IA.
docs/reference/query-languages/toc.yml
- I created a new toc.yml that contains just the pages that belong in the Query languages section in the overall IA.
docs/reference/scripting-languages/toc.yml
- I created a new toc.yml that contains just the pages that belong in the Scripting languages section in the overall IA.
docs/reference/search-connectors/toc.yml
- After moving all the content that lived at docs/reference/ingestion-docs/search-connectors/* to docs/reference/search-connectors/*, I added a toc.yml file that contains just the pages related to search connectors to be inserted into the Ingestion tools section of the overall IA.
docs/reference/text-analysis/toc.yml
- After moving all the content that lived at docs/reference/data-analysis/text-analysis/* to docs/reference/text-analysis/*, I added a toc.yml file that contains just the pages related to text analysis to be inserted into the Data analysis section of the overall IA.

cc @Mpdreamz

Mpdreamz · 2025-03-18T21:51:51Z

docs/docset.yml

+  - file: reference/index.md
+    children:
+    - toc: reference/elasticsearch
+    - toc: reference/community-contributed
+    - toc: reference/enrich-processor
+    - toc: reference/search-connectors
+    - toc: reference/elasticsearch-plugins
+    - toc: reference/query-languages
+    - toc: reference/scripting-languages
+    - toc: reference/text-analysis
+    - toc: reference/aggregations


Suggested change

- file: reference/index.md

children:

- toc: reference/elasticsearch

- toc: reference/community-contributed

- toc: reference/enrich-processor

- toc: reference/search-connectors

- toc: reference/elasticsearch-plugins

- toc: reference/query-languages

- toc: reference/scripting-languages

- toc: reference/text-analysis

- toc: reference/aggregations

- toc: reference

with reference/toc.yml holding:

children: - toc: elasticsearch - toc: community-contributed - toc: enrich-processor - toc: search-connectors - toc: elasticsearch-plugins - toc: query-languages - toc: scripting-languages - toc: text-analysis - toc: aggregations

Otherwise it will trip the new validations: elastic/docs-builder#767

I thought toc.yml files couldn't contain toc:s (only docset.yml can use toc:) or does elastic/docs-builder#767 also change that, too?

I just did this for now 1b4df48.

there is no restriction on files origin, just depth so toc.yml file can hold toc.yml files as long as max_toc_depth is adhered too.

elasticsearchmachine · 2025-03-19T18:52:24Z

Pinging @elastic/es-docs (Team:Docs)

leemthompo · 2025-03-20T15:41:32Z

docs/reference/query-languages/toc.yml
I created a new toc.yml that contains just the pages that belong in the Query languages section in the overall IA.

@craigtaverner is this going to impact anything on your side? FYI some paths have been updated for a few esql pages

leemthompo

Folder rationalization and link path updates LGTM

leemthompo · 2025-03-20T18:47:51Z

💚 All backports created successfully

Status	Branch	Result
✅	9.0

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

* reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images (cherry picked from commit 9bcd595) # Conflicts: # docs/reference/aggregations/search-aggregations-pipeline-bucket-script-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-cumulative-cardinality-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-cumulative-sum-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-derivative-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-extended-stats-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-max-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-min-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-percentiles-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-stats-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-sum-bucket-aggregation.md # docs/reference/query-languages/esql/esql-commands.md # docs/reference/query-languages/esql/esql-lookup-join.md # docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md # docs/reference/query-languages/images/esql-lookup-join.png # docs/reference/query-languages/toc.yml # docs/reference/search-connectors/es-connectors-run-from-docker.md # docs/reference/text-analysis/analysis-apostrophe-tokenfilter.md # docs/reference/toc.yml

* [docs] Prepare for docs-assembler (#125118) * reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images (cherry picked from commit 9bcd595) # Conflicts: # docs/reference/aggregations/search-aggregations-pipeline-bucket-script-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-cumulative-cardinality-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-cumulative-sum-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-derivative-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-extended-stats-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-max-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-min-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-percentiles-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-stats-bucket-aggregation.md # docs/reference/aggregations/search-aggregations-pipeline-sum-bucket-aggregation.md # docs/reference/query-languages/esql/esql-commands.md # docs/reference/query-languages/esql/esql-lookup-join.md # docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md # docs/reference/query-languages/images/esql-lookup-join.png # docs/reference/query-languages/toc.yml # docs/reference/search-connectors/es-connectors-run-from-docker.md # docs/reference/text-analysis/analysis-apostrophe-tokenfilter.md # docs/reference/toc.yml * remove markers --------- Co-authored-by: Colleen McGinnis <[email protected]>

* reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images

Clean up some Elasticsearch redirects after elastic/elasticsearch#125118

* reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images

colleenmcginnis added 2 commits March 14, 2025 16:45

reorg files for docs-assembler and create toc.yml files

72b62ee

catch up to main, fix build errors

a467668

colleenmcginnis added >docs General docs changes Team:Docs Meta label for docs team documentation labels Mar 18, 2025

colleenmcginnis self-assigned this Mar 18, 2025

elasticsearchmachine added v9.1.0 external-contributor Pull request authored by a developer outside the Elasticsearch team labels Mar 18, 2025

fix build error, add redirects

311bb44

Mpdreamz requested changes Mar 18, 2025

View reviewed changes

only toc

1b4df48

Mpdreamz mentioned this pull request Mar 19, 2025

feature/assembler global toc elastic/docs-builder#770

Merged

move images

7b9ec0b

colleenmcginnis requested a review from leemthompo March 19, 2025 16:29

colleenmcginnis changed the title ~~[docs] [work in progress] Prepare for docs-assembler~~ [docs] Prepare for docs-assembler Mar 19, 2025

Merge branch 'main' into docs-assembler-prep

2b7cd19

Mpdreamz mentioned this pull request Mar 19, 2025

Update navigation.yml elastic/docs-builder#780

Merged

colleenmcginnis requested a review from Mpdreamz March 19, 2025 18:51

colleenmcginnis marked this pull request as ready for review March 19, 2025 18:52

Mpdreamz approved these changes Mar 20, 2025

View reviewed changes

leemthompo added auto-backport Automatically create backport pull requests when merged v9.0.0 labels Mar 20, 2025

leemthompo approved these changes Mar 20, 2025

View reviewed changes

colleenmcginnis merged commit 9bcd595 into elastic:main Mar 20, 2025
6 checks passed

colleenmcginnis deleted the docs-assembler-prep branch March 20, 2025 17:09

leemthompo mentioned this pull request Mar 20, 2025

[9.0] [docs] Prepare for docs-assembler (#125118) #125339

Merged

afoucret pushed a commit to afoucret/elasticsearch that referenced this pull request Mar 21, 2025

[docs] Prepare for docs-assembler (elastic#125118)

37872a5

* reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images

smalyshev pushed a commit to smalyshev/elasticsearch that referenced this pull request Mar 21, 2025

[docs] Prepare for docs-assembler (elastic#125118)

6a7d107

* reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images

colleenmcginnis mentioned this pull request Mar 26, 2025

Clean up some Elasticsearch redirects pre-assembler elastic/docs-content#929

Merged

colleenmcginnis added a commit to elastic/docs-content that referenced this pull request Mar 26, 2025

Clean up some Elasticsearch redirects pre-assembler (#929)

c7cc2d4

Clean up some Elasticsearch redirects after elastic/elasticsearch#125118

omricohenn pushed a commit to omricohenn/elasticsearch that referenced this pull request Mar 28, 2025

[docs] Prepare for docs-assembler (elastic#125118)

36ac8c5

* reorg files for docs-assembler and create toc.yml files * fix build error, add redirects * only toc * move images

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[docs] Prepare for docs-assembler #125118

[docs] Prepare for docs-assembler #125118

Uh oh!

colleenmcginnis commented Mar 18, 2025 •

edited

Loading

Uh oh!

Mpdreamz Mar 18, 2025

Uh oh!

colleenmcginnis Mar 18, 2025

Uh oh!

colleenmcginnis Mar 19, 2025

Uh oh!

Mpdreamz Mar 20, 2025

Uh oh!

elasticsearchmachine commented Mar 19, 2025

Uh oh!

leemthompo commented Mar 20, 2025 •

edited

Loading

Uh oh!

leemthompo left a comment

Uh oh!

Uh oh!

leemthompo commented Mar 20, 2025

Uh oh!

Uh oh!

[docs] Prepare for docs-assembler #125118

[docs] Prepare for docs-assembler #125118

Uh oh!

Conversation

colleenmcginnis commented Mar 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mpdreamz Mar 18, 2025

Choose a reason for hiding this comment

Uh oh!

colleenmcginnis Mar 18, 2025

Choose a reason for hiding this comment

Uh oh!

colleenmcginnis Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

Mpdreamz Mar 20, 2025

Choose a reason for hiding this comment

Uh oh!

elasticsearchmachine commented Mar 19, 2025

Uh oh!

leemthompo commented Mar 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

leemthompo commented Mar 20, 2025

💚 All backports created successfully

Questions ?

Uh oh!

Uh oh!

colleenmcginnis commented Mar 18, 2025 •

edited

Loading

leemthompo commented Mar 20, 2025 •

edited

Loading