Expanded building blocks

Mpdreamz · Mpdreamz · commit 7887ee2d2840 · 2025-10-01T10:50:10.000+02:00
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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-catalog.md b/docs/building-blocks/link-catalog.md
@@ -1,30 +1,30 @@
 ---
-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
 * **Assembler coordination** - The assembler uses this to determine which repositories and versions are available to build
 
 ## 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
 ```
 
 ## 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,31 +36,31 @@ 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
 
 ### By the assembler
 
 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
@@ -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
@@ -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
@@ -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
