Merge branch 'fix/callout-build-error'

Author: leecalcote

content/content-formatting-examples/demo.cast

@@ -0,0 +1,17 @@
+{"version": 2, "width": 80, "height": 24, "timestamp": 1700000000, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}}
+[0.5, "o", "$ "]
+[1.0, "o", "echo \"Welcome to the Academy!\""]
+[1.5, "o", "\r\n"]
+[1.6, "o", "Welcome to the Academy!\r\n"]
+[2.0, "o", "$ "]
+[2.5, "o", "hugo version"]
+[3.0, "o", "\r\n"]
+[3.1, "o", "hugo v0.158.0+extended darwin/amd64\r\n"]
+[3.5, "o", "$ "]
+[4.0, "o", "hugo server -D"]
+[4.5, "o", "\r\n"]
+[4.6, "o", "Start building sites...\r\n"]
+[5.0, "o", "Built in 2041 ms\r\n"]
+[5.2, "o", "Web Server is available at http://localhost:1313/\r\n"]
+[5.5, "o", "Press Ctrl+C to stop\r\n"]
+[6.0, "o", "$ "]

content/content-formatting-examples/example-notebook.ipynb

@@ -0,0 +1,88 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Sample Notebook\n",
+        "\n",
+        "This Jupyter notebook demonstrates how the `hextra/jupyter` shortcode renders notebook cells.\n",
+        "It supports **Markdown** cells, code cells with syntax highlighting, and cell outputs."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Hello from the Academy!\n"
+          ]
+        }
+      ],
+      "source": [
+        "# A simple Python greeting\n",
+        "message = \"Hello from the Academy!\"\n",
+        "print(message)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]"
+            ]
+          },
+          "execution_count": 2,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "source": [
+        "# Generate Fibonacci numbers\n",
+        "def fibonacci(n):\n",
+        "    a, b = 0, 1\n",
+        "    result = []\n",
+        "    for _ in range(n):\n",
+        "        a, b = b, a + b\n",
+        "        result.append(a)\n",
+        "    return result\n",
+        "\n",
+        "fibonacci(10)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Summary\n",
+        "\n",
+        "The notebook shortcode renders each cell in sequence:\n",
+        "\n",
+        "- **Markdown cells** are rendered as formatted text.\n",
+        "- **Code cells** are displayed as syntax-highlighted code blocks.\n",
+        "- **Outputs** (stream text and execution results) appear below their code cells."
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.12.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}

content/content-formatting-examples/index.md

@@ -522,47 +522,75 @@ Renders an inline SVG icon from `data/hextra/icons.yaml`. Useful for embedding i
 Embeds a PDF file in a responsive iframe.
 
 ```text
-{{</* hextra/pdf "/path/to/sample.pdf" */>}}
+{{</* hextra/pdf "sample.pdf" */>}}
 ```
 
-Supply a valid PDF path (page-bundle resource, asset, or absolute path) to render the embedded viewer.
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| positional | Path to the PDF file (page resource, asset, or absolute path) | _(required)_ |
+
+**Example:**
+
+{{< hextra/pdf "sample.pdf" >}}
 
 ---
 
 ### Include
 
-Includes the rendered content of another page inline. The parameter is the page path (relative to the content directory, without the file extension).
+Includes the rendered content of another page inline. This shortcode **must** use the percent-delimiter syntax.
 
 ```text
-{{%/* hextra/include "page-path" */%}}
+{{%/* hextra/include "include-snippet" */%}}
 ```
 
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| positional | Page path relative to the content directory | _(required)_ |
+
+**Example (included from a separate page):**
+
+{{% hextra/include "include-snippet" %}}
+
 ---
 
 ### Term
 
-Wraps a glossary term in an `<abbr>` tooltip. Definitions are sourced from `data/<lang>/termbase.yaml` (e.g., `data/en/termbase.yaml`).
+Wraps a glossary term in an `<abbr>` tooltip. Hover over the highlighted terms below to see their definitions. Definitions are sourced from `data/<lang>/termbase.yaml`.
 
 ```text
 {{</* hextra/term "API" */>}}
 ```
 
-To use this shortcode, create a termbase data file. For example, `data/en/termbase.yaml`:
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `entry` | Glossary abbreviation or full term (named or positional) | _(required)_ |
+
+To use this shortcode, create a termbase data file at `data/en/termbase.yaml`:
 
 ```yaml
 - abbr: API
   term: Application Programming Interface
   definition: A set of protocols for building software.
 ```
 
+**Examples:**
+
+Hugo is an {{< hextra/term "SSG" >}} that can be controlled via its {{< hextra/term "CLI" >}}. Configuration is written in {{< hextra/term "YAML" >}} and sites are commonly served through a {{< hextra/term "CDN" >}}. Most projects use a {{< hextra/term "CI/CD" >}} pipeline to deploy changes automatically. The theme exposes a rich {{< hextra/term "API" >}} of shortcodes and partials.
+
 ---
 
 ### Jupyter
 
 Renders a Jupyter Notebook (`.ipynb`) as code blocks and Markdown cells.
 
 ```text
-{{%/* hextra/jupyter "notebook.ipynb" */%}}
+{{%/* hextra/jupyter "example-notebook.ipynb" */%}}
 ```
 
 **Parameters:**
@@ -572,7 +600,9 @@ Renders a Jupyter Notebook (`.ipynb`) as code blocks and Markdown cells.
 | positional | Path or URL to the `.ipynb` file | _(required)_ |
 | `allowUnsafeHTML` | Set to `"true"` to render raw HTML from notebook outputs | `false` |
 
-Place a `.ipynb` file in the page bundle or `assets/` directory and reference it by name.
+**Example:**
+
+{{% hextra/jupyter "example-notebook.ipynb" %}}
 
 ---
 
@@ -596,7 +626,9 @@ Embeds an [asciinema](https://asciinema.org/) terminal recording player. The pla
 | `poster` | Poster/thumbnail specification | _(none)_ |
 | `markers` | Comma-separated time markers (e.g., `"5:Intro,10:Demo"`) | _(none)_ |
 
-Place a `.cast` file in the page bundle and reference it by name.
+**Example:**
+
+{{< hextra/asciinema file="demo.cast" speed="2" autoplay="true" loop="true" >}}
 
 ---
 

content/content-formatting-examples/sample.pdf

@@ -0,0 +1,12 @@
+---
+title: Includeable Snippet
+draft: true
+_build:
+  list: never
+  render: always
+---
+
+This paragraph was pulled in from a separate page using the `hextra/include` shortcode. It demonstrates how you can compose content from multiple sources into a single page.
+
+- Included content supports **full Markdown** formatting.
+- Lists, `code`, and _emphasis_ all render correctly.

content/include-snippet/index.md

@@ -0,0 +1,23 @@
+- abbr: API
+  term: Application Programming Interface
+  definition: A set of protocols and tools for building and integrating software applications.
+
+- abbr: CLI
+  term: Command-Line Interface
+  definition: A text-based interface used to interact with software by typing commands.
+
+- abbr: SSG
+  term: Static Site Generator
+  definition: A tool that generates a full static HTML website from raw data and templates.
+
+- abbr: CDN
+  term: Content Delivery Network
+  definition: A geographically distributed network of servers that delivers web content to users based on their location.
+
+- abbr: YAML
+  term: YAML Ain't Markup Language
+  definition: A human-readable data serialization format commonly used for configuration files.
+
+- abbr: CI/CD
+  term: Continuous Integration and Continuous Delivery
+  definition: Development practices that automate building, testing, and deploying code changes.