Link old Bootstrap docs to latest release

[mdo]

This likely is going to be a pain in the ass, but I wanted to capture some thoughts regardless of where we land on it. My hope is that we can put some time into our old v4.x docs and update them with new outdated release banners and links to the latest versions of each page in our versions pickers. I'd like help brainstorming our approach to this, because right now all I can think of is manually doing it one by one.

Two things are on my mind for it.

Updated new release banner

First is updating the release banner, and adding it to all previous v4.x releases.

Right now there's a thin banner on the 4.0, 4.1, and 4.2 docs. We don't have them on 4.3 or 4.4, and soon 4.5 (after we ship our next v4.6.0 release). At a minimum, we need to:

• [ ] Add banner 4.3
• [ ] Add banner to 4.4

And for the stretch goal, we take it 1-2 steps further:

• [ ] Change the links of each banner to be page-specific (as in, don't link to https://getbootstrap.com on every banner)
• [ ] Redesign the banner to be larger and more noticeable

Updated versions dropdown

Beyond the new version banners, I'd like us to do something more with our versions dropdowns in the navbar. Each version of our docs (4.0–4.5) is different, which leads to unfortunate experiences of viewing outdated docs and not being able to easily jump to the latest version of the page.

Question is, do we include every version like so?

• 4.0: 4.1, 4.2, 4.3, 4.4, 4.5
• 4.1: 4.2, 4.3, 4.4, 4.5
• 4.2: 4.3, 4.4, 4.5
• 4.3: 4.4, 4.5
• 4.4: 4.5
• Bootstrap v5.x

Or, do we do the version you're reading, the latest v4.x, and the latest v5.x like so?

• 4.0: 4.5
• 4.1: 4.5
• 4.2: 4.5
• 4.3: 4.5
• 4.4: 4.5
• Bootstrap v5.x

And, lastly, for all v4 and v5 versions dropdowns, do we include links to v3 and v2? Thinking we can drop those with these changes, and keep the All versions link.

v3?

Beyond v4's docs, I'm wondering if we need to update v3.4's docs to modify the new release banner and versions dropdown. Thinking we modify the text in the banner to mention v4 and v5. With the dropdown, I'm thinking we remove the v4 alpha 6 release finally, update Latest (4.x) to Bootstrap v4.x, and add Bootstrap v5.x. Both the v4 and v5 could point to their latest releases instead of all the releases.

Screenshots of dropdowns

Just for quick comparison...

---

What do you think @twbs/team?

[hashnimo]

I'd like help brainstorming our approach to this,

You can also take a dynamic approach:

1. Build one dynamic page design that can be applied to every version.
2. Remove the version number from the URL.
3. Make the version dropdown default to the latest.
4. Make the user selection as the default if the user selects an older version and keep it in a cookie so it will stay like that even on a full page refresh until the user selects another version or cleared the cookie.
5. Dynamically fetch the documentation information from each version to fill/remove each section of the above one dynamic page.

The fetch documentation database for each version can even be just plain .txt files (with or without html codes), so you can keep each section/part of the documentation for each version as separate .txt files, easily editable for the team when required. The common documentation for all the versions stays as a single file for each common section, edit once and it will be shown for all the versions.

Search engines will see the common links as there's no version number in the URL anymore, which is great for both the people who want the latest version and those who still using the older versions. The dropdown version value can be passed using a cookie, I'm not sure about a way for cookie disabled browsers, maybe using a URL parameter, but again keep an eye on SEO. For JavaScript disabled browsers, handle the fetch using PHP, both scenarios can be handled by this one dynamic page index.php, which means the website is already handled by PHP as the foundation and it doesn't matter if the user has disabled JavaScript or not, Progressive Enhancement methods can be used for this. Overall, I'm not so sure about this or an expert in this, but just an idea.

[Lausselloic]

as documentation is static, maybe store a file with versions value in json format, and load that file in Javascript

• need to update application.js for all actual version
• define the json format

[Johann-S]

A dynamic way would be to find if Github provide an API, which allow us to fetch our tags and use our tags to select a version (+ a bit of JavaScript)

[ffoodd]

What about only linking to latest (for each major) only, using a simple redirection? We may use /4/ to redirect to (currently) /4.6/ and so on.

This would help with maintenance a lot since we'd only have links to majors—and replacing those dropdowns everywhere would be done once (and updated for each major, which isn't that frequent).

[XhmikosR]

