Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update new docs version picker to work on home and examples pages #36245

Merged
merged 4 commits into from
Apr 30, 2022

Conversation

mdo
Copy link
Member

@mdo mdo commented Apr 29, 2022

Alternate fix to #36221.

This doesn't address every issue, but it fixes the broken links for Home and Examples. This also fixes the 404 for the utilities/opacity/ page. What remains is figuring out what to do about two situations:

TBD on both those.

/cc @julien-deramond

@mdo
Copy link
Member Author

mdo commented Apr 29, 2022

For more context on why we would keep this version picker, see #31980. We've had a handful of issues and more requests to better support jumping between versions of specific pages.

Across major versions, we need better linking and some updates for the previous major versions.

Copy link
Member

@julien-deramond julien-deramond left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm closing #36221 based on the content of this PR that fixes the blocking issues. As said in the description what remains is figuring out what to do about two situations.

Let's keep in mind that it would be safer in the future to wait for the beginning of a major version to change the sitemap of the documentation (e.g. moving or renaming some sections). Otherwise, between minor versions, if the sitemap of the documentation changes too much, it will result in a lot of 404s.

Don't know if it would be feasible but while I was testing this PR, one possible evolution would be to keep the anchor links as well:

site/layouts/partials/docs-versions.html Outdated Show resolved Hide resolved
site/content/docs/5.1/utilities/opacity.md Show resolved Hide resolved
@mdo
Copy link
Member Author

mdo commented Apr 30, 2022

Let's keep in mind that it would be safer in the future to wait for the beginning of a major version to change the sitemap of the documentation (e.g. moving or renaming some sections). Otherwise, between minor versions, if the sitemap of the documentation changes too much, it will result in a lot of 404s.

Definitely. No major restructuring of pages here. Only thing we should have to worry about is new pages, which we've accounted for with the added front matter.

Don't know if it would be feasible but while I was testing this PR, one possible evolution would be to keep the anchor links as well:

I'm going to skip that for now, definitely a nice to have. Also a little tougher since the headings can change between versions (e.g., ## Sass became ## CSS on a ton of pages). Not a huge deal because those links would still function, they just wouldn't scroll to the section.

@mdo mdo merged commit 55be3c3 into main Apr 30, 2022
@mdo mdo deleted the docs-version-switcher branch April 30, 2022 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants