errose28 commented on PR #297: URL: https://github.com/apache/ozone-site/pull/297#issuecomment-3820818436
The Docusaurus docs are a little unclear on how this type of link formatting will work when we add [versioning](https://docusaurus.io/docs/versioning). There are two types of links internal in Docusuaurus: URL links and file links as seen [here](https://docusaurus.io/docs/markdown-features/links). What we are actually doing in this PR is migrating from file links to URL links. At the end of that page, the docs recommend using file links for various reasons. None of those are relevant for this project except for one: >. Using relative file paths (with .md extensions) instead of relative URL links provides the following benefits: > ... > A [versioned doc](https://docusaurus.io/docs/versioning) will link to another doc of the exact same version This is an important thing to have working, however it seems to work with URL links too despite what the docs are implying. On [this branch](https://github.com/errose28/ozone-site/tree/HDDS-9225-website-v2-versioning) I created a test versioning setup and used a URL link in the [1.0 version](https://github.com/errose28/ozone-site/blob/9669efa1e61462e93e4d0c5f445d37e916bbba44/versioned_docs/version-1.0.0/02-quick-start/02-reading-writing-data.md?plain=1#L11) and [next version](https://github.com/errose28/ozone-site/blob/9669efa1e61462e93e4d0c5f445d37e916bbba44/docs/02-quick-start/02-reading-writing-data.md?plain=1#L11). In both cases the link stays within the same version when navigating to that page in the local preview, so I think using URL links like we are currently doing is still preferred in our case. Worst case if we have to change them later this sort of bulk reformatting is easy for AI code assistants to handle. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
