-
-
Notifications
You must be signed in to change notification settings - Fork 8.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fix: support relative markdown linking #1138
Conversation
Deploy preview for docusaurus-preview ready! Built with commit 552716c |
One other question: will this handle Markdown file links that also have an anchor attached to them, like I have to say I'm kinda surprised that not many other people have run across this issue yet :) |
Yes it will. Actually everyone is referencing stuff with What it means by https://docusaurus.io/docs/en/doc-markdown#linking-other-documents is that we need to reference it based on It's been like that since the very first release of Docusaurus 😮 But anyway, seems that it's not hard to implement the relative linking |
Cool. If you can push this out real soon (like, today maybe? :) ), I think this might let me move forward with the Redux docs conversion. |
Thanks for fixing this @endiliey! Would it be possible to also fix relative links for assets in this PR? A link like The issue was already reported in #705 (see #705 (comment)). Basically, the goal is to be able to use the same link paths (for markdown documents and assets) both when browsing the source in GitHub (or the Markdown Preview in VS Code) and when building the docs with Docusaurus. |
I just pasted this modified file into my current Redux local repo Docusaurus install. The good news is that it does fix the original issue I described in #1137. Relative Markdown page links now work, including anchors. The bad news is that I found one other pattern we use heavily in our current docs files: absolute paths from the root of the repo. For example, here's one from an FAQ entry that links to another docs page:
I think part of the issue was wanting the links to work okay when rendered by Github. Is that something that's easily fixable? Or would we be better off trying to convert all docs links to be relative? |
@markerikson we don't recommend that absolute path because in versioned docs (which is the core of Docusaurus), e.g: if you are in v1.0.0, you would want to refer to v1.0.0 versioned docs I recommend converting it to how Docusaurus works. If in the future Redux is going to version their docs like how babel does, its going to work flawlessly |
Gotcha. Yeah, I went ahead and converted all the absolute links to relative ones last night. Can you put this out as a 1.6.1 release so that we can use it? Thanks! |
@endiliey Any word on releasing 1.6.1? I want to see if it fixed the issues I mentioned in the issue ticket as well. Thanks. |
Sorry for the delay ! Just released 1.6.1 to npm |
@endiliey thank you. unfortunately after upgrading, my issue does not seem resolved. the pertinent link is here: https://spothero.com/uniform/ace/docs/upgrading-v5/#code-splitting if you click on the The Am I misunderstanding something? Mis-linking? |
Its also worth noting that after the upgrade I noticed that when I went to upload my files to S3 almost all of them said "No change", almost as if it was not re-run at all. |
Actually, i'm getting a different issue when i ran development mode (i was going straight to production). I'm seeing this:
|
Disregard, disabling babel cache brought me back to the issue being discussed there. That being said, I'm not sure if that fix will fix my issue as well. |
1.6.2 should fix it @reintroducing Let us know how it goes |
@tibdex sorry for the late reply. Didnt notice the comment. Seems like a good idea, I will probably push a fix for relative linking on assets for next release |
@endiliey Just updated to 1.6.2 and it does not seem to have fixed the issue still :\ |
Send a reproducible repo in for bug report |
@endiliey there are a few issues with that. 1 being is that this only happens when its deployed to production and 2 is that this is pretty heavily tied to a private repo we have. i've tried to outline our setup above and i'd be happy to try and provide any info possible to help troubleshoot this. i'd also be happy to hop on a screenshare or similar if you wanted to live debug it, i just am not sure that trying to re-create this repo without actually pushing to production in this environment would be helpful. |
The production and development consume the same api for replaceAssetsLink. Either way a If you are deploying via a CI, node_modules cache is usually quite the problem. It's hard to fix it without any clonable & reproducible repo. I've at least confirmed with > 5 repo and it seems that 1.6.2 fixed the relative linking issue. Edit: |
@endiliey if i provide you with a repo that is just the docusaurus setup we have for that project, would that suffice? |
As long as we can reproduce the bug, that will be fine! Sorry for the trouble but that'd be helpful. There are lot of cases where we can't even reproduce the bug so we can't even fix it 😊 |
i went ahead and put the pertinent code on dropbox here: https://www.dropbox.com/s/eyqygyc0kv1cx8y/docusaurus-bug.zip?dl=0 As you can see, locally the issue i described here (#1138 (comment)) is fine, but when it goes to prod, which you can hit in the url provided in that comment, the result is not correct. let me know if you need anything else. |
@endiliey Just coming back to this and was wondering if you had a chance to look over the files I provided? |
Motivation
Fix #1137
Upon finding, we actually never really support relative markdown linking since initial release. Things has been working so far because lot of people refer to doc by doing
[test](dir1/test.md]
, however[test](../test.md)
will not work because we never really properly resolve it when replacing the markdown linkingThe key change here is this
Oh another thing is we no longer replace markdown linking in fenced blocks 👍
Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
docs-rebuild
branchDocusaurus/v1/lib/server/docs.js
toredux/website/node_modules/Docusaurus/lib/server/docs.js
Before
After
cc @markerikson