That doable for sure, and easy to maintain. We'd still need to change the old live docs to read 4.x etc.

A more flexible approach would be to have a placeholder HTML, then use JS to fetch our docs and create the toggler client-side. That would probably have a speed penalty, though. Plus if we host the version file on GitHub, their API limits might apply.

[folknor]

My ticket https://github.com/twbs/bootstrap/issues/36189 was closed as a duplicate of this one, but I had actually read this ticket before filing mine :-P I feel like I suggested things that were quite different from what has been discussed here thus far.

Hope you will take that into consideration and read my ticket if/when you do any work towards this. Thank you!

Of course if you want I'll gladly repeat the highlights from it here.

EDIT: That said, I must say I do commend you a lot for keeping a much cleaner issue tracker than most other projects this size. That's not a small feat at all.

[mdo]

Part of this has been addressed in #35736 with the versions dropdown in the navbar now pointing to previous versions of the current page. Still TBD on how much we update in the live docs for our older versions.

[folknor]

I'm just going to mention my idea from issue #36189 again, because I don't think @mdo understood what I meant.

One of the easiest way to solve this and make pull requests like #37002 and this ticket unnecessary is to add another URL alias to the site; for example https://getbootstrap.com/docs/latest/ that you would update to point to the newest release when you release it.

Then every old doc version dropdown or header or whatever can just be updated to add a link to https://getbootstrap.com/docs/latest/ (as the top level item in the dropdown for example), and VOILA - old docs never have to be fixed/updated again.

Does that make sense?

Again, @mdo closed my ticket #36189 (where I tried to explain this idea, but I am probably bad at explaining) as a duplicate of this ticket. But it isn't a duplicate. My idea for fixing this hassle is completely different.

[patrickhlauke]

One of the easiest way to solve this and make pull requests like #37002 and this ticket unnecessary is to add another URL alias to the site; for example https://getbootstrap.com/docs/latest/ that you would update to point to the newest release when you release it.

Then every old doc version dropdown or header or whatever can just be updated to add a link to https://getbootstrap.com/docs/latest/ (as the top level item in the dropdown for example), and VOILA - old docs never have to be fixed/updated again.

this would make sense to me. @mdo et al, have a think (unless there was another good reason not to do it)

[julien-deramond]

FYI if it can help, we began to work on "latest" URLs in Boosted: https://github.com/Orange-OpenSource/Orange-Boosted-Bootstrap/pull/1088 (with the system of aliases) in order to have things like:

• https://getbootstrap.com/components
• https://getbootstrap.com/docs/components
• https://getbootstrap.com/docs/5.2/components

[VividLemon]

Not that I have much weight on the topic, as I dont do any work on the library or anything...

But a significantly easier method to maintain is to use a component based framework. That's not to say that there wouldn't be a lot of work to be done. But honestly, probably not an absolute monolith amount once you get passed the repetitive layout items.

My focus is Vue so obviously I'm going to lean from there... but a full fledged Vue SPA could make this a lot simpler as everything would under a global layout, one place, one code to maintain when theres a change.

However, Vue could also be used as an single injectable, where the dropdown js is written in one place, then mounted into the page. So, could be an alternative for single replacements.

Just saying, an all around Vue app, Nuxt app, or React app would make a lot of this all easier 🤔 Just saying, it would take some work, but would make maintenance exponentially easier.

I made a PR that updated the dropdowns in v5, however, I could technically extend the update for v4 and v3. It's really a simple search and replace job that vscode can easily do.

[julien-deramond]

FYI we just merged https://github.com/Orange-OpenSource/Orange-Boosted-Bootstrap/pull/1088 into Boosted which is available in Boosted v5.2.1. We only use GitHub Pages so we didn't explore ideas around redirections in HTTP servers but rather mainly with what Hugo is able to do.

As an example now:

• https://boosted.orange.com/docs/ → https://boosted.orange.com/docs/5.2/getting-started/introduction/
• https://boosted.orange.com/docs/getting-started/ → https://boosted.orange.com/docs/5.2/getting-started/introduction/
• https://boosted.orange.com/docs/getting-started/introduction/ → https://boosted.orange.com/docs/5.2/getting-started/introduction/
• https://boosted.orange.com/docs/getting-started/introduction/#important-globals follows well the anchor link

More details can be found in the PR. If it can be useful for Bootstrap, we can provide the same PR here.

[GeoSot]

I suppose we can have the same results without adding new aliases https://github.com/twbs/bootstrap/pull/36805