Skip to content

Commit b87fd05

Browse files
leecalcoteleecalcote
committed
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 <lee.calcote@layer5.io>
1 parent 82a1321 commit b87fd05

File tree

6 files changed

+181
-9
lines changed

6 files changed

+181
-9
lines changed

‎content/content-formatting-examples/demo.cast‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{"version": 2, "width": 80, "height": 24, "timestamp": 1700000000, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}}
2+
[0.5, "o", "$ "]
3+
[1.0, "o", "echo \"Welcome to the Academy!\""]
4+
[1.5, "o", "\r\n"]
5+
[1.6, "o", "Welcome to the Academy!\r\n"]
6+
[2.0, "o", "$ "]
7+
[2.5, "o", "hugo version"]
8+
[3.0, "o", "\r\n"]
9+
[3.1, "o", "hugo v0.158.0+extended darwin/amd64\r\n"]
10+
[3.5, "o", "$ "]
11+
[4.0, "o", "hugo server -D"]
12+
[4.5, "o", "\r\n"]
13+
[4.6, "o", "Start building sites...\r\n"]
14+
[5.0, "o", "Built in 2041 ms\r\n"]
15+
[5.2, "o", "Web Server is available at http://localhost:1313/\r\n"]
16+
[5.5, "o", "Press Ctrl+C to stop\r\n"]
17+
[6.0, "o", "$ "]

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Sample Notebook\n",
8+
"\n",
9+
"This Jupyter notebook demonstrates how the `hextra/jupyter` shortcode renders notebook cells.\n",
10+
"It supports **Markdown** cells, code cells with syntax highlighting, and cell outputs."
11+
]
12+
},
13+
{
14+
"cell_type": "code",
15+
"execution_count": 1,
16+
"metadata": {},
17+
"outputs": [
18+
{
19+
"name": "stdout",
20+
"output_type": "stream",
21+
"text": [
22+
"Hello from the Academy!\n"
23+
]
24+
}
25+
],
26+
"source": [
27+
"# A simple Python greeting\n",
28+
"message = \"Hello from the Academy!\"\n",
29+
"print(message)"
30+
]
31+
},
32+
{
33+
"cell_type": "code",
34+
"execution_count": 2,
35+
"metadata": {},
36+
"outputs": [
37+
{
38+
"data": {
39+
"text/plain": [
40+
"[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]"
41+
]
42+
},
43+
"execution_count": 2,
44+
"metadata": {},
45+
"output_type": "execute_result"
46+
}
47+
],
48+
"source": [
49+
"# Generate Fibonacci numbers\n",
50+
"def fibonacci(n):\n",
51+
" a, b = 0, 1\n",
52+
" result = []\n",
53+
" for _ in range(n):\n",
54+
" a, b = b, a + b\n",
55+
" result.append(a)\n",
56+
" return result\n",
57+
"\n",
58+
"fibonacci(10)"
59+
]
60+
},
61+
{
62+
"cell_type": "markdown",
63+
"metadata": {},
64+
"source": [
65+
"## Summary\n",
66+
"\n",
67+
"The notebook shortcode renders each cell in sequence:\n",
68+
"\n",
69+
"- **Markdown cells** are rendered as formatted text.\n",
70+
"- **Code cells** are displayed as syntax-highlighted code blocks.\n",
71+
"- **Outputs** (stream text and execution results) appear below their code cells."
72+
]
73+
}
74+
],
75+
"metadata": {
76+
"kernelspec": {
77+
"display_name": "Python 3",
78+
"language": "python",
79+
"name": "python3"
80+
},
81+
"language_info": {
82+
"name": "python",
83+
"version": "3.12.0"
84+
}
85+
},
86+
"nbformat": 4,
87+
"nbformat_minor": 4
88+
}

‎content/content-formatting-examples/index.md‎

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -522,47 +522,75 @@ Renders an inline SVG icon from `data/hextra/icons.yaml`. Useful for embedding i
522522
Embeds a PDF file in a responsive iframe.
523523

524524
```text
525-
{{</* hextra/pdf "/path/to/sample.pdf" */>}}
525+
{{</* hextra/pdf "sample.pdf" */>}}
526526
```
527527

528-
Supply a valid PDF path (page-bundle resource, asset, or absolute path) to render the embedded viewer.
528+
**Parameters:**
529+
530+
| Parameter | Description | Default |
531+
|-----------|-------------|---------|
532+
| positional | Path to the PDF file (page resource, asset, or absolute path) | _(required)_ |
533+
534+
**Example:**
535+
536+
{{< hextra/pdf "sample.pdf" >}}
529537

