Add tags to links in docs #2183
Conversation
|
Thanks @itsyme, could you help to double-check and fix all instances of the existing absolute links from UG to DG (and from DG to UG), such as this one that's not yet updated: |
|
@itsyme can you add the reasoning in the commit message pls. This PR a bit weird without context. |
| @@ -55,7 +55,7 @@ Ensure that you can serve the MarkBind documentation site in development mode. Y | |||
|
|
|||
| In the following steps, we will be fixing a hypothetical typo. You do not need to commit the changes or raise a PR, but understand the context and follow the steps to get a feel for the process. | |||
|
|
|||
| **!!Let's suppose we want to change the use of "Pop-Up" in our [user guide](../../userGuide/components/popups.html) to "Popup" (i.e. remove the hyphen).!!** | |||
| **!!Let's suppose we want to change the use of "Pop-Up" in our <a tags="environment--combined" href="/userGuide/components/popups.html">user guide</a><a tags="environment--dg" href="https://markbind.org/userGuide/components/popups.html">user guide</a> to "Popup" (i.e. remove the hyphen).!!** | |||
There was a problem hiding this comment.
If we are switching to the new combined tag, do we still need the anchor with tags="environment --dg", and if so, in what situations do we need them?
^ This comment applies for all occurrences of this!
There was a problem hiding this comment.
Hi @lhw-1! We are not exactly switching to the new combined tag, we are adding a new combined tag to differentiate when using serving the site.json which displays both the ug and dg together and serving dg-site.json and ug-site.json individually as the individual dg and ug do not have access to the intra-linked files between them
There was a problem hiding this comment.
Hi @lhw-1! We are not exactly switching to the new combined tag, we are adding a new combined tag to differentiate when using serving the
site.jsonwhich displays both the ug and dg together and servingdg-site.jsonandug-site.jsonindividually as the individual dg and ug do not have access to the intra-linked files between them
👍 so there are three scenarios:
- DG + UG - markbind-master via netlify
- DG - markbind.org via github pages
- UG - markbind.org/devdocs via github pages
There was a problem hiding this comment.
Hi @lhw-1! We are not exactly switching to the new combined tag, we are adding a new combined tag to differentiate when using serving the
site.jsonwhich displays both the ug and dg together and servingdg-site.jsonandug-site.jsonindividually as the individual dg and ug do not have access to the intra-linked files between them
Yep, that makes sense!
I think that just as a side note, the duplication of the anchor tags seem unnecessary - a method of declaring an alternate syntax for tags that do not provide such a way could be something to look into. For instance, it would be nice to be able to declare <a tags="environment--combined" href="/userGuide/components/popups.html">user guide</a><alt tags="environment--dg" href="https://markbind.org/userGuide/components/popups.html" />.
There was a problem hiding this comment.
Yep, that makes sense!
I think that just as a side note, the duplication of the anchor tags seem unnecessary - a method of declaring an alternate syntax for tags that do not provide such a way could be something to look into. For instance, it would be nice to be able to declare
<a tags="environment--combined" href="/userGuide/components/popups.html">user guide</a><alt tags="environment--dg" href="https://markbind.org/userGuide/components/popups.html" />.
I think thats a great idea! Do you want to open an issue to request that feature?
What is the purpose of this pull request?
Overview of changes:
Resolves #2179. Added tags to links in docs to differentiate between when both user guide and developer guide are being built together and when only user guide or developer guide is being built alone.
Anything you'd like to highlight/discuss:
Testing instructions:
Proposed commit message: (wrap lines at 72 characters)
Add tags to links in docs
Links in docs referencing other sections of MarkBind are all
written in the intra-link form.
This causes confusion when serving the user guide or developer
guide individually as the files to these intra-links are not accessible.
Let's differentiate the links with tags based on the environment,
having intra-links for when the user guide and developer guide are
served together and absolute links for when the user guide and
developer guide are served seperately.
This allows the right behaviour for both situations and creates an
illusion that the user guide and developer guide exist together even
when served separately.
Checklist: ☑️