Add portal builds: a new way to host multiple isolated documentation sets#2348
Merged
Add portal builds: a new way to host multiple isolated documentation sets#2348
Conversation
…sets
This PR introduces **Portal Builds**, a third documentation building mode alongside single docset builds and assembler builds.
Portal builds enable hosting multiple isolated documentation sets under a unified developer portal with shared navigation and filtering.
Portal builds solve the need for internal developer documentation portals where:
- Multiple teams maintain separate documentation repositories
- Each documentation set should remain isolated (independent builds, versioning)
- Users need a single entry point to discover and navigate all documentation
- **Shared EUI Icons**: New `Elastic.Documentation.Svg` project provides 460+ EUI icons as embedded resources, used by both `IconRole` in markdown and the portal landing page
- **Landing Page with Filtering**: Text search and category dropdown to filter documentation sets
- **Category Pills**: Color-coded badges showing documentation set categories (observability, tooling, security, etc.)
- **htmx Navigation**: Seamless page transitions using `hx-select-oob` for content swapping without full page reloads
- **Portal Configuration**: YAML-based configuration for defining documentation sets, categories, and display options
```bash
docs-builder portal clone config/portal.example.yml
docs-builder portal build config/portal.example.yml
docs-builder portal serve
```
```yaml
site_prefix: /internal-docs
title: "Elastic's Internal Dev Docs"
documentation_sets:
- name: my-repo
branch: main
category: tooling
display_name: "My Documentation"
icon: docs
```
2 tasks
# Conflicts: # config/changelog.example.yml # src/Elastic.Documentation.Site/_ViewModels.cs
# Conflicts: # src/Elastic.Documentation.Configuration/Serialization/YamlStaticContext.cs
reakaleek
approved these changes
Feb 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
his PR introduces Portal Builds, a third documentation building mode alongside single docset builds and assembler builds.
Portal builds enable hosting multiple isolated documentation sets under a unified developer portal with shared navigation and filtering.
Portal builds solve the need for internal developer documentation portals where:
Multiple teams maintain separate documentation repositories
Each documentation set should remain isolated (independent builds, versioning)
Users need a single entry point to discover and navigate all documentation
Shared EUI Icons: New
Elastic.Documentation.Svgproject provides 460+ EUI icons as embedded resources, used by bothIconRolein markdown and the portal landing pageLanding Page with Filtering: Text search and category dropdown to filter documentation sets
Category Pills: Color-coded badges showing documentation set categories (observability, tooling, security, etc.)
htmx Navigation: Seamless page transitions using
hx-select-oobfor content swapping without full page reloadsPortal Configuration: YAML-based configuration for defining documentation sets, categories, and display options
Everything new builds on old.
This feature connects into seemlessly into
docs-builderarchitecture:cursorful-video-1765543446664.mp4