diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..4b56654 --- /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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 33ab6b5..23501e2 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 diff --git a/Makefile b/Makefile index cc6955c..697a47f 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 ## ------------------------------------------------------------ diff --git a/content/content-formatting-examples/demo.cast b/content/content-formatting-examples/demo.cast new file mode 100644 index 0000000..31de143 --- /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 0000000..aa42cda --- /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 d7796ce..9bd0530 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 @@ -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 0000000..42931ff Binary files /dev/null and b/content/content-formatting-examples/sample.pdf differ diff --git a/content/include-snippet/index.md b/content/include-snippet/index.md new file mode 100644 index 0000000..b6ac97e --- /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 0000000..e44062e --- /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. diff --git a/go.mod b/go.mod index 6f5445d..59bc897 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 7599ee0..a35718f 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= diff --git a/package-lock.json b/package-lock.json index 716b285..638640b 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": {