Add note on absolute links

docs/userGuide/syntax/includes.md

@@ -56,6 +56,35 @@ When setting the `id` of a fragment, be careful not to clash with heading anchor
 </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>`) as 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>`" type="info">
+
+The file `folder1/file1.md` contains a link to `folder1/target.html`. The file `folder2/file2.md` contains a fragment from `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">
+
+If a relative link `target.html` is used, the link will point to `folder2/target.html` instead of `folder1/target.html`
+</box>
+</panel>
+</div>
+
+</box>
+</div>
 
 <include src="tip.md" boilerplate >
 <span id="tip_body">

docs/userGuide/syntax/links.md

@@ -99,6 +99,8 @@ To ensure that links in the <code>_markbind/</code> folder work correctly across
 {% endraw %}
 </div>
 
+<include src="includes.md#baseUrl-warning"/>
+
 ****Relative paths****
 
 <div class="indented">

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 >

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 >

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"/>
+