Skip to content

Commit a1288dd

Browse files
leecalcoteleecalcote
committed
hextra shortcodes
Signed-off-by: Lee Calcote <lee.calcote@layer5.io>
1 parent 7edcc14 commit a1288dd

File tree

4 files changed

+388
-1
lines changed

4 files changed

+388
-1
lines changed

‎.claude/launch.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"version": "0.0.1",
3+
"configurations": [
4+
{
5+
"name": "hugo-dev",
6+
"runtimeExecutable": "/usr/local/bin/hugo",
7+
"runtimeArgs": ["server", "-D", "--port", "1314"],
8+
"port": 1314,
9+
"env": {
10+
"PATH": "/usr/local/go/bin:/usr/local/bin:/usr/bin:/bin"
11+
}
12+
}
13+
]
14+
}

‎content/hextra-shortcodes-examples/index.md‎

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
---
2+
title: Hextra Shortcodes Examples
3+
weight: 6
4+
description: Demonstrations of every Hextra shortcode ported to the Academy theme. Each shortcode is namespaced under hextra/ to avoid conflicts with existing Academy, Docsy, and Hugo shortcodes.
5+
draft: true
6+
---
7+
8+
This page exercises every shortcode ported from the [Hextra](https://imfing.github.io/hextra/docs/guide/shortcodes/) Hugo theme. All shortcodes are invoked with the `hextra/` prefix.
9+
10+
{{< alert type="note" title="Test Page: Not for Production" >}}
11+
This page will not be published in the production version of the site. It is only visible during local preview and serves as a rendering test for the Hextra shortcodes.
12+
{{< /alert >}}
13+
14+
---
15+
16+
## Callout
17+
18+
Callouts highlight important information. Five types are supported: **default**, **info**, **warning**, **error**, and **important**.
19+
20+
{{< hextra/callout >}}
21+
This is a **default** callout. It uses a light-bulb icon and green styling.
22+
{{< /hextra/callout >}}
23+
24+
{{< hextra/callout type="info" >}}
25+
This is an **info** callout. Use it to surface supplementary context.
26+
{{< /hextra/callout >}}
27+
28+
{{< hextra/callout type="warning" >}}
29+
This is a **warning** callout. Draw attention to potential issues.
30+
{{< /hextra/callout >}}
31+
32+
{{< hextra/callout type="error" >}}
33+
This is an **error** callout. Indicate something that went wrong.
34+
{{< /hextra/callout >}}
35+
36+
{{< hextra/callout type="important" >}}
37+
This is an **important** callout. Emphasize critical information.
38+
{{< /hextra/callout >}}
39+
40+
### Callout with emoji
41+
42+
{{< hextra/callout emoji="🚀" >}}
43+
You can use an **emoji** instead of an icon.
44+
{{< /hextra/callout >}}
45+
46+
---
47+
48+
## Cards
49+
50+
Cards display content in a responsive grid. Wrap individual `hextra/card` shortcodes inside a `hextra/cards` container.
51+
52+
### Basic cards (3 columns, default)
53+
54+
{{< hextra/cards >}}
55+
{{< hextra/card link="https://gohugo.io" title="Hugo" subtitle="The world's fastest static site generator." icon="document-text" >}}
56+
{{< hextra/card link="https://getbootstrap.com" title="Bootstrap" subtitle="Build fast, responsive sites with Bootstrap." icon="folder" >}}
57+
{{< hextra/card link="https://github.com" title="GitHub" subtitle="Where the world builds software." icon="information-circle" >}}
58+
{{< /hextra/cards >}}
59+
60+
### Two-column cards
61+
62+
{{< hextra/cards cols="2" >}}
63+
{{< hextra/card title="Card without link" subtitle="This card has no link — it is not clickable." >}}
64+
{{< hextra/card link="/" title="Card with tag" subtitle="This card sports a badge tag." tag="New" tagColor="success" >}}
65+
{{< /hextra/cards >}}
66+
67+
---
68+
69+
## Details
70+
71+
A collapsible content block built on the native `<details>` element.
72+
73+
{{< hextra/details title="Click to expand this section" >}}
74+
Here is the hidden content revealed when the summary is clicked.
75+
76+
- Supports **Markdown** formatting
77+
- Lists, `code`, and _emphasis_ all work
78+
{{< /hextra/details >}}
79+
80+
### Initially closed
81+
82+
{{< hextra/details title="This one starts closed" closed="true" >}}
83+
You had to click to see this content!
84+
{{< /hextra/details >}}
85+
86+
---
87+
88+
## Steps
89+
90+
Numbered step lists rendered with CSS counters. Use heading levels (h3–h6) inside the shortcode body.
91+
92+
{{< hextra/steps >}}
93+
94+
### Clone the repository
95+
96+
```bash
97+
git clone https://github.com/layer5io/academy-example.git
98+
```
99+
100+
### Install dependencies
101+
102+
```bash
103+
npm install
104+
```
105+
106+
### Start the development server
107+
108+
```bash
109+
hugo server -D
110+
```
111+
112+
{{< /hextra/steps >}}
113+
114+
---
115+
116+
## Tabs
117+
118+
Tabbed interfaces powered by Bootstrap 5 nav-tabs. Each `hextra/tab` is nested inside a `hextra/tabs` container.
119+
120+
{{< hextra/tabs >}}
121+
{{< hextra/tab name="Go" >}}
122+
```go
123+
package main
124+
125+
import "fmt"
126+
127+
func main() {
128+
fmt.Println("Hello, World!")
129+
}
130+
```
131+
{{< /hextra/tab >}}
132+
{{< hextra/tab name="Python" >}}
133+
```python
134+
print("Hello, World!")
135+
```
136+
{{< /hextra/tab >}}
137+
{{< hextra/tab name="JavaScript" >}}
138+
```javascript
139+
console.log("Hello, World!");
140+
```
141+
{{< /hextra/tab >}}
142+
{{< /hextra/tabs >}}
143+
144+
### Pre-selected tab
145+
146+
The `selected` parameter sets the default tab.
147+
148+
{{< hextra/tabs >}}
149+
{{< hextra/tab name="macOS" >}}
150+
```bash
151+
brew install hugo
152+
```
153+
{{< /hextra/tab >}}
154+
{{< hextra/tab name="Linux" selected=true >}}
155+
```bash
156+
sudo apt install hugo
157+
```
158+
{{< /hextra/tab >}}
159+
{{< hextra/tab name="Windows" >}}
160+
```powershell
161+
choco install hugo-extended
162+
```
163+
{{< /hextra/tab >}}
164+
{{< /hextra/tabs >}}
165+
166+
---
167+
168+
## File Tree
169+
170+
An interactive file tree with expandable folders. Compose `hextra/filetree/container`, `hextra/filetree/folder`, and `hextra/filetree/file`.
171+
172+
{{< hextra/filetree/container >}}
173+
{{< hextra/filetree/folder name="content" >}}
174+
{{< hextra/filetree/folder name="docs" >}}
175+
{{< hextra/filetree/file name="_index.md" >}}
176+
{{< hextra/filetree/file name="getting-started.md" >}}
177+
{{< /hextra/filetree/folder >}}
178+
{{< hextra/filetree/folder name="blog" state="closed" >}}
179+
{{< hextra/filetree/file name="_index.md" >}}
180+
{{< hextra/filetree/file name="first-post.md" >}}
181+
{{< /hextra/filetree/folder >}}
182+
{{< /hextra/filetree/folder >}}
183+
{{< hextra/filetree/folder name="layouts" >}}
184+
{{< hextra/filetree/file name="baseof.html" >}}
185+
{{< hextra/filetree/file name="index.html" >}}
186+
{{< /hextra/filetree/folder >}}
187+
{{< hextra/filetree/file name="hugo.yaml" >}}
188+
{{< hextra/filetree/file name="package.json" >}}
189+
{{< /hextra/filetree/container >}}
190+
191+
---
192+
193+
## Badge
194+
195+
Inline badges with color variants.
196+
197+
### Positional form (gray, default)
198+
199+
{{< hextra/badge "Default" >}}
200+
201+
### Named parameters with colors
202+
203+
{{< hextra/badge content="Success" color="green" >}}
204+
{{< hextra/badge content="Info" color="blue" >}}
205+
{{< hextra/badge content="Warning" color="yellow" >}}
206+
{{< hextra/badge content="Error" color="red" >}}
207+
{{< hextra/badge content="Important" color="purple" >}}
208+
{{< hextra/badge content="Amber" color="amber" >}}
209+
210+
### Badge with link
211+
212+
{{< hextra/badge content="Visit Hugo" color="blue" link="https://gohugo.io" >}}
213+
214+
### Badge with icon
215+
216+
{{< hextra/badge content="Documentation" color="green" icon="document-text" >}}
217+
218+
---
219+
220+
## Icon
221+
222+
Renders an inline SVG icon from `data/hextra/icons.yaml`.
223+
224+
Here are a few icons inline: {{< hextra/icon "light-bulb" >}} light-bulb, {{< hextra/icon "information-circle" >}} information-circle, {{< hextra/icon "exclamation" >}} exclamation, {{< hextra/icon "folder" >}} folder, {{< hextra/icon "document-text" >}} document-text.
225+
226+
---
227+
228+
## PDF
229+
230+
Embeds a PDF file in an iframe. _(Requires a real PDF path.)_
231+
232+
Usage:
233+
234+
```text
235+
{{</* hextra/pdf "/path/to/sample.pdf" */>}}
236+
```
237+
238+
<p class="text-body-secondary"><em>Supply a valid PDF path in the shortcode above to test rendering.</em></p>
239+
240+
---
241+
242+
## Include
243+
244+
Includes the rendered content of another page inline. _(Requires a page path that exists in the content directory.)_
245+
246+
Usage:
247+
248+
```text
249+
{{%/* hextra/include "content-formatting-examples" */%}}
250+
```
251+
252+
<p class="text-body-secondary"><em>Replace the path with an existing content page to test the <code>hextra/include</code> shortcode.</em></p>
253+
254+
---
255+
256+
## Term
257+
258+
Wraps a glossary term in an `<abbr>` tooltip. Definitions are sourced from `data/<lang>/termbase.yaml`.
259+
260+
Usage:
261+
262+
```text
263+
{{</* hextra/term "API" */>}}
264+
```
265+
266+
To test, create `data/en/termbase.yaml`:
267+
268+
```yaml
269+
- abbr: API
270+
term: Application Programming Interface
271+
definition: A set of protocols for building software.
272+
```
273+
274+
<p class="text-body-secondary"><em>Create the termbase data file above, then use the shortcode in your content.</em></p>
275+
276+
---
277+
278+
## Jupyter
279+
280+
Renders a Jupyter Notebook (.ipynb) as code blocks and markdown cells.
281+
282+
Usage:
283+
284+
```text
285+
{{%/* hextra/jupyter "notebook.ipynb" */%}}
286+
```
287+
288+
<p class="text-body-secondary"><em>Place a <code>.ipynb</code> file in this page bundle and use the shortcode above to test.</em></p>
289+
290+
---
291+
292+
## Asciinema
293+
294+
Embeds an asciinema terminal recording player.
295+
296+
Usage:
297+
298+
```text
299+
{{</* hextra/asciinema file="demo.cast" */>}}
300+
```
301+
302+
<p class="text-body-secondary"><em>Place a <code>.cast</code> file in this page bundle and use the shortcode above to test.</em></p>
303+
304+
---
305+
306+
## Combined example
307+
308+
Below is a realistic example combining several shortcodes:
309+
310+
{{< hextra/callout type="info" >}}
311+
Follow the steps below to set up your development environment.
312+
{{< /hextra/callout >}}
313+
314+
{{< hextra/steps >}}
315+
316+
### Prerequisites
317+
318+
Make sure you have the following installed:
319+
320+
{{< hextra/cards cols="2" >}}
321+
{{< hextra/card title="Hugo Extended" subtitle="v0.146.0 or later" link="https://gohugo.io/installation/" icon="document-text" >}}
322+
{{< hextra/card title="Node.js" subtitle="LTS version recommended" link="https://nodejs.org/" icon="folder" >}}
323+
{{< /hextra/cards >}}
324+
325+
### Clone and install
326+
327+
{{< hextra/tabs >}}
328+
{{< hextra/tab name="HTTPS" >}}
329+
```bash
330+
git clone https://github.com/layer5io/academy-example.git
331+
cd academy-example && npm install
332+
```
333+
{{< /hextra/tab >}}
334+
{{< hextra/tab name="SSH" >}}
335+
```bash
336+
git clone git@github.com:layer5io/academy-example.git
337+
cd academy-example && npm install
338+
```
339+
{{< /hextra/tab >}}
340+
{{< /hextra/tabs >}}
341+
342+
### Verify the project structure
343+
344+
{{< hextra/filetree/container >}}
345+
{{< hextra/filetree/folder name="academy-example" >}}
346+
{{< hextra/filetree/folder name="content" >}}
347+
{{< hextra/filetree/file name="_index.md" >}}
348+
{{< /hextra/filetree/folder >}}
349+
{{< hextra/filetree/file name="hugo.yaml" >}}
350+
{{< hextra/filetree/file name="package.json" >}}
351+
{{< hextra/filetree/file name="go.mod" >}}
352+
{{< /hextra/filetree/folder >}}
353+
{{< /hextra/filetree/container >}}
354+
355+
### Start the server
356+
357+
```bash
358+
hugo server -D
359+
```
360+
361+
{{< hextra/callout type="warning" >}}
362+
The `-D` flag renders draft pages. Remove it for production builds.
363+
{{< /hextra/callout >}}
364+
365+
{{< /hextra/steps >}}
366+
367+
{{< hextra/badge content="Setup complete" color="green" icon="light-bulb" >}}

‎go.mod‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ module github.com/layer5io/academy-example
33
go 1.24.5
44

55
// Uncomment line below when testing changes to the academy theme
6-
// replace github.com/layer5io/academy-theme v0.1.9 => ../academy-theme
6+
replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme
77

88
replace github.com/FortAwesome/Font-Awesome v4.7.0+incompatible => github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3
99

0 commit comments

Comments
 (0)