I opened some issues... > On Feb 8, 2022, at 11:25 AM, Zoran Regvart <zo...@regvart.com> wrote: > > Hi David & Cameleers, > > On Tue, Feb 8, 2022 at 7:57 PM David Jencks <david.a.jen...@gmail.com > <mailto:david.a.jen...@gmail.com>> wrote: >> We have a problem in a lot of blog posts that they link into the Antora >> generated docs. > > Yes this happens with increasing frequency and it is problematic > >> Many link to the “next” version of the docs which has two problems: >> >> - as release announcements, they should link to the doc version that’s been >> released. >> - there’s no reason to suppose any particular page in ‘next’ is going to >> stay there. > > We should agree never to link to `next` or `latest`, but to concrete > versions. A validation rule to that effect can be implemented to > enforce this.
https://github.com/apache/camel-website/issues/779 <https://github.com/apache/camel-website/issues/779> deals with fixing existing blog posts. https://github.com/apache/camel-website/issues/780 <https://github.com/apache/camel-website/issues/780> suggests adding a rule to keep us out of trouble in the future. > >> From this point of view we should change all the release announcement links >> to point to the docs in the released version. That’s an improvement, but it >> will cause another problem: >> >> - At the moment our plan is to drop the docs for no-longer-supported >> versions when they aren’t used by supported versions of other subprojects. >> >> So, eventually all the links to docs in blog posts will break. >> >> I think we should: >> >> - change all blog post links to point to explicit appropriate doc versions. >> I’m somewhat afraid about how big a job this will be, but the current links >> to “next” are clearly wrong in all cases. >> >> - Decide what to do about old versions. I can think of three possibilities: >> >> — Keep all the old docs versions in the docs, perhaps marking them >> “unsupported”. There might be ways to do this without building those >> portions of the website every time but this would take some time and thought >> and wouldn’t be my highest priority for some time. >> — Delink broken links in the blog, marking them something “no longer >> documented” or “obsolete” or something. >> — Remove the blog posts about no-longer-documented versions. >> >> I really don’t know what to do here, so I’m hoping discussion will result in >> a “best path forward”. > > I'd like to be in a place where we could keep the old versions of the > documentation, given that we've split off the website source and > publish repositories. Perhaps there is a way forward by keeping more > content in the publish repositories, even if it is not built/linked > from the site. As a form of archived documentation. For that we would > need to keep everything within the "/_" (CSS, images...) and when > publishing instead of deleting everything[1] we delete only the built > versions. I also would really like to be able to keep all the old doc versions somehow. Around some details, either I don’t quite understand you or slightly disagree on what is needed or will work. I opened https://github.com/apache/camel-website/issues/781 <https://github.com/apache/camel-website/issues/781> to try to explain my thinking on what we could do. > > The drawback of this approach is that it might overwhelm whatever is > done outside of our purview to publish the site, but we can try and > see if it really does and engage INFRA to explore options. It seems implausible to me that even a few GB of infrequently accessed static content would be a problem, and I think we should start by solving the problems of how to avoid generating the entire site on every build. thanks! David Jencks > > zoran > [1] > https://github.com/apache/camel-website/blob/b978a3e6af3fcc97808515bc01a004ddd28426a6/Jenkinsfile#L99 > > <https://github.com/apache/camel-website/blob/b978a3e6af3fcc97808515bc01a004ddd28426a6/Jenkinsfile#L99> > -- > Zoran Regvart
