layer5io · leecalcote · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026 · Apr 1, 2026
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -0,0 +1,72 @@
+name: Build and Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - ".github/**"
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Hugo site
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Setup Hugo Extended
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "0.147.9"
+          extended: true
+
+      - name: Install Node.js dependencies
+        run: npm ci
+
+      - name: Build Hugo site
+        run: |
+          hugo --minify \
+            --baseURL "https://${{ github.repository_owner }}.github.io/academy-example/"
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./public
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/master' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,7 +3,7 @@ Please do! Thanks for your help improving the project! :balloon:
 
 All contributors are welcome. Please see the [newcomers welcome guide](https://layer5.io/community/newcomers) for how, where and why to contribute. This project is community-built and welcomes collaboration. Contributors are expected to adhere to our [Code of Conduct](.CODE_OF_CONDUCT.md).
 
-Not sure where to start? First, see the [newcomers welcome guide](https://docs.google.com/document/d/17OPtDE_rdnPQxmk2Kauhm3GwXF1R5dZ3Cj8qZLKdo5E/edit). Grab an open issue with the [help-wanted label](../../labels/help%20wanted) and jump in. Join the [Slack account](http://slack.layer5.io) and engage in conversation. Create a [new issue](/../../issues/new/choose) if needed.  All [pull requests](/../../pulls) should reference an open [issue](/../../issues). Include keywords in your pull request descriptions, as well as commit messages, to [automatically close issues in GitHub](https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords).
+Not sure where to start? First, see the [newcomers welcome guide](https://layer5.io/community/newcomers). Grab an open issue with the [help-wanted label](../../labels/help%20wanted) and jump in. Join the [Slack account](http://slack.layer5.io) and engage in conversation. Create a [new issue](/../../issues/new/choose) if needed.  All [pull requests](/../../pulls) should reference an open [issue](/../../issues). Include keywords in your pull request descriptions, as well as commit messages, to [automatically close issues in GitHub](https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords).
 
 **Sections**
 - <a name="contributing">General Contribution Flow</a>

diff --git a/Makefile b/Makefile
@@ -38,6 +38,7 @@ site: check-go
 ## Empty build cache and run on your local machine.
 clean: 
 	hugo --cleanDestinationDir
+	make setup
 	make site
 
 ## ------------------------------------------------------------

diff --git a/content/content-formatting-examples/demo.cast b/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", "$ "]
diff --git a/content/content-formatting-examples/example-notebook.ipynb b/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
+}
diff --git a/content/content-formatting-examples/index.md b/content/content-formatting-examples/index.md
@@ -196,7 +196,7 @@ This is a superscript number for your footnote. [^1]
 The shortcodes below are ported from the [Hextra Hugo theme](https://imfing.github.io/hextra/docs/guide/shortcodes/) and adapted to work with Bootstrap 5. They are all namespaced under `hextra/` to avoid conflicts with Academy, Docsy, and Hugo built-in shortcodes.
 
 {{< hextra/callout type="info" >}}
-All Hextra shortcodes use the **angle-bracket** syntax `{{</* */>}}` (not the percent syntax `{{%/* */%}}`). This ensures raw HTML output is preserved correctly.
+All Hextra shortcodes use the **angle-bracket** delimiter syntax (not the percent delimiter syntax). This ensures raw HTML output is preserved correctly. See the usage examples below for the correct invocation pattern.
 {{< /hextra/callout >}}
 
 ### Callout
@@ -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" >}}
 
 ---
 

diff --git a/content/content-formatting-examples/sample.pdf b/content/content-formatting-examples/sample.pdf
diff --git a/content/include-snippet/index.md b/content/include-snippet/index.md
@@ -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.
diff --git a/data/en/termbase.yaml b/data/en/termbase.yaml
@@ -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.
diff --git a/go.mod b/go.mod
@@ -9,6 +9,6 @@ replace github.com/FortAwesome/Font-Awesome v4.7.0+incompatible => github.com/Fo
 
 require (
 	github.com/FortAwesome/Font-Awesome v4.7.0+incompatible // indirect
-	github.com/layer5io/academy-theme v0.4.2 // indirect
+	github.com/layer5io/academy-theme v0.4.5 // indirect
 	github.com/twbs/bootstrap v5.3.7+incompatible // indirect
 )
diff --git a/go.sum b/go.sum
@@ -26,5 +26,7 @@ github.com/layer5io/academy-theme v0.4.0 h1:qVF0aENeXVUzmdDFeQbaWFY7YjxO94O6o9VQ
 github.com/layer5io/academy-theme v0.4.0/go.mod h1:Dv72UWsREOvX4Zg4mJjrpoyDxdgxxpiDotxqYBXMjXo=
 github.com/layer5io/academy-theme v0.4.2 h1:uwaXj61bXLwWFHD8wAncQbtMiqvbbE24pKE2ocp0JbQ=
 github.com/layer5io/academy-theme v0.4.2/go.mod h1:Dv72UWsREOvX4Zg4mJjrpoyDxdgxxpiDotxqYBXMjXo=
+github.com/layer5io/academy-theme v0.4.5 h1:SfjQ63uYxgtsqdo8qPjvr7/9ygkMQZK80BO+6piWUaQ=
+github.com/layer5io/academy-theme v0.4.5/go.mod h1:Dv72UWsREOvX4Zg4mJjrpoyDxdgxxpiDotxqYBXMjXo=
 github.com/twbs/bootstrap v5.3.7+incompatible h1:ea1W8TOWZFkqSK2M0McpgzLiUQVru3bz8aHb0j/XtuM=
 github.com/twbs/bootstrap v5.3.7+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
diff --git a/package-lock.json b/package-lock.json