[Feature Request]: Cross-repo snippets/includes

[florent-leborgne]

Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

Snippets and more generally reuse in documentation are a great way to display the important information anywhere it's needed while maintaining a single source of truth.

It would be super awesome if documentation files in different repositories could also share snippets.

This actually is not a simple nice to have, it's rather important in a multi-repo docs setup like ours

Proposed Solution

Just like we do with cross-repo links, what if we could include files with similar links, like {include} repo://path_to_snippet

Examples and Research

No response

Alternative Solutions

No response

Additional Context

No response

How important is this feature to you?

Important

[reakaleek]

IMO, it would be easy for assembler builds.

The bigger problem is the isolated build, and therefore, the previews.

@Mpdreamz what are your thoughts on this?

[Mpdreamz]

Not sharing is pivotal to the stability of our system.

It's what makes our builds idempotent, repeatable, immutable.

Let's discuss these snippets maybe they are directives in disguise?

Otherwise git submodules would be a way to share reliably but they come with their own DX challenges.

[theletterf]

What about a snippets registry?

1. Each repo publishes its _snippets content to a snippet registry (S3 bucket or similar)
2. During build, fetch required snippets from registry
3. Cache snippets with versioning/ETag like link indexes

The implementation could mirror the cross-link system:

# docset.yml
cross_links:
  - elasticsearch
  - kibana
cross_snippets:  # New section
  - shared-content
  - elasticsearch

# Usage in documentation
:::{include} shared-content://warnings/security-notice.md
:::

[nastasha-solomon]

Hello! 👋🏼 The workflow docs would also benefit from the ability to include files from repos outside of docs-content. Below, I've provided more information about our current situation and workaround, what we'd specifically need for workflow docs, and how cross-repo include support could benefit other teams down the line.

Our situation

Workflow docs have two components that need to live together in the nav: narrative content (what are workflows, how do they work, etc.) and reference content (specs for workflow steps, triggers, and connectors).

The ideal setup would be narrative docs in docs-content and reference docs in the Kibana repo, alongside the feature code. This would let developers contribute to the docs without leaving their normal workflow, and ship both the implementation and the docs in a single PR. It would also keep the reference docs tightly coupled to the source — when the implementation changes, the docs are right there to update. Writers could still review and edit without needing to own the files outright, and publication timing could be tied to the Serverless release rather than the impl PR merge.

Unfortunately, the docs system currently requires files to live in the same repo as their docset, so there's no way to surface Kibana-side files in the same nav as the docs-content narrative without physically moving the reference docs out of Kibana — which is where they belong.

Current workarounds

We're exploring three short-term options. All of them work around the system constraint rather than solving it:

Option	Flow	Owner	Pros	Cons
1) Kibana repo, PR and dev-driven	Impl PR merged → docs auto-generated in Kibana → writers edit in Kibana repo → docs live on impl PR merge	Dev	Closest to source; zero handoff lag between code and docs	Docs go live when the impl PR merges, not when the Serverless release ships. Would need a toc.yml in Kibana wired into docset.yml. Publication timing is fully outside docs control; writer friction if unfamiliar with the Kibana repo.
2) Script generates files in docs-content	Impl PR merged → script opens a docs-content PR with generated files → writers edit and merge on their schedule	Docs	Docs controls merge and publish timing; automation handles scaffolding; files live in docs-content from the start, making TOC integration easier	Feasibility not yet confirmed. A writer still needs to pick up and shepherd the generated PR. Needs a fallback if automation fails; script must reliably extract enough signal from the Kibana PR.
3) Issue generated, docs writes	Impl PR finalized but not merged → skill or human opens a structured docs issue → writer picks up issue, creates and publishes docs	Docs	Docs controls timing and content fully; works when source material is too sparse to scaffold; issue is a natural tracking artifact visible in the backlog	Adds a queue step before any content exists; issue can sit unactioned if not assigned or prioritized. No draft to start from (though a skill I've built to author docs from an issue may help with this).

We've narrowed down to options 1 and 2 as the most viable short-term paths. Option 2 keeps the reference docs in docs-content to work around the system constraint, but that means decoupling the docs from the source material and the feature owners. It also makes it harder to ensure that the docs and code remain aligned, an issue that wouldn't exist if the reference files could just live in Kibana.

What would help

The ability to include files from an external repo within a docset. Files from the external repo would not need to live in docs-content to be added to the narrative doc's TOC.

For workflow docs, that means the narrative docs would be in docs-content and the reference docs would be in the Kibana repo, but they would both surface together within the same Workflow docsets.

The broader case

The workflow docs situation is one example, but the constraint that we're working around is one that other teams have likely encountered too. Anywhere the feature implementation and the narrative docs live in different repos, teams face the same tradeoff: move files to satisfy the system, or accept a navigation split that fragments the user experience. Cross-repo includes would let teams build navigation around what users need rather than around where files happen to live.