From 9c35f9bd48aef7d890fee975757bf2c95dd68e8d Mon Sep 17 00:00:00 2001 From: leecalcote Date: Thu, 2 Apr 2026 04:32:14 +0000 Subject: [PATCH 1/7] Update academy-theme to v0.4.5 Signed-off-by: leecalcote Signed-off-by: Lee Calcote --- go.mod | 2 +- go.sum | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 6f5445df..59bc897e 100644 --- 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 index 7599ee02..a35718fd 100644 --- 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= From 7375e9a58483399d96abdc28d6bb4a57078a8098 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Wed, 1 Apr 2026 23:53:02 -0500 Subject: [PATCH 2/7] Fix callout build error caused by escaped shortcode syntax in body Hugo resolves escaped shortcode delimiters (e.g. {{}}) to literal {{< >}} inside .InnerDeindent, which then causes markdownify to fail with "shortcode has no name". Reword the callout text to avoid embedded shortcode delimiter literals. Signed-off-by: Lee Calcote --- content/content-formatting-examples/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/content-formatting-examples/index.md b/content/content-formatting-examples/index.md index d7796ced..cbb5608f 100644 --- 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 From 6b2dac8f875a9d9f6a8b02b4d5beda679b8bc921 Mon Sep 17 00:00:00 2001 From: Bhumika Garg Date: Wed, 1 Apr 2026 23:37:05 +0530 Subject: [PATCH 3/7] fix: remove public directory in clean target Signed-off-by: Bhumika Garg Signed-off-by: Lee Calcote --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index cc6955c7..697a47fd 100644 --- 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 ## ------------------------------------------------------------ From d87cf37390a01f7d9651494e0d8f056b269d5e0a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 26 Mar 2026 05:10:02 +0000 Subject: [PATCH 4/7] Bump picomatch Bumps and [picomatch](https://github.com/micromatch/picomatch). These dependencies needed to be updated together. Updates `picomatch` from 2.3.1 to 2.3.2 - [Release notes](https://github.com/micromatch/picomatch/releases) - [Changelog](https://github.com/micromatch/picomatch/blob/master/CHANGELOG.md) - [Commits](https://github.com/micromatch/picomatch/compare/2.3.1...2.3.2) Updates `picomatch` from 4.0.2 to 4.0.4 - [Release notes](https://github.com/micromatch/picomatch/releases) - [Changelog](https://github.com/micromatch/picomatch/blob/master/CHANGELOG.md) - [Commits](https://github.com/micromatch/picomatch/compare/2.3.1...2.3.2) --- updated-dependencies: - dependency-name: picomatch dependency-version: 2.3.2 dependency-type: indirect - dependency-name: picomatch dependency-version: 4.0.4 dependency-type: indirect ... Signed-off-by: dependabot[bot] Signed-off-by: Lee Calcote --- package-lock.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/package-lock.json b/package-lock.json index 716b2855..638640b3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -636,9 +636,9 @@ "license": "ISC" }, "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz", + "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==", "dev": true, "license": "MIT", "engines": { @@ -996,9 +996,9 @@ } }, "node_modules/tinyglobby/node_modules/picomatch": { - "version": "4.0.2", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.2.tgz", - "integrity": "sha512-M7BAV6Rlcy5u+m6oPhAPFgJTzAioX/6B0DxyvDlo9l8+T3nLKbrczg2WLUyzd45L8RqfUMyGPzekbMvX2Ldkwg==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz", + "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==", "dev": true, "license": "MIT", "engines": { From c282bc5452af6b2190efad81bf6ee861dd6f295d Mon Sep 17 00:00:00 2001 From: Raunak Madan <143412156+CodexRaunak@users.noreply.github.com> Date: Tue, 6 Jan 2026 06:27:25 +0530 Subject: [PATCH 5/7] Update newcomers guide link in CONTRIBUTING.md Signed-off-by: Raunak Madan <143412156+CodexRaunak@users.noreply.github.com> Signed-off-by: Lee Calcote --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 33ab6b51..23501e21 100644 --- 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** - General Contribution Flow From 82a1321ada59eba8d38c17595336e6a6169e4193 Mon Sep 17 00:00:00 2001 From: YASHMAHAKAL Date: Thu, 2 Apr 2026 01:04:33 +0530 Subject: [PATCH 6/7] ci: add GitHub Pages build and deploy workflow Signed-off-by: YASHMAHAKAL Signed-off-by: Lee Calcote --- .github/workflows/gh-pages.yml | 72 ++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 00000000..4b566546 --- /dev/null +++ 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 From b87fd05bac5b0fcb1178f338dbc1cf3edb815fa6 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 2 Apr 2026 09:09:09 -0500 Subject: [PATCH 7/7] Add live rendered examples for all Hextra shortcodes Previously PDF, include, term, jupyter, and asciinema shortcodes only had syntax documentation with no rendered output. This commit adds the supporting assets and data files needed to produce live examples: - sample.pdf: minimal PDF for the hextra/pdf embed demo - example-notebook.ipynb: Jupyter notebook with markdown, code, and output cells for the hextra/jupyter demo - demo.cast: asciinema terminal recording for the hextra/asciinema demo - data/en/termbase.yaml: glossary definitions (API, CLI, SSG, CDN, YAML, CI/CD) for the hextra/term tooltip demo - content/include-snippet: standalone page included inline via hextra/include Every Hextra shortcode now has a live rendered example on the content formatting examples page. Signed-off-by: Lee Calcote --- content/content-formatting-examples/demo.cast | 17 ++++ .../example-notebook.ipynb | 88 ++++++++++++++++++ content/content-formatting-examples/index.md | 50 ++++++++-- .../content-formatting-examples/sample.pdf | Bin 0 -> 538 bytes content/include-snippet/index.md | 12 +++ data/en/termbase.yaml | 23 +++++ 6 files changed, 181 insertions(+), 9 deletions(-) create mode 100644 content/content-formatting-examples/demo.cast create mode 100644 content/content-formatting-examples/example-notebook.ipynb create mode 100644 content/content-formatting-examples/sample.pdf create mode 100644 content/include-snippet/index.md create mode 100644 data/en/termbase.yaml diff --git a/content/content-formatting-examples/demo.cast b/content/content-formatting-examples/demo.cast new file mode 100644 index 00000000..31de1430 --- /dev/null +++ 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 new file mode 100644 index 00000000..aa42cda2 --- /dev/null +++ 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 index cbb5608f..9bd05303 100644 --- a/content/content-formatting-examples/index.md +++ b/content/content-formatting-examples/index.md @@ -522,32 +522,56 @@ Renders an inline SVG icon from `data/hextra/icons.yaml`. Useful for embedding i Embeds a PDF file in a responsive iframe. ```text -{{}} +{{}} ``` -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 `` tooltip. Definitions are sourced from `data//termbase.yaml` (e.g., `data/en/termbase.yaml`). +Wraps a glossary term in an `` tooltip. Hover over the highlighted terms below to see their definitions. Definitions are sourced from `data//termbase.yaml`. ```text {{}} ``` -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 @@ -555,6 +579,10 @@ To use this shortcode, create a termbase data file. For example, `data/en/termba 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 @@ -562,7 +590,7 @@ To use this shortcode, create a termbase data file. For example, `data/en/termba 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 new file mode 100644 index 0000000000000000000000000000000000000000..42931ff3cbb7bda5be8838ee5c31a863ca708bf0 GIT binary patch literal 538 zcmZWmL2kk@5WM>pdqHXst>eTAMM611L6zF7DCCAX7_y;3Ax5^TXkXuTpb(XnA}g~q zp4oM8_B?$MkCF)pK(DsLAhQuOxxpeyyZz%iqpBJW?QmZGAS67~n%?NNIcA+QuFWVT$$GuX$MhFb CbCc)* literal 0 HcmV?d00001 diff --git a/content/include-snippet/index.md b/content/include-snippet/index.md new file mode 100644 index 00000000..b6ac97e9 --- /dev/null +++ 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 new file mode 100644 index 00000000..e44062e8 --- /dev/null +++ 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.