Add note on absolute links (#2507)

* Add note on absolute links * Fix typos * Add tip to more pages * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Add negative example * Update docs/userGuide/troubleshooting.md Co-authored-by: Chan Yu Cheng <[email protected]> * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Add more details * Improve explanation * Improve look of tip * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Update docs/userGuide/syntax/includes.md Co-authored-by: Chan Yu Cheng <[email protected]> * Implement review changes --------- Co-authored-by: Chan Yu Cheng <[email protected]> Co-authored-by: Shuyao "Tim" Xu <[email protected]>
MarkBind · Apr 16, 2024 · fc776ba · fc776ba
1 parent fc71dd6
commit fc776ba
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 2 deletions.
diff --git a/docs/userGuide/syntax/includes.md b/docs/userGuide/syntax/includes.md
@@ -52,10 +52,34 @@ Tip 2. ...
 <box type="warning">
 
 When setting the `id` of a fragment, be careful not to clash with heading anchor IDs auto-generated by MarkBind. For example, if you have a heading `## Some Useful Tips`, MarkBind will auto-generate an ID `some-useful-tips` for that heading.
+</box>
+<include src="panels.md#script_and_styles_warning"></include>
+<div id="baseUrl-warning">
+<box type="warning" header="Add `{{ '{{ baseUrl }}' }}` to make your URLs absolute links if they may be reused in different contexts">
+
+Make an internal relative link an absolute link by adding `{{ '{{ baseUrl }}' }}` in front of the path. This allows the link to always point to the same target. Keep this in mind when putting content with links that is reused (eg: via `<include>`). This is because when your content is re-used, a relative link may no longer point to where you want it to.
+<div id="baseUrl-example">
+<panel header="Example of using absolute links in `<include>`">
+
+The file `folder1/file1.md` contains a link to `folder1/target.html`. The file `folder2/file2.md` contains `folder1/file1.md` using `<include>`.
+
+**In `folder2/file2.md`:** 
+```
+<include src="folder1/file1.md" />
+```
+<box type="success" header="Positive example">
 
+To ensure that the link will still point to `folder1/target.html`, use an **absolute link** in `folder1/file1.md` as such: `{{ '{{baseUrl}}' }}/folder1/target.html`.
 </box>
+<box type="wrong" header="Negative example">
 
-<include src="panels.md#script_and_styles_warning"></include>
+If a relative link `target.html` is used, the link in `folder2/file2.md` will point to `folder2/target.html` instead of `folder1/target.html`
+</box>
+</panel>
+<br/>
+</div>
+</box>
+</div>
 
 <include src="tip.md" boilerplate >
 <span id="tip_body">

diff --git a/docs/userGuide/syntax/panels.md b/docs/userGuide/syntax/panels.md
@@ -167,6 +167,8 @@ To safeguard against unintended consequences, consider directly incorporating th
 </variable>
 </include>
 
+<include src="includes.md#baseUrl-warning"/>
+
 **If `preload` attribute is provided, the panel body will load the HTML when the page renders instead of after being expanded.**
 
 <include src="codeAndOutput.md" boilerplate >

diff --git a/docs/userGuide/syntax/popovers.md b/docs/userGuide/syntax/popovers.md
@@ -71,6 +71,8 @@
 </variable>
 </include>
 
+<include src="includes.md#baseUrl-warning"/>
+
 **Using trigger for Popover:**<br>
 
 <include src="codeAndOutput.md" boilerplate >

diff --git a/docs/userGuide/troubleshooting.md b/docs/userGuide/troubleshooting.md
@@ -93,4 +93,13 @@ You could signpost Markdown either by:
 <box> **This will be rendered as plain text**</box>
 </variable>
 </include>
-</panel>
+</panel>
+
+##### Content with local links not working when included with `<include>`
+
+If you notice that relative links in a page pointing to another page no longer works after adding it into a page via `<include>`, it may be because the relative link no longer points to the correct address in the new page with `<include>`. 
+
+To solve this, change the relative URL into an **absolute** URL by adding `{{ '{{ baseUrl }}' }}`. This will ensure that the link will always point to the same address regardless of the page it is included in.
+
+<include src="syntax/includes.md#baseUrl-example"/>
+