First pass of claude over building blocks

Author: Mpdreamz

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

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

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.

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

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