Broken links detected for the deployment to devdocs #2179
Comments
|
Hi @tlylt! I tried to fix the links by removing |
|
@itsyme thanks for investigating. Could you help me test by trying to build just the dg (like in the github workflow) locally and see if the navigation to UG still works? I suspect that's not the case and if this is so then we might need to relook at our docs deployment strategy. |
|
Hi @tlylt! I managed to build the DG however when I tried to deploy it using |
It's ok, I was talking about building and not deploying. Deploying can only be done with the access token. |
|
Hi @tlylt! Sorry for the confusion. When opening the developer guide locally after the changes made, the links to the user guide don't work. |
|
Thank you @itsyme for the testing. I think we will need further discussion on how to fix this issue. To test locally:
It seems like building and deploying the same site (or parts of the same site, in our case, UG, and DG) separately via different site.json is going to be problematic for intra-site link management. @damithc have you encountered something similar for other MarkBind sites? Some related work done trying to fix this problem:
Pinging @MarkBind/active-devs for context/comments/suggestions on what's the best way forward. |
tlylt
added
a-Documentation 📝
s.UnderDiscussion
|
Would it help if we implemented a feature that allows users to specify alternate baseURLs in their site.json? For instance, we allow users to specify {
"baseUrl": "...",
"altUrls": {
"devGuide": "...",
"userGuide": "..."
},
}They can then use these URLs in their pages, e.g. This may solve the issue as we can specify different URLs in our As a bonus, it could also allow authors to specify shorthands for various links. Would such a feature solve this issue? |
Thank you @jovyntls, I think that gave me some inspiration on how to proceed. I think fundamentally building the UG and the DG separately will result in broken link issues if a cross-reference is done. This is because the individual site has no way to access the content outside of it. So locally, the relative links to another site will not work at all. However, when deployed to the cloud, the fact that the UG and DG share the same domain but different base URL means they can create an illusion that the two exist together. I think what you are suggesting might also be possible with the use of "tags", perhaps similar to how we are using the "environment--dg" to handle decision to display the link to DG in our navigation bar. @itsyme would you like to try and see if that leads to a viable solution? |
Hi @tlylt! Is this approach in line with what you have in mind?
|
Yes, something like that. Can it be done just by manipulating the existing two tags? If not creating a new tag is fine as well. |
Please confirm that you have searched existing issues in the repo
Yes, I have searched the existing issues
Any related issues?
No response
Tell us about your environment
Windows 10
MarkBind version
Master branch
Describe the bug and the steps to reproduce it
See logs in every CI run for recently merged PRs, in Deploy DG on any commit to master, to markbind.org/devdocs
(This is likely due to how the site.json and host differs for the build of our docs into different domains)
And the intra-site links are indeed broken, e.g.
Expected behavior
No broken link and no warning logged.
Anything else?
No response
The text was updated successfully, but these errors were encountered: