docs: clarify impact of document ID on the URL #11339
Conversation
✅ [V2]
To edit notification comments on pull requests, go to your Netlify project configuration. |
⚡️ Lighthouse report for the deploy preview of this PR
|
Josh-Cena
left a comment
There was a problem hiding this comment.
I don't see why this needs such a long wall of text. I think it would just be a few sentences saying how the ID is used as the default for the slug, so if you change the ID you may want to restore to the previous URL by setting the slug.
slorber
left a comment
There was a problem hiding this comment.
Thanks, agree we should clarify this and recommend the usage of slug
But also agree with @Josh-Cena , this is currently too verbose. Please try to explain things as clearly and concisely as possible. I don't think we need new headings to cover that topic, and you should focus on providing that information in 2/3 sentences max.
| ### Doc URLs {#doc-urls} | ||
|
|
||
| By default, a document's URL location is its file path relative to the `docs` folder, with a few exceptions. Namely, if a file is named one the following, the file name won't be included in the URL: | ||
| By default, a document's URL location is its file path relative to the `docs` folder, with a few exceptions. Namely, if a file is named one of the following, the file name won't be included in the URL: |
There was a problem hiding this comment.
We should start by saying that the filename is used as the default ID and the ID is used as the default slug, except for these "category index" files (IIRC, I have long forgotten about the technical details). Otherwise the tip that changing the id changes the URL doesn't make sense
Pre-flight checklist
Motivation
Closes #10496
Deploy preview: https://deploy-preview-11339--docusaurus-2.netlify.app/docs/create-doc/