elastic / elastic/docs-builder

Improve multi-repo assembled docs workflow and contributor guidance

Open
#1,912 6 comments 1 reaction 2 assignees Assigned to @Mpdreamz View on GitHub
ai-triaged ai:eng-question ai:writer-question stale tech-debt
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Description
Our current v3 build system works well for single-repo projects, but breaks down when assembling docs across multiple repos. This is especially painful for our large reference section, where making improvements is nearly impossible without engineering support.

Writers have raised the following challenges:

- **Black box multi-repo builds:** It’s unclear how assembled docs come together across repos, making changes difficult and error-prone.
- **Virtual staging area missing:** Writers need a way to preview assembled docs locally or in staging with a mix of current + WiP branches before merging.
- **Navigation complexity:**
- navigation.yml is hard to manage across repos.
- Path prefixes are confusing and inconsistent.
- Assembling a navigation tree across repos is nearly impossible.
- Redirects based on path prefixes are not supported.
- **Inconsistent outputs:** Local docs-builder results often differ significantly from CI results, leading to confusion.
- **Slow feedback loop:** Waiting 30–40 minutes to see production results creates unnecessary suspense for large changes.

## Impact

These improvements would:

- Empower writers to make reference section changes without engineering intervention.
- Reduce errors and inconsistencies in assembled docs.
- Shorten iteration cycles and make large structural changes less stressful.
- Increase overall contributor satisfaction and productivity.

## Assignee note

@Mpdreamz to transfer knowledge and support. @reakaleek or @cotti to own.

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.