Merge pull request #1406 from quarto-dev/sync-1392-to-prerelease

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>
-```
+```