Today, when users visit the root / of a DocC archive, they encounter a "soft 404" error page. This creates a poor first impression and doesn't guide visitors toward the actual documentation they're looking for.
For example, visiting https://docs.swift.org/swiftpm/ shows an error, when ideally it should provide a clear landing experience that orients the user and directs them to the documentation modules and tutorials available in that archive.
Why This Matters
The documentation homepage is often the first touchpoint for users discovering a library or framework. A poor experience at this critical moment can:
Frustrate new users and developers
Reduce discoverability of important documentation
Create confusion about whether documentation even exists
Contrast sharply with modern developer documentation sites (like Apple's Developer Docs)
Proposed Solution
Instead of a 404, the archive index at / should display:
A clear heading or hero section introducing the archive
A sidebar showing the top-level navigation structure
Direct links to the primary modules, tutorials, and documentation sections
This can be achieved by leveraging the existing navigator data that DocC already generates, without requiring new output files or changes to existing routes.
This proposal is fully compatible with DocC's merged documentation feature. We're only creating a landing page at /, while leaving the existing /documentation route intact. This means:
Merged archives continue to work as expected
The root landing page complements rather than conflicts with combined documentation
No changes needed to existing merged archive configurations
I think what you're aiming for here is a pitch or ad-hoc review to help mitigate an issue with how the single page app (DocC-Render) works today - and I'm here for it. Today we're actively designing around this gap in the current functionality, along with the gap that a combined documentation page is only synthesized and can't be provided as a "curated experience" (aka rendered from markdown or something)
I think what you're proposing here definitely works as a stop-gap to fix an immediate problem, but the larger issue needs to be addressed as well.
While the docc-archive-as-JSON-bundle-of-data thing worked acceptably, and enabled the potential of native rendering for docs as well as HTML presentation with the single-page app, it brought with it significant challenges in presenting the content (requiring the /documentation in everything) that from a practical perspective has been (and continues to be) a notable challenge.
Thanks for the feedback, @Joseph_heck. I've been exploring a couple of alternatives that might address both the immediate UX problem and the larger architectural concerns.
Alternative 2: "Back to Documentation" Link
Simple, works for both simple and combined archives.
Reuses existing infrastructure (no new code patterns)
Allows curated content via homepage.json
Directly addresses the "curated experience" gap you mentioned
Same model works for simple and combined archives
Trade-offs
Alternative 2 is quicker; Alternative 3 aligns better with the larger direction.
However, with Alternative 3, we need to decide on the actual filename for the data file. This decision affects both the render side and requires changes to swift-docc to emit the file with the right name and content.
Thanks @victorpuga - to be clear, I'm not the owner/maintainer of DocC, more a very frequent user/consumer of its features as a means to present documentation, tutorials, and guides. The alternatives and suggestions you presented after were more limited in scope than what I was advocating for thinking - smaller and more focused, and maybe what you want to pitch or suggest - but not really what I was suggesting.
I think if we stay within the Javascript/single-page-app mode, there's a broader question that we need to address of how to provide a curated/edited view of a top-level page that directs and presents readers from a root URL or the root URL + /documentation.
While this is the status quo today, I'm not personally convinced this is working to the project and our reader's benefits, and that maybe we need to spend some time focused on a display that doesn't require a Javascript intermediary. The moving parts are all in the code base to allow us to render a fully static HTML site from a DocC archive collection. I think there's a lot of benefit in having the intermediary DocC Archive that we can merge, or display individually - and now that we're more actively merging more of these, it's become clear that the navigation between individual archive sets combined into a collection - while functional - could use some more attention in terms of navigating between the collections, how that's visually presented, and how we provide or present a top-level visual of the collection that can be explicitly designed, not just synthesized.
In my view, the quick-nav left panel - which in a single archive is pretty effective - doesn't hold up as well when you have multiple collections in a merged archive that you're displaying. As an example, when you're viewing: Package Manager Docs, it's not at all clear that the collection includes the sibling PackagePlugin API docs and PackageDescription API docs - although you can see both from that synthesized page at the top (https://docs.swift.org/swiftpm/documentation/)
The collections show a disclosure triangle in the combined left nav so you can expand/collapse each collection, but that's it. On top of that, the left nav setup is (to me) visually larger and more prominent in the design and layout than I think it should be - detracting from the core content that's being made available - the docs themselves. I'd personally prefer a far more compact visual representation - keeping the searching and navigation capability, and perhaps expanding to even a breadcrumb concept so that you have a better representation of where you are within a deeper or broader collection of docs.
I'm not at all suggesting that your proposal needs adjustment for a pitch, more airing the pain points I'm seeing and broader conversation that I think the project should explore.
Thanks for the further clarification, @Joseph_Heck. You're articulating a much broader architectural concern than what I was addressing and I think you're right to push on this.
The merged archive navigation problem you're describing is real. When you have multiple collections combined, the left sidebar doesn't effectively communicate the relationships between them or help readers understand the scope of what's available.
Potential approach:
Scoped Navigation
Only show the current archive's pages in the left nav, with a selector or breadcrumb to switch between collections. This keeps the visual hierarchy cleaner and makes the structure of each collection immediately apparent.
As part of this, we could include a link in the "Documentation" text at the top of the sidebar that takes readers to the homepage, where they'd be able to see the combined archive's root and understand the full scope of what's available.
I personally want to address the homepage issue, but not as a quick patch. I want to do it in a way that's part of the larger solution. I feel strongly about adding a home route that renders DocumentationTopic.vue , mapping / to /data/homepage.json, because it treats the homepage as a first-class citizen in the data model and creates a foundation that can evolve with the broader architectural improvements.
Whether that's through a curated landing page, improved navigation structure, or rethinking how collections present themselves at the root, it should all work together.
I'd love to hear @ronnqvist and @marcus_ortiz's thoughts on this. What does the broader vision look like for merged archive presentation, and how should the homepage/root experience fit into that?
My feelings is that adding another page is a stop-gap solution to an immediate problem and that it would ultimately be phased out when addressing the core issues.
I still feel that it's perfectly fine to do it as a stop gap solution and believe that the timescale for it to be phased out could possibly be measured in years.
If we go back to the original problem statement:
visiting https://docs.swift.org/swiftpm/ shows an error, when ideally it should provide a clear landing experience that orients the user and directs them to the documentation modules and tutorials available in that archive.
I feel that the root cause of that issue is the need for a leading "documentation" path component which—as far as I know—is required by Docc Render to know what type of documentation page is requested (if it's a tutorial or not) so that it can load the right resources and put together the page. If that path component wasn't required then the https://docs.swift.org/swiftpm could be the page that's on https://docs.swift.org/swiftpm/documentation today and the documentation for its modules (for example "PackageDescription") could be https://docs.swift.org/swiftpm/packagedescription.
Additionally, if we look ahead—at what's intended but not yet implemented for combined documentation archives—when it becomes possible to pass a catalog to the merge command, then the documentation that's currently at https://docs.swift.org/swiftpm/documentation/packagemanagerdocscould become the landing page for the combined archive (which without the "documentation" component would be https://docs.swift.org/swiftpm) with the "PackageDescription" and "PackagePlugin" documentation having their own sub paths (https://docs.swift.org/swiftpm/packagedescription and https://docs.swift.org/swiftpm/packageplugin).
I don't know how much work it is to change DocC Render to not require a leading "documentation" component but this has been an issue for 5 years now.
My personal vision is that DocC would transition to fully static HTML files as the default output format, that deploying to a different location would be as simple as moving the files there, and that renaming a path component would be as simple as renaming a file/directory.
I made some progress on this last year and DocC can now (as of the 6.3 release) emit a static HTML representation of the page's content for environments that don't run JavaScript. As mentioned in the original pitch, one natural next step would be to add a small amount of CSS to improve the reading experience; with the goal of looking exactly the same as the DocC Render single-page-app version. I've been finding a little bit of time to explore this but I'm still not ready to even open an early work-in-progress (draft) PR or to pitch the idea with more details here in the forums.
Thanks for sharing that vision, @ronnqvist. I totally get the appeal of moving toward static HTML output. It's elegant, portable, and solves a lot of the fundamental architectural issues you're describing.
I do have a few questions as I think through this though.
What would you suggest for the immediate fix? The /swiftpm/ → 404 problem affects users today, and even if the long-term solution is HTML-based, we need something in the meantime.
I already have forks of swift-docc and swift-docc-render that handle the new homepage with homepage.json. The implementation is nearly done, but I'm wondering if it's worth maintaining and upstreaming if it's ultimately going to be removed when the static HTML approach ships. What's your take on that?
I'm also genuinely eager to help move the static HTML rendering feature forward. What are the next steps, and where could I contribute effectively? Is there work on the styling layer you mentioned, or would it be more helpful to focus on a specific part of the pipeline?
