an attempt to clarify all the config files

Author: bmorelli25

config/legacy-url-mappings.yml

@@ -1,4 +1,8 @@
+#############################################
+# This file defines the legacy URL mappings for the documentation site.
+# It maps current documentation pages to older versions to ensure users can find the content they need.
 # TODO: Refactor the model, for now we just use the first element as current version
+#############################################
 
 stack: &stack [ '9.0+', '8.18', '8.17', '8.16', '8.15', '8.14', '8.13', '8.12', '8.11', '8.10', '8.9', '8.8', '8.7', '8.6', '8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.17' ]
 

config/navigation.yml

@@ -64,8 +64,9 @@ toc:
         children:
           - file: index.md
           - file: content.md
-          - file: landing-page.md
-          - file: redirects.md
+          - file: navigation.md
+          - file: versions.md
+          - file: legacy-url-mappings.md
       - folder: content-set
         children:
           - file: index.md

docs/_docset.yml

@@ -30,48 +30,20 @@ Tagged
 :   Allows you to 'tag' a single git reference (typically a branch) as `current` which will be used to deploy to production.
     Allowing you to control the timing of when new documentation should go live.
 
+### Add a new content set
 
-### Continuous deployment
+To get started:
 
-This is the default. To get started, follow our [guide](/migration/guide/index.md) to set up the new docs folder structure and CI configuration.
+1. Follow our [guide](/migration/guide/index.md) to set up the new docs folder structure and CI configuration.
+1. Configure the repository source in `assembler.yml`. See [](./site/content.md) for details.
 
-Once setup ensure the repository is added to our [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml)  under `references`. 
+  :::{note}
+  The tagged branching strategy requires first following our [migration guide](/migration/guide/index.md) and configuring the documentation CI integration.
+  Our CI integration checks will block until `current` is successfully configured.
+  :::
 
-For example say you want to onboard `elastic/my-repository` into the production build:
-
-```yaml
-references:
-  my-repository:
-```
-
-Is equivalent to specifying.
-
-```yaml
-references:
-  my-repository:
-    next: main
-    current: main
-```
-
-% TODO we need navigation.yml docs
-Once the repository is added, its navigation still needs to be injected into to global site navigation.
-
-### Tagged
-
-If you want to have more control over the timing of when your docs go live to production. Configure the repository
-in our [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) to have a fixed git reference (typically a branch) deploy the `current` content source to production.
-
-```yaml
-references:
-  my-other-repository:
-    next: main
-    current: 9.0
-```
-
-:::{note}
-In order for `9.0` to be onboarded it needs to first follow our [migration guide](/migration/guide/index.md) and have our documentation CI integration setup.
-Our CI integration checks will block until `current` is successfully configured
-:::
+1. Inject the content set into the global navigation. See [](./site/navigation.md) for details.
+1. Optionally set up legacy URL mappings. See [](./site/legacy-url-mappings.md) for details.
 
 #### CI configuration
 

docs/configure/content-sources.md

@@ -1,55 +1,63 @@
+---
+navigation_title: `assembler.yml`
+---
+
 # `assembler.yml`
 
