Cross-repo navigation mixing requires workarounds

[theletterf]

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:

- 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:

# 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:

- 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.