refactor: normalize Markdown linkification behavior, elaborate in documentation #7248
Conversation
Josh-Cena
added
pr: documentation
| @@ -9,4 +9,4 @@ | |||
| - [doc1](doc1.md) | |||
| - [doc2](./doc2.md) | |||
|
|
|||
| - [doc-localized](./doc-localized.md) | |||
| - [doc-localized](/doc-localized.md) | |||
There was a problem hiding this comment.
This change is intended. This file is actually not in the localized directory, so relative links shouldn't magically point to the fr localized directory. Changing it to an absolute link will cause the fr directory to be matched in priority.
| @@ -4,7 +4,7 @@ Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin | |||
|
|
|||
| ## Creating plugins {#creating-plugins} | |||
|
|
|||
| A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md). | |||
| A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](../api/plugin-methods/README.md). | |||
There was a problem hiding this comment.
This is a typo. It should have been caught because it doesn't make much sense!
✅ [V2]
To edit notification comments on pull requests, go to your Netlify site settings. |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-7248--docusaurus-2.netlify.app/ |
|
Size Change: +20 B (0%) Total Size: 803 kB ℹ️ View Unchanged
|
|
@Josh-Cena 👍 to resolve against version content folders absolute paths. As far as I understand it, now in the ops repo, I think we can try to avoid the breaking change and simply resolve md links a bit more aggressively? IMHO it never makes sense for a website to end-up with links ending with Also, I think resolving links from the root may make sense for GitHub linking? I think we keep current logic and just add more resolution source folders, so that both of those work? [Test link](/docs/tutorial-basics/quickstart/quickstart.md)
[Test link](/tutorial-basics/quickstart/quickstart.md)And eventually, we could allow users to later configure extra resolution folders so that this is also possible? [Test link](/repo-subdir/website/docs/tutorial-basics/quickstart/quickstart.md)That would be less fail-fast for docs portability (ie user will know it's bad linking only after trying to version or use i18n) but would also improves linking DX overall. In general, link portability is a broad term, it could as well mean I think there are also some opportunities to automatically fix the link portability problem with some CLI tool. |
|
I'm open to add links that resolve against the site dir, but the real absolute path ( I have had many similar requests in the past where people want to create links that map to an external URL (e.g. #6463). When we have a dedicated markdown config and a global Markdown infrastructure, I'd like to create a |
website/docs/guides/markdown-features/markdown-features-links.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Sébastien Lorber <[email protected]>
Motivation
Fix #7247.
This change introduces a little breaking change: absolute links like
/otherFolder/doc.mdis never resolved against the current file's location, and relative links like./folder/doc.mdis never resolved against the content root (should be rare, because it was never documented)Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
Added a test case