elastic / elastic/docs-builder

Cross-repo navigation mixing requires workarounds

Open
#2,561 2 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question ai:writer-question enhancement needs triage stale
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.