apache / apache/camel-website

Investigate how to keep old doc versions in the website without building them on every build.

Open
#781 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
CSS
Stars
76
Forks
202
Avg merge
1d 12h
Merged PRs (30d)
19

Description

It would be great to keep all the old doc versions accessible in our website:
- links from old blog posts would keep working
- external links would keep working
- Someone stuck on an old version could find the docs

However...
- building an ever growing set of doc versions on every build will soon take too long to be practical
- Without a way to hide obsolete doc versions, the component explorer will become unwieldy

In any case, I believe we have to rebuild the entire site when the UI changes or Antora is significantly upgraded.

At the moment we are using the standard Antora component explorer, which includes the whole explorer in every page. There are other solutions such as putting this stuff in a separate json document and rendering the json on each page. If we stick with the default component explorer I think we have to rebuild the entire site whenever we add a doc version, so the explorer on old pages can get to all versions.

For all other site builds, I think it should be possible to do something using a site manifest similar to the subproject-specific partial doc builds to only build "active" doc branches while using the already-built pages for the "inactive" doc branches. Together with setting up the partial builds, we'll need to figure out how to publish a complete site when only part of it has been "just built". Either we have to remove only the "old, active" pages when publishing the site, or find an independent way to archive the inactive pages and add them to the "built site" before committing.

Contributor guide

No contributing guide indexed for this repository

Research direction

Review the standard Antora component explorer, the site manifest approach, and the existing subproject-specific partial doc builds. Define how active branches are built, how inactive pages are retained, and how a complete site is published without rebuilding every old version.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.