Docs: remove "Canonical URLs" guide #11516
Conversation
This guide is pretty old and it's not correct anymore. Besides, we are now mentioning `$READTHEDOCS_CANONICAL_URL` environment variable in the https://docs.readthedocs.io/en/stable/canonical-urls.html. We should create a redirect from the page deleted to that one where we are already mentioning how to configure Sphinx and MkDocs. Closes #10246
There was a problem hiding this comment.
This seems like useful information about how to set this information in the specific tools. Now that we're supporting more tools, I guess this isn't as useful, but it does seem like having small guides about how this works on each tool is still useful to have?
We should at least copy over the code snippet that we put in the blog post (https://about.readthedocs.com/blog/2024/07/addons-by-default/) in the Canonical URL docs or similar
| If you are using a custom ``html_baseurl`` in your ``conf.py``, | ||
| you have to ensure that the value is correct. | ||
| This can be complex, | ||
| supporting pull request builds (which are published on a separate domain), | ||
| special branches | ||
| or if you are using :term:`subproject` s or :doc:`translations </localization>`. | ||
| We recommend not including a ``html_baseurl`` in your ``conf.py``, | ||
| and letting Read the Docs define it. |
There was a problem hiding this comment.
Does our current guide explain how to do this effectively? I don't think we really need to set canonical URLs in PR builds though, since they are disallowed by robots.txt.
There was a problem hiding this comment.
What's the effectively way of doing this? The current guide just mention that on Sphinx you can use html_baseurl and on MkDocs the site_url configs: https://docs.readthedocs.io/en/stable/canonical-urls.html#how-to-specify-the-canonical-url
Setting these for specific tools should be done in different pages. See my other comment: #11516 (comment)
I think we definitely want a per tool guide to set all of these things. We are tracking that work in #11187 |
|
I think this page currently adds more confusion that help since most of its content is not valid anymore; that's why I'm proposing to delete it for now and work directly on the other issues we have open for per-doc tool integration guides. |
|
Yea, it just seems like a shame to lose the information that's still useful from this guide. It seems like it should be moved over to the Canonical URL page for now? |
|
I don't follow you here. What's exactly the useful information from this page you refer to? Can you share the link to it? |
|
I think the note about how to set the canonical URL for each tool, and the links to the docs for them, along with the code example from the blog post I linked? I guess I'm fine just removing these for now, but since we're removing automatically setting the canonical URL, it seems like our docs should have explicit examples for how to set them in the tools previously supported? |
This guide is pretty old and it's not correct anymore. Besides, we are now mentioning
$READTHEDOCS_CANONICAL_URLenvironment variable in the https://docs.readthedocs.io/en/stable/canonical-urls.html.We should create a redirect from the page deleted to that one where we are already mentioning how to configure Sphinx and MkDocs.
Closes #10246
📚 Documentation previews 📚
docs): https://docs--11516.org.readthedocs.build/en/11516/dev): https://dev--11516.org.readthedocs.build/en/11516/