elastic / elastic/docs-builder
Cross-repo navigation mixing requires workarounds
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
When content from multiple repositories needs to appear at the same navigation level, the current system requires creating placeholder `toc.yml` + `index.md` files in a "host" repository, even when that repository has no real content to contribute at that level.
## Real-world example: EDOT Cloud Forwarder
The EDOT Cloud Forwarder documentation needed this structure:
```
EDOT Cloud Forwarder
├── EDOT Cloud Forwarder for AWS ← from edot-cloud-forwarder-aws repo
├── Azure ← from opentelemetry repo
└── GCP ← from opentelemetry repo
```
To achieve this, the `opentelemetry` repo had to create a folder structure solely to act as a "parent node":
```
reference/
└── edot-cloud-forwarder/
├── toc.yml ← exists only to create the parent identifier
├── index.md ← required for the TOC, but may have minimal content
├── azure/
│ ├── toc.yml
│ └── index.md
└── gcp/
├── toc.yml
└── index.md
```
Then `navigation.yml` stitches the repos together:
```yaml
- toc: opentelemetry://reference/edot-cloud-forwarder
path_prefix: reference/opentelemetry/edot-cloud-forwarder
children:
- toc: edot-cloud-forwarder-aws://reference/edot-cf-aws # external repo
path_prefix: reference/opentelemetry/edot-cloud-forwarder/aws
- toc: opentelemetry://reference/edot-cloud-forwarder/azure
path_prefix: reference/opentelemetry/edot-cloud-forwarder/azure
- toc: opentelemetry://reference/edot-cloud-forwarder/gcp
path_prefix: reference/opentelemetry/edot-cloud-forwarder/gcp
```
## Current limitations
1. **Cross-repo mixing only possible in `navigation.yml`**: A repo's `toc.yml` cannot reference content from other repos. Only the central `navigation.yml` can stitch repos together.
2. **Identifier = folder path**: There's no way to define a custom identifier for a TOC. The identifier is always derived from the folder path, creating tight coupling.
3. **Placeholder content required**: To create a parent node that groups cross-repo content, you must create a real `toc.yml` + `index.md` even if the "parent" has no meaningful content of its own.
## Possible solutions
### Option A: Allow cross-repo references in `toc.yml`
Let a repo's `toc.yml` reference TOCs from other repositories:
```yaml
# In opentelemetry's reference/edot-cloud-forwarder/toc.yml
children:
- external: edot-cloud-forwarder-aws://reference/edot-cf-aws
- file: azure/index.md
- file: gcp/index.md
```
**Pros:**
- Repos define their own complete structure.
- `navigation.yml` stays simpler.
- Content owners have full control.
**Cons:**
- Repos become coupled to each other.
- Can't build/preview a repo in isolation without dependencies.
- Harder to reason about what's included where.
### Option B: Allow `navigation.yml` to inject children without full override
Instead of replacing a TOC's children, allow injecting additional children:
```yaml
- toc: opentelemetry://reference/edot-cloud-forwarder
inject_children:
- toc: edot-cloud-forwarder-aws://reference/edot-cf-aws
position: 1 # or "after: azure", "before: gcp", etc.
```
**Pros:**
- Repos keep their own structure.
- Central config only specifies the "glue."
- No placeholder files needed.
**Cons:**
- Position semantics can get complex.
- Still requires coordination between repos and central config.
Option A (cross-repo references in `toc.yml`) is powerful but introduces tight coupling between repos, which may be undesirable for distributed ownership.
Contributor guide
Assessment
This issue has not been assessed yet.