update to use % for raw markdown and document this option in shortcodes doc

projects/hugo/hugo-project-main.md

@@ -7,4 +7,4 @@ lastmod: '2025-03-30'
 tags: [hugo, framework, overview, documentation]
 ---
 
-{{< include "/srv/dev/hugo/wiki/README.md" >}}
+{{% include "/srv/dev/hugo/wiki/README.md" %}}

projects/hugo/hugo_shortcodes.md

@@ -13,8 +13,24 @@ lastmod: '2025-03-28'
 
 Custom shortcodes defined in `layouts/shortcodes/`.
 
-*   **`include`**: Include a Markdown file into another. Supports absolute paths (mapped to `private/`) and relative paths (relative to Hugo content).
+*   **`include`**: Inject the contents of external files into your page. Supports local Hugo content paths and absolute paths mounted from the host (e.g., `/srv/configs/...`, `/srv/dev/hugo/wiki/...`).
-    *   Usage: `{{/*  include "private/bazel/plan.md"*/}}` or `{{/*  include "/srv/docs/private/bazel/plan.md"*/}}`
+
+    **CRITICAL: Angle Brackets (`< >`) vs. Percentage Signs (`% %`)**
+    *   Use **`{{% %}}`** when you want the included text to be **parsed as Markdown**. This is required when including other `.md` files so their headers, lists, and links render properly.
+    *   Use **`{{< >}}`** to output the raw text directly *without* Markdown processing.
+
+    **Example 1: Including another Markdown file**
+    ```markdown
+    {{/*% include "/srv/dev/hugo/wiki/README.md" %*/}}
+    ```
+
+    **Example 2: Including raw code into a Code Block**
+    Wrap the shortcode in standard Markdown code fences to syntax-highlight an external configuration file:
+    ````markdown
+    ```yaml
+    {{/*% include "/srv/configs/docker_compose/homepage/docker-compose.yaml" %*/}}
+    ```
+    ````
 *   **`video`**: Embed local or remote videos.
     *   Usage: `{{/*  video src="path/to/video.mp4"*/}}`
 *   **`rawhtml`**: Insert raw HTML content.