Skip to content

docs: avoid using .html extension for blog posts#17090

Merged
kachkaev merged 2 commits intoprettier:mainfrom
Lehoczky:main
Feb 10, 2025
Merged

docs: avoid using .html extension for blog posts#17090
kachkaev merged 2 commits intoprettier:mainfrom
Lehoczky:main

Conversation

@Lehoczky
Copy link
Copy Markdown
Contributor

@Lehoczky Lehoczky commented Feb 9, 2025

Description

Similar to #17079 which removes the .html extension from a lot of existing URLs, this PR aims to remove that for new release blog posts.

This is important, because otherwise opening the blog posts from the GitHub release notes renders the page twice. This is known issue in docusaurus that will be fixed in later versions: facebook/docusaurus#10053

For handling old URLs with the .html extension, I enabled Netlify's "Pretty URLs" option, recommended here: facebook/docusaurus#9552 (comment)

As an example, opening the blog post for the 3.5 release now in the deploy preview works even with the .html in the URL: https://deploy-preview-17090--prettier.netlify.app/blog/2025/02/09/3.5.0.html

Checklist

  • I’ve added tests to confirm my change works.
  • (If changing the API or CLI) I’ve documented the changes I’ve made (in the docs/ directory).
  • (If the change is user-facing) I’ve added my changes to changelog_unreleased/*/XXXX.md file following changelog_unreleased/TEMPLATE.md.
  • I’ve read the contributing guidelines.

Try the playground for this PR

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented Feb 9, 2025

Open in Stackblitz

npm i https://pkg.pr.new/prettier@17090

commit: 825a1c2

@fisker
Copy link
Copy Markdown
Member

fisker commented Feb 9, 2025

I enabled Netlify's "Pretty URLs" option,

Actually, it was enabled by default, but I found that accessing docs/foo it will redirect to docs/foo/(HTTP 301), so I turned it off few days ago.

Do you know if it's possible to always ADD .html? In that case netlify won't redirect, I guess.

@Lehoczky
Copy link
Copy Markdown
Contributor Author

Lehoczky commented Feb 9, 2025

Hmm, the issue now is the present of the .html part of the URL, Sébastien Lorber - the maintainer of Docusaurus - clearly thinks it shouldn't be there:

You should serve pages by their canonical URLs. By default, this means serving them without the .html extension.

I've tried messing around with the _redirects file without any success. Seems like the only way to do this is with the pretty urls option.

Another solution would be to leave everything as is, and just edit the links in a few recent GitHub releases. It's highly unlikely, that anyone has recent blog posts bookmarked with the .html part and encounter this issue when trying to use those bookmarks. It's such an edge-case, popular Docusaurus websites have the same issue, and I don't think they get reported.

For example:

Also, this will be fixed eventually in Docusaurus 4.

@fisker
Copy link
Copy Markdown
Member

fisker commented Feb 9, 2025

Thanks for the investigation,I think we can live with no .html decision, like I already did in #17079 😄

Without "pretty url", seem that .html version url can also be redirected to correct page now, so we only need avoid add .html.

Copy link
Copy Markdown
Member

@kachkaev kachkaev left a comment

Choose a reason for hiding this comment

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

Thank you @Lehoczky!

@kachkaev kachkaev merged commit 8b1dda2 into prettier:main Feb 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants