hextra shortcodes - #113
Conversation
Signed-off-by: Lee Calcote <lee.calcote@layer5.io>
There was a problem hiding this comment.
Pull request overview
Adds an (currently draft) content page showcasing Hextra shortcodes and updates local tooling/configuration to support rendering and development.
Changes:
- Enables Goldmark raw HTML rendering in
hugo.yamland suppresses the related warning log. - Updates
go.modto use a localreplaceforacademy-themeand bumps the referenced version. - Adds a draft “Hextra Shortcodes Examples” page plus a
.claudeHugo dev launch configuration.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| hugo.yaml | Enables Goldmark unsafe rendering (raw HTML) and suppresses the raw-HTML warning log. |
| go.mod | Switches academy-theme to a local filesystem replace (and updates version reference). |
| content/hextra-shortcodes-examples/index.md | New draft page exercising Hextra shortcodes (includes some raw HTML notes). |
| .claude/launch.json | Adds a Hugo dev launch configuration for local preview. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| // Uncomment line below when testing changes to the academy theme | ||
| // replace github.com/layer5io/academy-theme v0.1.9 => ../academy-theme | ||
| replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme |
There was a problem hiding this comment.
The replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme directive is now active, which will break builds for anyone who doesn’t have a sibling ../academy-theme directory (including CI and downstream users). If this is only for local theme development, keep it commented out or move it to a developer-only workflow (e.g., documented local instructions, a separate go.work, or an uncommitted override).
| replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme | |
| // replace github.com/layer5io/academy-theme v0.4.2 => ../academy-theme |
| ignoreLogs: ['warning-goldmark-raw-html'] | ||
|
|
||
| markup: | ||
| goldmark: | ||
| renderer: | ||
| unsafe: true |
There was a problem hiding this comment.
goldmark.renderer.unsafe: true enables rendering of raw HTML in Markdown (and ignoreLogs suppresses related warnings). This widens the XSS/content-injection surface if untrusted or externally-sourced Markdown ever enters the build. If the goal is only to support a few styled notes in the shortcode example page, prefer replacing those raw <p> blocks with Markdown/shortcodes or confine unsafe to a dev-only config (e.g., environment-specific config override) rather than enabling it globally.
| ignoreLogs: ['warning-goldmark-raw-html'] | |
| markup: | |
| goldmark: | |
| renderer: | |
| unsafe: true | |
| markup: | |
| goldmark: | |
| renderer: |
| 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. | ||
|
|
||
| {{< alert type="note" title="Test Page: Not for Production" >}} | ||
| 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. | ||
| {{< /alert >}} |
There was a problem hiding this comment.
The text says “All shortcodes are invoked with the hextra/ prefix”, but this page immediately uses the non-namespaced alert shortcode. Either adjust the wording to clarify that alert comes from the Academy theme (and Hextra shortcodes are namespaced), or switch the notice to a hextra/* equivalent to keep the claim accurate.
| ``` | ||
|
|
||
| <p class="text-body-secondary"><em>Supply a valid PDF path in the shortcode above to test rendering.</em></p> | ||
|
|
There was a problem hiding this comment.
This raw HTML block (<p class="text-body-secondary">…) requires enabling Goldmark unsafe rendering to display as intended. To avoid needing global markup.goldmark.renderer.unsafe: true, consider rewriting these notes in pure Markdown (italics/blockquote) or using an existing shortcode/component for secondary text styling.
| "runtimeExecutable": "/usr/local/bin/hugo", | ||
| "runtimeArgs": ["server", "-D", "--port", "1314"], | ||
| "port": 1314, | ||
| "env": { | ||
| "PATH": "/usr/local/go/bin:/usr/local/bin:/usr/bin:/bin" |
There was a problem hiding this comment.
This launch config hardcodes macOS/Homebrew-style paths (/usr/local/bin/hugo and a full PATH override). That makes the config non-portable (Linux, Windows, Apple Silicon/Homebrew in /opt/homebrew, etc.) and can also inadvertently hide the user’s existing PATH entries. Prefer using runtimeExecutable: "hugo" and omitting the env.PATH override (or appending to ${env:PATH}) so it works across environments.
| "runtimeExecutable": "/usr/local/bin/hugo", | |
| "runtimeArgs": ["server", "-D", "--port", "1314"], | |
| "port": 1314, | |
| "env": { | |
| "PATH": "/usr/local/go/bin:/usr/local/bin:/usr/bin:/bin" | |
| "runtimeExecutable": "hugo", | |
| "runtimeArgs": ["server", "-D", "--port", "1314"], | |
| "port": 1314, | |
| "env": { | |
| "PATH": "${env:PATH}:/usr/local/go/bin" |
New shortcakes from hextra