Merge pull request #1392 from mcanouil/docs/tip-include-path

docs: add tip about absolute path in include shortcode important callout

Author: cwickham

docs/authoring/includes.qmd

@@ -14,7 +14,9 @@ To include a file, add the `{{{< include >}}}` shortcode at the location in your
 
 ::: callout-important
 
-Include shortcodes are equivalent to copying and pasting the text from the included file into the main file. This means that relative references (links, images, etc.) inside the included file resolve based on the directory of the main file not the included file.
+Include shortcodes are equivalent to copying and pasting the text from the included file into the main file.
+This means that relative references (links, images, other includes, etc.) inside the included file resolve based on the directory of the main file not the included file.
+Use absolute (to the project root) paths for links, images, or other includes, in included files to ensure they resolve correctly, *e.g.*, `[A Figure Reused](/path/to/image.png)` or `{{< include /path/to/_file.qmd >}}`.
 
 It also means that if the included file has a metadata block, that block will take effect in all included files. In most cases, having metadata blocks in an included file will cause unexpected behavior.
 
@@ -110,4 +112,4 @@ code span.in {
   font-style:  normal;
 }
 </style>
-```
+```