530538
---
531539

532540
### Include
533541

534-
Includes the rendered content of another page inline. The parameter is the page path (relative to the content directory, without the file extension).
542+
Includes the rendered content of another page inline. This shortcode **must** use the percent-delimiter syntax.
535543

536544
```text
537-
{{%/* hextra/include "page-path" */%}}
545+
{{%/* hextra/include "include-snippet" */%}}
538546
```
539547

548+
**Parameters:**
549+
550+
| Parameter | Description | Default |
551+
|-----------|-------------|---------|
552+
| positional | Page path relative to the content directory | _(required)_ |
553+
554+
**Example (included from a separate page):**
555+
556+
{{% hextra/include "include-snippet" %}}
557+
540558
---
541559

542560
### Term
543561

544-
Wraps a glossary term in an `<abbr>` tooltip. Definitions are sourced from `data/<lang>/termbase.yaml` (e.g., `data/en/termbase.yaml`).
562+
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`.
545563

546564
```text
547565
{{</* hextra/term "API" */>}}
548566
```
549567

550-
To use this shortcode, create a termbase data file. For example, `data/en/termbase.yaml`:
568+
**Parameters:**
569+
570+
| Parameter | Description | Default |
571+
|-----------|-------------|---------|
572+
| `entry` | Glossary abbreviation or full term (named or positional) | _(required)_ |
573+
574+
To use this shortcode, create a termbase data file at `data/en/termbase.yaml`:
551575

552576
```yaml
553577
- abbr: API
554578
term: Application Programming Interface
555579
definition: A set of protocols for building software.
556580
```
557581
582+
**Examples:**
583+
584+
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.
585+
558586
---
559587
560588
### Jupyter
561589
562590
Renders a Jupyter Notebook (`.ipynb`) as code blocks and Markdown cells.
563591

564592
```text
565-
{{%/* hextra/jupyter "notebook.ipynb" */%}}
593+
{{%/* hextra/jupyter "example-notebook.ipynb" */%}}
566594
```
567595

568596
**Parameters:**
@@ -572,7 +600,9 @@ Renders a Jupyter Notebook (`.ipynb`) as code blocks and Markdown cells.
572600
| positional | Path or URL to the `.ipynb` file | _(required)_ |
573601
| `allowUnsafeHTML` | Set to `"true"` to render raw HTML from notebook outputs | `false` |
574602

575-
Place a `.ipynb` file in the page bundle or `assets/` directory and reference it by name.
603+
**Example:**
604+
605+
{{% hextra/jupyter "example-notebook.ipynb" %}}
576606

577607
---
578608

@@ -596,7 +626,9 @@ Embeds an [asciinema](https://asciinema.org/) terminal recording player. The pla
596626
| `poster` | Poster/thumbnail specification | _(none)_ |
597627
| `markers` | Comma-separated time markers (e.g., `"5:Intro,10:Demo"`) | _(none)_ |
598628

599-
Place a `.cast` file in the page bundle and reference it by name.
629+
**Example:**
630+
631+
{{< hextra/asciinema file="demo.cast" speed="2" autoplay="true" loop="true" >}}
600632

601633
---
602634

‎content/content-formatting-examples/sample.pdf‎

538 Bytes
Binary file not shown.

‎content/include-snippet/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Includeable Snippet
3+
draft: true
4+
_build:
5+
list: never
6+
render: always
7+
---
8+
9+
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.
10+
11+
- Included content supports **full Markdown** formatting.
12+
- Lists, `code`, and _emphasis_ all render correctly.

‎data/en/termbase.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
- abbr: API
2+
term: Application Programming Interface
3+
definition: A set of protocols and tools for building and integrating software applications.
4+
5+
- abbr: CLI
6+
term: Command-Line Interface
7+
definition: A text-based interface used to interact with software by typing commands.
8+
9+
- abbr: SSG
10+
term: Static Site Generator
11+
definition: A tool that generates a full static HTML website from raw data and templates.
12+
13+
- abbr: CDN
14+
term: Content Delivery Network
15+
definition: A geographically distributed network of servers that delivers web content to users based on their location.
16+
17+
- abbr: YAML
18+
term: YAML Ain't Markup Language
19+
definition: A human-readable data serialization format commonly used for configuration files.
20+
21+
- abbr: CI/CD
22+
term: Continuous Integration and Continuous Delivery
23+
definition: Development practices that automate building, testing, and deploying code changes.

0 commit comments

Comments
 (0)