Documentation homepage

Development Swift-DocC
1

Proposal: Curated Home Page Layout for DocC Archives (Hero + Top-Level Cards)

I opened a PR (Added Documentation homepage by VictorPuga · Pull Request #982 · swiftlang/swift-docc-render · GitHub) with this approach and was asked to start a forums thread to discuss it further; this post summarizes the proposal and open questions.

Context / Motivation

  • Pain point: Today / defaults to a “not found” page and doesn’t highlight the most important entry points (documentation and tutorials).
  • Goal: Provide a clear, modern landing experience—hero plus concise top-level navigation—so readers can immediately choose between primary documentation areas.

What this change delivers

How it works

  • Reuses the existing DocumentationLayout and Navigator data, filtered to the top-level nodes of the sidebar tree.
  • Uses existing TopicType metadata to choose icons; no extra content authoring required.
  • Hero strings come from new i18n keys; colors/shadows use existing theme tokens.
  • Routing remains the same: the home page is still /.

Comparison to merged/combined archives

I checked merged archives recently, and these are the key points:

  • They provide a similar experience to this PR, but the merged view currently lives at /documentation instead of /.
  • This proposal does not require a combined archive (--enable-experimental-combined-documentation). It uses the same DocC-generated index output and presents it with a curated hero + cards at the root.
  • It intentionally renders only the top-level nodes (like the merged archive index), keeping the landing page focused and uncluttered.

Customization surface

The current PR does not expose customization knobs yet; open to which options (hero text overrides, grid breakpoints, icon set, etc.) should be configurable and whether they belong in this renderer or in DocC itself.

Open questions for the community

  • Do we want this as an opt-in template, a default, or a theme toggle?
  • If we add customization, should those controls live in DocC itself or in the renderer layer?
  • Given that combined archives already exist, does it make sense to add this landing page? If so, what differentiating features should it include?

Looking forward to feedback and to aligning this with DocC’s roadmap.

2

Hi Victor,

Welcome, and thank you both expressing an interest in the docs tooling and for sharing!

I was a little confused about what this is doing, and specifically what changes you're proposing. In particular, is this changing the default HTML that's immediately available at the root of a DocC archive, or is this changing HTML that's at the /documentation subdirectory within a DocC archive?

If a DocC archive has multiple modules, how it that presented? For example the Package Manager docc archive that's published through swift.org at Documentation has that default curation page, but Documentation doesn't. Would this help that situation and provide links to the /documentation page with its panels?

To try and provide some background for how things sit today re: customization of content:

Customization for DocC is fairly minimal, and generally provided through DocC. The existence of theme-settings.json for some, or just the existence of files (header.html, footer.html) for others. Because DocC (and the rendering app) are included within a Swift toolchain, the renderer is "pre-baked" and included as a distribution build with toolchains today - so anything we do in terms of supporting customization needs to work with this kind of deployment mechanism.

3

Thanks for the questions and for outlining the toolchain constraints. Let me answer them and clarify what the change does.

In particular, is this changing the default HTML that's immediately available at the root of a DocC archive, or is this changing HTML that's at the /documentation subdirectory within a DocC archive?

The proposal replaces the current “not found” experience at the archive root (/) with a curated hero and top-level cards. It does not change the content at /documentation; that page continues to render exactly as it does today.

The renderer reuses the existing index data that DocC already emits. It simply filters the navigator tree to its root nodes and renders those as cards alongside the hero. No new DocC output files or alternate routes are added.

If a DocC archive has multiple modules, how it that presented?

Each top-level module becomes its own card, so a multi-module archive shows one card per module at the root. Tutorial bundles or other top-level navigator entries are treated the same way.

Would this help that situation and provide links to the /documentation page with its panels?

It would surface links into each module’s /documentation/... page; it does not change the /documentation page itself.

Documentation Tooling Workgroup Meeting - 15 December 2025