-The global navigation is defined in the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file. This file can roughly be thought of as the V3 equivalent of conf.yaml in the asciidoc build system. This file, which writers own, allows for arbitrary nesting of `docset.yml` and `toc.yml` references. This file will live in the `elastic/docs-content` repository, but will not build or have any influence over the `docs-builder` builds in that repo.
+The [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file defines the global documentation site:
 
-The global navigation that is defined in [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) can be composed of three main resources:
-1. Local TOC files: toc.yml files that live in the docs-content repository.
-2. External TOC files: A subset of a content set (represented by a toc.yml file) that is external to the docs-content repository.
-3. External content set declarations: An entire docset.yml file that is external to the docs-content repository.
+* `environments`
+* `shared_configuration`
+* narrative repository configuration
+* reference repository configurations
 
-The [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file might look something like this:
+## `environments`
 
-```yaml
+This section defines different build environments for the documentation site.
 
-```
+Each environment specifies configuration details such as the site URI, content source, path prefix, Google Tag Manager settings, and feature flags.
+
+## `shared_configuration`
+
+This section defines YAML anchors for common settings shared among multiple repositories.
+
+## `narrative`
+
+Configures the main `docs-content` repository.
+
+## `references`
+
+Configures all other repositories whose docs content should be included or referenced in the build. Each can have custom settings for branch, checkout method, etc.
 
-## Assembler constraints
+### Branching strategy
 
-To maintain each docset’s immutability and self-containment, resources in the global navigation (assembler.yml) must follow specific rules.
-1. A link resource can appear only once in the global navigation, and it must nest directly under another resource (not under individual pages from a different content set). In other words:
-    1. Each docset.yml or toc.yml file can appear only once in the overall navigation.
-    1. Any TOC declarations—whether in docset.yml or toc.yml—must be placed either at the top level or directly under another TOC entry, with no individual files in between.
-1. Nested resources must appear either before or after (default) the parent’s TOC, and they cannot be placed arbitrarily among the parent’s pages (e.g., between two files of the parent).
-1. If an external TOC is linked, all of its child TOCs must also be included in the global navigation.
+How you add a reference repository depends on its [branching strategy](../content-sources.md#branching-strategies).
 
-## AsciiDoctor conf.yml
+#### Continuous deployment repository
 
-In the AsciiDoctor-powered site, content configuration at the site level is done in the [`conf.yaml`](https://github.com/elastic/docs/blob/master/conf.yaml) file in the elastic/docs repo. In the `conf.yml` file, the configuration information for all books are listed in this one file. Here's the example of what it looks like to configure a single book:
+To add a continuous deployment repository, define the name of the repository:
 
 ```yaml
-- title:      Machine Learning
-  prefix:     en/machine-learning
-  current:    *stackcurrent
-  index:      docs/en/stack/ml/index.asciidoc
-  branches:   [ {main: master}, 8.9, 8.8, 8.7, 8.6, 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3 ]
-  live:       *stacklive
-  chunk:      1
-  tags:       Elastic Stack/Machine Learning
-  subject:    Machine Learning
-  sources:
-    -
-      repo:   stack-docs
-      path:   docs/en/stack
-    -
-      repo:   elasticsearch
-      path:   docs
-    -
-      repo:   docs
-      path:   shared/versions/stack/{version}.asciidoc
-    -
-      repo:   docs
-      path:   shared/attributes.asciidoc
-    -
-      repo:   docs
-      path:   shared/settings.asciidoc
+references:
+  my-repository:
 ```
+
+The above configuration is equivalent to specifying. 
+
+```yaml
+references:
+  my-repository:
+    next: main
+    current: main
+```
+
+### Tagged repository
+
+To add a tagged repository, configure the repo to have a fixed git reference (typically a branch) deploy the `current` content source to production.
+
+```yaml
+references:
+  my-other-repository:
+    next: main
+    current: 9.0
+```

docs/configure/site/content.md

@@ -4,41 +4,17 @@ navigation_title: Site-level
 
 # Site-level configuration
 
-Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. At the site-level, we have:
+Configure the documentation site in these files:
 
-| System property | Asciidoc | V3 |
-| -------------------- | -------------------- | -------------------- |
-| **Content sources** --> Collections of markup files containing doc content. These are split up across many docs repos. | _Books_ | _Content sets_ |
-| **Content configuration** --> A way to specify where to find those content sources, and in what order they should be added to the site. | Configuration file ([`conf.yml`](https://github.com/elastic/docs/blob/master/conf.yaml) in elastic/docs) | Config file `assembler.yml` |
-
-Where these pieces live and what format they are in varies between the two systems, but they generally achieve the same goal.
-
-## Content sources
-
-TBD
-
-## Content configuration
-
-In both the AsciiDoctor- and V3-based system, there is site-wide configuration where you list all content sources, where to find those sources, and in what order they should be added to the site.
-
-In the AsciiDoctor system, this all happens in one YAML file in the `/docs` repo. In the V3 system:
-* Content configuration happens in the [`assembler.yml`](https://github.com/elastic/docs-builder/blob/main/config/assembler.yml) file in `docs-builder`.
-* Navigation configuration happens in the [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file in `docs-builder`.
-
-[assembler.yml](./content.md)
-
-## Landing page
-
-See [landing page](./landing-page.md)
+- [](./content.md) - build environments and repository sources
+- [](./navigation.md) - global navigation index
+- [](./versions.md) - global versioning schemes
+- [](./legacy-url-mappings.md) - supported legacy version
 
 ## Redirects
 
-Plan still needed
+Redirects are also configured at the site-level. See [](../../contribute/redirects.md) for more information.
 
 ## V3 site-level diagram
 
-DIAGRAM NEEDED
-
-## Asciidoc site-level diagram
-
-![site-level config in the asciidoc system](./img/site-level-asciidoctor.png)
+*Coming soon*

docs/configure/site/index.md

@@ -0,0 +1,23 @@
+# 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.
+
+## Structure
+
+`stack anchor`
+:   Defines a reusable list of version strings for "stack" projects, e.g., [ '9.0+', '8.18', ... ].
+
+`mappings`
+:   A YAML mapping where each key is a legacy documentation URL path (like `en/apm/agent/java/`) and the value is a list of asciidoc versions that exist for that path.
+
+:::{important}
+The first version in the `mappings` list is treated as the "current" version in documentation version dropdown.
+:::
+
+## Example entry
+
+```yml
+en/elasticsearch/reference/: *stack
+```

docs/configure/site/landing-page.md

@@ -0,0 +1,30 @@
+# `navigation.yml`
+
+The [`navigation.yml`](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml) file acts as a global navigation index. Each entry points to a `toc.yml` file, which contains the navigation tree for that section. This design allows each section/project/team to manage its own navigation independently of other content sets.
+
+## `toc`
+
+The location of the table of contents file.
+
+`repo_name://path-relative-to-toc.yml`
+
+## `path_prefix` (optional)
+
+The `path_prefix` configuration key specifies the URL path segment that should be prefixed to all documentation URLs.
+
+ listing all documentation sources and the corresponding `toc.yml` file that defines their navigation.
+
+
+ table of roots and specifying the location of each documentation section’s table of contents (toc.yml) file. Every entry in navigation.yml must reference a toc.yml file, which actually defines the navigation structure for that documentation section.
+
+
+
+defines the structure and organization of the navigation menu for the Elastic documentation site. 
+
+The file is composed of nested YAML objects, where each object represents a navigation node. Navigation nodes can be categories, sections, or links to documentation pages.
+
+
+
+
+% TODO we need [`navigation.yml](https://github.com/elastic/docs-builder/blob/main/config/navigation.yml`) docs
+Once the repository is added, its navigation still needs to be injected into to global site navigation.