### Start Development Server

Source: https://github.com/imfing/hextra/blob/main/CLAUDE.md

Use this command to start the development server. It includes theme reloading, which is recommended for active theme development.

```bash
# Start development server with theme reloading (recommended for theme development)
npm run dev:theme
```

--------------------------------

### Hero Container Shortcode Example

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/hextra/hero-container.html

Example demonstrating the basic usage of the hero-container shortcode with an image and link.

```html
{{< hextra/hero-container image="image.png" imageLink="https://example.com" imageTitle="Example Image" >}}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/imfing/hextra/blob/main/CLAUDE.md

Run this command first to install all necessary Node.js dependencies for the project, especially after a fresh clone or in a new worktree.

```bash
npm install
```

--------------------------------

### Steps Shortcode Usage Example

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/steps.md

A direct code example showing the syntax for the steps shortcode, including how to define steps using Markdown headings and how to exclude a subheading from the step count.

```go-html-template
{{%/* steps */%

### Step 1

This is the first step.

### Step 2

This is the second step.

#### Step subheading {class="no-step-marker"}

This will not be counted as a step.

{{%/* /steps */%
}}
```

--------------------------------

### Build Project Assets

Source: https://github.com/imfing/hextra/blob/main/AGENTS.md

Commands for building the example site or CSS assets.

```bash
# Build the example site
npm run build
```

```bash
# Build CSS assets only
npm run build:css
```

--------------------------------

### Example Jupyter Notebook with Prompts

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/jupyter.md

An example demonstrating the inclusion of a Jupyter Notebook with prompts enabled, typically used for showcasing interactive code execution.

```html
{{< jupyter src="example.ipynb" prompts=true >}}
```

--------------------------------

### Synchronized Tabs Example

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/tabs.md

Provides an example of two separate tab blocks that will be synchronized when the sync feature is enabled.

```markdown
{{< tabs >}}

  {{< tab name="A" >}}A content{{< /tab >}}
  {{< tab name="B" >}}B content{{< /tab >}}

{{< /tabs >}}

{{< tabs >}}

  {{< tab name="A" >}}Second A content{{< /tab >}}
  {{< tab name="B" >}}Second B content{{< /tab >}}

{{< /tabs >}}
```

--------------------------------

### Print to Standard Output

Source: https://github.com/imfing/hextra/blob/main/docs/assets/example-outputs.ipynb

Basic example of printing a string to standard output.

```python
print("Hello from stdout")
```

--------------------------------

### Using Custom Icons

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/icon.md

Examples of how to use your custom-defined icons with the icon shortcode and the card shortcode.

```html
{{</* icon "your-icon" */>}}
```

```html
{{</* card icon="your-icon" */>}}
```

--------------------------------

### Blog Post Front Matter Example

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/organize-files.md

Example front matter for a blog post, including title and weight. This structure is common for organizing posts within a series.

```yaml
---
title: Post A
weight: 1
---

```

```yaml
---
title: Post B
weight: 2
---

```

```yaml
---
title: Post C
weight: 3
---

```

--------------------------------

### Card Shortcode Example

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/card.html

Demonstrates the basic usage of the card shortcode with a link and title.

```html
{{< card link="/" title="Image Card" }}
```

--------------------------------

### Basic Gallery Usage

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/gallery.md

Use the `gallery` shortcode to wrap multiple `gallery-item` shortcodes. This example shows how to include both local and remote images.

```gohtml
{{</* gallery */>}}
  {{</* gallery-item src="images/space.jpg" caption="Space" */>}}
  {{</* gallery-item src="https://picsum.photos/id/1015/1600/1200" thumb="https://picsum.photos/id/1015/800/600" width="1600" height="1200" caption="River valley" */>}}
  {{</* gallery-item src="https://picsum.photos/id/1018/1600/1200" thumb="https://picsum.photos/id/1018/800/600" width="1600" height="1200" caption="Mountain lake" */>}}
{{</* /gallery */>}}
```

```gohtml
{{< gallery >}}
  {{< gallery-item src="images/space.jpg" caption="Space" >}}
  {{< gallery-item src="https://picsum.photos/id/1015/1600/1200" thumb="https://picsum.photos/id/1015/800/600" width="1600" height="1200" caption="River valley" >}}
  {{< gallery-item src="https://picsum.photos/id/1018/1600/1200" thumb="https://picsum.photos/id/1018/800/600" width="1600" height="1200" caption="Mountain lake" >}}
{{< /gallery >}}
```

--------------------------------

### Initialize New Hugo Site

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/getting-started.md

Creates a new Hugo site with YAML configuration. Ensure Hugo (extended version), Git, and Go are installed.

```shell
hugo new site my-site --format=yaml
```

--------------------------------

### FileTree Markdown Usage Example

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/filetree.md

This example shows how to use the FileTree shortcodes within a Markdown file, with comments indicating the structure.

```markdown
{{</* filetree/container */>}}
  {{</* filetree/folder name="content" */>}}
    {{</* filetree/file name="_index.md" */>}}
    {{</* filetree/folder name="docs" state="closed" */>}}
      {{</* filetree/file name="_index.md" */>}}
      {{</* filetree/file name="introduction.md" */>}}
      {{</* filetree/file name="introduction.fr.md" */>}}
    {{</* /filetree/folder */>}}
  {{</* /filetree/folder */>}}
  {{</* filetree/file name="hugo.toml" */>}}
{{</* /filetree/container */>}}
```

--------------------------------

### Preview Site Locally

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/getting-started.md

Starts the Hugo development server to preview the site. The site will be available at http://localhost:1313/.

```shell
hugo server --buildDrafts --disableFastRender
```

--------------------------------

### Badge Shortcode Examples

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/others.md

Demonstrates various ways to use the badge shortcode with different options like content, color, link, and icon.

```html
{{< badge "default" >}}&nbsp;
```

```html
{{< badge content="border" border=false >}}&nbsp;
```

```html
{{< badge content="color" color="green" >}}&nbsp;
```

```html
{{< badge content="link" link="https://github.com/imfing/hextra/releases" >}}&nbsp;
```

```html
{{< badge content="icon" icon="sparkles" >}}&nbsp;
```

--------------------------------

### Usage Example: Image Cards and Custom Alt Text

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/cards.md

Demonstrates the usage of image cards, including remote and local images, with options for Hugo's image processing and custom alt text for accessibility. The `/* */` syntax is used to prevent Hugo from processing these shortcodes within the example.

```html
{{</* cards */>}}
  {{</* card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" */>}}
  {{</* card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." */>}}
  {{</* card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" */>}}
  {{</* card link="/" title="Custom Alt Text" image="images/space.jpg" alt="A beautiful view of space with stars and galaxies" subtitle="Image with custom alt text for accessibility." */>}}
{{</* /cards */>}}
```

--------------------------------

### Usage Example: Basic Cards

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/cards.md

Illustrates the basic structure for creating cards with titles, links, and icons using the `cards` and `card` shortcodes. The `/* */` syntax is used to prevent Hugo from processing these shortcodes within the example.

```html
{{</* cards */>}}
  {{</* card link="../callout" title="Callout" icon="warning" */>}}
  {{</* card link="../callout" title="Card with tag" icon="tag" tag= "A custom tag" */>}}
  {{</* card link="/" title="No Icon" */>}}
{{</* /cards */>}}
```

--------------------------------

### Scrolled Output Example

Source: https://github.com/imfing/hextra/blob/main/docs/assets/example-outputs.ipynb

Generates a large amount of output lines to demonstrate scrolled output behavior.

```python
for i in range(20):
    print(f'line {i}')
```

--------------------------------

### Build Project Assets

Source: https://github.com/imfing/hextra/blob/main/CLAUDE.md

These commands are used for building the project. 'npm run build' builds the example site, while 'npm run build:css' specifically builds only the CSS assets.

```bash
# Build the example site
npm run build

# Build CSS assets only
npm run build:css
```

--------------------------------

### Remote Icon Pack Usage

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/icon.md

Examples of using icons from remote icon packs by specifying a provider prefix. Icons are fetched at build time.

```html
{{</* icon "lucide:house" */>}}
```

```html
{{</* icon "tabler:user" */>}}
```

```html
{{</* icon "simple:hugo" */>}}
```

--------------------------------

### Hugo Directory Structure Example

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/organize-files.md

Illustrates a typical Hugo content directory structure and the corresponding URL paths.

```tree
content
├── _index.md // <- /
├── docs
│   ├── _index.md // <- /docs/
│   ├── getting-started.md // <- /docs/getting-started/
│   └── guide
│       ├── _index.md // <- /docs/guide/
│       └── organize-files.md // <- /docs/guide/organize-files/
└── blog
    ├── _index.md // <- /blog/
    └── post-1.md // <- /blog/post-1/
```

--------------------------------

### Add Image from Static Directory

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/organize-files.md

Reference images placed in the 'static' directory using an absolute path starting with a slash.

```markdown
![](/images/image.png)
```

--------------------------------

### Render Hero Badge Shortcode

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/hextra/hero-badge.html

Use this shortcode to render a badge. It accepts 'link', 'class', and 'style' parameters. The 'link' parameter can be an external URL or a relative path. If the link starts with 'http', it's treated as external; otherwise, it's processed with `relURL` if it starts with '/'.

```html
{{< hextra/hero-badge >}}{{< /hextra/hero-badge >}}
```

--------------------------------

### Example Jupyter Notebook with Various Outputs

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/jupyter.md

Embed a Jupyter Notebook designed to demonstrate all supported output types, including errors, streams, and various data formats.

```html
{{< jupyter "example-outputs.ipynb" >}}
```

--------------------------------

### Data Visualization with Seaborn

Source: https://github.com/imfing/hextra/blob/main/docs/assets/example.ipynb

This code snippet demonstrates how to create a data visualization using the Seaborn library. Ensure Seaborn is installed and data is loaded correctly.

```python
# Import seaborn
import seaborn as sns

# Apply the default theme
sns.set_theme()

# Load an example dataset
tips = sns.load_dataset("tips")

# Create a visualization
sns.relplot(
    data=tips,
    x="total_bill", y="tip", col="time",
    hue="smoker", style="smoker", size="size",
)
```

```python
tips.head()
```

--------------------------------

### Add Hextra as Git Submodule

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/getting-started.md

Adds Hextra as a Git submodule to the themes directory and configures it in hugo.yaml. Requires Git to be installed.

```shell
cd my-site
git init
git submodule add https://github.com/imfing/hextra.git themes/hextra
```

```yaml
theme: hextra
```

--------------------------------

### Feature Card Shortcode Usage

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/hextra/feature-card.html

Example of how to use the feature card shortcode with basic parameters like title and subtitle. This shortcode is used to display a card highlighting a specific feature.

```html
{{< hextra/feature-card title="Feature Card" subtitle="This is a feature card." >}}
```

--------------------------------

### Get Hugo Language Locale (v0.158.0+)

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/utils/hugo-compat/language-locale.html

Retrieves the language locale using the `Language.Locale` property for Hugo versions 0.158.0 and above. This is the preferred method for newer Hugo installations.

```html
{{- /* Returns the language locale using the supported Hugo API for the running version. Hugo v0.158.0 deprecated Language.LanguageCode in favor of Language.Locale. Keep the fallback so Hextra can continue supporting Hugo >= 0.146.0. */ -}} {{- $language := . -}} {{- $locale := "" -}} {{- if ge (hugo.Version) "0.158.0" -}} {{- $locale = $language.Locale -}} {{- else -}} {{- $locale = $language.LanguageCode -}} {{- end -}} {{- return $locale -}}
```

--------------------------------

### Get Hugo Language Direction (Compatible)

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/utils/hugo-compat/language-direction.html

Use this partial to get the language direction, supporting Hugo versions prior to and after v0.158.0. It falls back to `Language.LanguageDirection` for older versions.

```html
{% comment %}
  Returns the language direction using the supported Hugo API for the running version. Hugo v0.158.0 deprecated Language.LanguageDirection in favor of Language.Direction. Keep the fallback so Hextra can continue supporting Hugo >= 0.146.0. {% endcomment %}
{%- $language := . -%}
{%- $direction := "" -%}
{%- if ge (hugo.Version) "0.158.0" -%}
  {%- $direction = $language.Direction -%}
{%- else -%}
  {%- $direction = $language.LanguageDirection -%}
{%- end -%}
{%- return $direction -%}
```

--------------------------------

### Basic Icon Usage

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/icon.md

Demonstrates how to use the icon shortcode with built-in icon names. Ensure inline shortcodes are enabled.

```html
{{< icon "academic-cap" >}}
```

```html
{{< icon "cake" >}}
```

```html
{{< icon "gift" >}}
```

```html
{{< icon "sparkles" >}}
```

--------------------------------

### Basic Steps Shortcode Usage

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/steps.md

Demonstrates the basic structure for using the steps shortcode with Markdown headings to define individual steps. Use `h3` for main steps and `h4` or lower for subheadings.

```markdown
{{% steps %

### Step 1

This is the first step.

### Step 2

This is the second step.

#### Step subheading {class="no-step-marker"}

This will not be counted as a step.

### Step 3

This is the third step.

{{% /steps %
}}
```

--------------------------------

### Enable Production Environment for Local Testing

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/configuration.md

Run a production server locally to test analytics.

```bash
hugo server --environment production
```

--------------------------------

### Print to Standard Error

Source: https://github.com/imfing/hextra/blob/main/docs/assets/example-outputs.ipynb

Example of printing a warning message to the standard error stream.

```python
import sys
print("Warning: something happened", file=sys.stderr)
```

--------------------------------

### Basic Cards with Icons and Tags

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/cards.md

Demonstrates how to create a set of cards with links, titles, icons, and custom tags. Ensure the 'icon' parameter uses valid icon names.

```html
{{< cards >}}
{{< card link="../callout" title="Callout" icon="warning" >}}
{{< card link="../callout" title="Card with tag" icon="tag" tag="custom tag">}}
{{< card link="/" title="No Icon" >}}
{{< /cards >}}
```

--------------------------------

### Mermaid Configuration and Initialization

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/scripts/mermaid.html

This script handles the loading and initialization of Mermaid.js. It supports loading from a CDN or local assets based on project configuration. It also sets up a MutationObserver to re-initialize Mermaid when the document's theme changes.

```html
{{- /* Mermaid */ -}} {{- $mermaidBase := "" -}} {{- $useDefaultCdn := true -}} {{- with site.Params.mermaid.base -}} {{- $mermaidBase = . -}} {{- $useDefaultCdn = false -}} {{- end -}} {{- $mermaidJsAsset := "" -}} {{- with site.Params.mermaid.js -}} {{- $mermaidJsAsset = . -}} {{- end -}} {{- /* If only js is set without base, use local asset loading */ -}} {{- if and $useDefaultCdn (ne $mermaidJsAsset "") -}} {{- $useDefaultCdn = false -}} {{- end -}} {{- /* Set default CDN base if needed */ -}} {{- if $useDefaultCdn -}} {{- $mermaidBase = "https://cdn.jsdelivr.net/npm/mermaid@latest/dist" -}} {{- end -}} {{- $isRemoteBase := or (strings.HasPrefix $mermaidBase "http://") (strings.HasPrefix $mermaidBase "https://") -}} {{- $minSuffix := cond hugo.IsProduction ".min" "" -}} {{- /* JS retrieval: get raw JS from either local asset or remote, then process */ -}} {{- if $isRemoteBase -}} {{- $jsPath := cond (ne $mermaidJsAsset "") $mermaidJsAsset (printf "mermaid%s.js" $minSuffix) -}} {{- $mermaidJsUrl := urls.JoinPath $mermaidBase $jsPath -}} {{- with try (resources.GetRemote $mermaidJsUrl) -}} {{- with .Err -}} {{- errorf "Could not retrieve Mermaid js file from %s. Reason: %s." $mermaidJsUrl . -}} {{- else with .Value -}} {{- with resources.Copy (printf "js/mermaid%s.js" $minSuffix) . -}} {{- $mermaidJs := . | fingerprint -}} {{- end -}} {{- end -}} {{- end -}} {{- else if $mermaidJsAsset -}} {{- with resources.Get $mermaidJsAsset -}} {{- $mermaidJs := . | fingerprint -}} {{- else -}} {{- errorf "Mermaid js asset not found at %q" $mermaidJsAsset -}} {{- end -}} {{- end -}}
```

```javascript
document.addEventListener("DOMContentLoaded", () => {
  // Store original mermaid code for each diagram
  document.querySelectorAll(".mermaid").forEach((el) => {
    el.dataset.original = el.innerHTML;
  });

  const theme = document.documentElement.classList.contains("dark") ? "dark" : "default";
  mermaid.initialize({
    startOnLoad: true,
    theme: theme
  });

  let timeout;
  new MutationObserver(() => {
    clearTimeout(timeout);
    timeout = setTimeout(() => {
      const theme = document.documentElement.classList.contains("dark") ? "dark" : "default";
      document.querySelectorAll(".mermaid").forEach((el) => {
        // Reset to original content, preserving HTML
        el.innerHTML = el.dataset.original;
        el.removeAttribute("data-processed");
      });
      mermaid.initialize({
        startOnLoad: true,
        theme: theme
      });
      mermaid.init();
    }, 150);
  }).observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["class"],
  });
});
```

--------------------------------

### Create Content Pages

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/getting-started.md

Generates the basic content files for the home page and documentation index.

```shell
hugo new content/_index.md
hugo new content/docs/_index.md
```

--------------------------------

### Blockquote with Attribution

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/markdown.md

Use blockquotes for cited text, including attribution. This example shows a blockquote with a citation and a footnote reference.

```markdown
> Don't communicate by sharing memory, share memory by communicating.<br>
> — <cite>Rob Pike[^1]</cite>

[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
```

--------------------------------

### GitHub Actions Workflow for Deploying Hugo Site

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/deploy-site.md

This workflow automates the building and deployment of a Hugo site to GitHub Pages. It checks out the repository, sets up Go and Hugo, builds the site, and uploads the artifact for deployment.

```yaml
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.147.7
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # fetch all history for .GitInfo and .Lastmod
          submodules: recursive
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Setup Hugo
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

```

--------------------------------

### Initialize PhotoSwipe Lightboxes

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/scripts/gallery.html

Initializes PhotoSwipe lightboxes for elements with the `data-pswp-gallery` attribute. It dynamically loads the PhotoSwipe core module and registers a custom UI element for captions, extracting them from figure elements or image alt text.

```javascript
import PhotoSwipeLightbox from {{ $lightboxUrl | jsonify | safeJS }};
const initLightboxes = () => {
  document.querySelectorAll("\\[data-pswp-gallery\\]").forEach((el) => {
    if (el.dataset.pswpInited === "1") return;
    const lightbox = new PhotoSwipeLightbox({
      gallery: "#" + el.id,
      children: "a\\[data-pswp-width\\]\\[data-pswp-height\\]",
      pswpModule: () => import({{ $coreUrl | jsonify | safeJS }}),
    });
    lightbox.on("uiRegister", () => {
      lightbox.pswp.ui.registerElement({
        name: "caption",
        order: 9,
        isButton: false,
        appendTo: "root",
        html: "",
        onInit: (captionEl, pswp) => {
          pswp.on("change", () => {
            const a = pswp.currSlide?.data?.element;
            const source = a?.closest("figure")?.querySelector(".hextra-gallery___caption");
            if (source && source.textContent.trim()) {
              captionEl.innerHTML = source.innerHTML;
              captionEl.style.display = "";
              return;
            }
            const text = a?.querySelector("img")?.getAttribute("alt") || "";
            captionEl.textContent = text;
            captionEl.style.display = text ? "" : "none";
          });
        },
      });
    });
    lightbox.init();
    el.dataset.pswpInited = "1";
  });
};
```

--------------------------------

### Tabs Shortcode Configuration for Syncing

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/tabs.md

Shows how to enable tab synchronization globally in `hugo.yaml` or per page in front matter.

```yaml
params:
  page:
    tabs:
      sync: true
```

```yaml
---
title: My page
params:
  tabs:
    sync: true
---

Example content.
```

--------------------------------

### Render a Flowchart with Mermaid

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/diagrams.md

Use a markdown code block with the 'mermaid' language to define a flowchart. This example shows a simple directed graph.

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

--------------------------------

### Archive Page Configuration

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/advanced/additional-pages.md

Set up the archive page by creating an `_index.md` file with the `archives` layout. This page will display posts grouped by year.

```yaml
---
title: Archives
layout: archives
toc: false
---
```

--------------------------------

### Customize Content Font Family

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/advanced/customization.md

Add custom CSS to `assets/css/custom.css` to change the font family of the content area. This example sets it to 'Times New Roman'.

```css
.content {
  font-family: "Times New Roman", Times, serif;
}
```

--------------------------------

### Configure Page Context Menu

Source: https://github.com/imfing/hextra/blob/main/docs/content/blog/v0.12.md

Enable the page context menu and add custom links with template variables for integrations like 'Ask AI'.

```yaml
params:
  page:
    contextMenu:
      enable: true
      links:
        - name: "Ask AI"
          url: "https://example.com?content={markdown_url}"
          icon: "sparkles"
```

--------------------------------

### Configure Archives Page Layout

Source: https://github.com/imfing/hextra/blob/main/docs/content/blog/v0.12.md

Set the `layout` to `archives` in the front matter of an index file to create a chronological blog post listing page.

```yaml
---
title: Archives
layout: archives
---

```

--------------------------------

### Include Shortcode Implementation

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/include.html

This is the implementation of the include shortcode. It checks for the presence of a positional parameter, attempts to retrieve the page, and renders its shortcodes. Errors are raised if the parameter is missing or the page is not found.

```gohtml
{{
- with .Get 0 }}
  {{- with site.GetPage . }}
    {{- .RenderShortcodes }}
  {{- else }}
    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
  {{- end }}
{{- else }}
  {{- errorf "The %q shortcode requires a positional parameter indicating the path of the file to include. See %s" .Name .Position }}
{{- end }}

```

--------------------------------

### Render a Sequence Diagram with Mermaid

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/diagrams.md

Embed Mermaid syntax within a 'mermaid' code block to create sequence diagrams. This example illustrates participant interactions and notes.

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

--------------------------------

### Add Custom Favicons

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/configuration.md

Override default favicons by placing icon files in the `static` folder. Include `favicon.svg` for basic setup and `favicon-dark.svg` for dark mode support.

```filetree
static/
  android-chrome-192x192.png
  android-chrome-512x512.png
  apple-touch-icon.png
  favicon-16x16.png
  favicon-32x32.png
  favicon-dark.svg
  favicon.ico
  favicon.svg
  site.webmanifest
```

--------------------------------

### Initialize Git Submodules for CI/CD

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/getting-started.md

Before running the Hugo build command in a CI/CD pipeline, execute this command to ensure theme files are present. Failure to do so will result in a build failure.

```shell
git submodule update --init
```

--------------------------------

### Create a Badge with Positional Parameter

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/badge.html

This demonstrates creating a badge using a positional parameter for the content. It's a shorthand for basic badge creation.

```html
{{< badge "Badge" >}}
```

--------------------------------

### Update Hugo Module to Hextra v0.10.0

Source: https://github.com/imfing/hextra/blob/main/docs/content/blog/v0.10.md

Run this command to update your Hugo module to the latest version of Hextra. Ensure Hugo v0.146.0+ is installed and review breaking changes before upgrading.

```bash
hugo mod get -u github.com/imfing/hextra@v0.10.0
```

--------------------------------

### Override Default Layouts

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/advanced/customization.md

Customize the theme's default layouts by creating files with the same name in your site's `layouts` directory. For example, override the `single.html` layout for docs by creating `layouts/docs/single.html`.

```html
layouts/docs/single.html
```

--------------------------------

### Go Code Block with Base URL and Filename

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/syntax-highlighting.md

Creates a Go code block with a filename and a base URL for linking.

```go
go 1.20
```

--------------------------------

### Get Hugo Sites with Version Compatibility

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/utils/hugo-compat/sites.html

Retrieves all sites using the supported Hugo API. It checks the Hugo version and falls back to `site.Sites` for versions older than 0.156.0 to maintain compatibility.

```html
{{/* Returns all sites using the supported Hugo API for the running version. Hugo v0.156.0 deprecated site.Sites / page.Sites in favor of hugo.Sites. Keep the fallback so Hextra can continue supporting Hugo >= 0.146.0. */}}
{{- $sites := slice -}}
{{- if ge (hugo.Version) "0.156.0" -}}
  {{- $sites = hugo.Sites -}}
{{- else -}}
  {{- $sites = site.Sites -}}
{{- end -}}
{{- return $sites -}}
```

--------------------------------

### Icon Shortcode Syntax

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/icon.md

The basic syntax for using the icon shortcode.

```html
{{</* icon "github" */>}}
```

--------------------------------

### Configure Archive Section

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/advanced/additional-pages.md

Specify the content section to be used for generating the archives. The default is `blog`.

```yaml
params:
  archives:
    section: blog
```

--------------------------------

### Get Hugo Language Label (Compatible)

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/utils/hugo-compat/language-label.html

Retrieves the language label using Hugo's supported API. Includes a fallback for older Hugo versions (>= 0.146.0) where `Language.Label` was not yet available.

```html
{{/\* Returns the language label using the supported Hugo API for the running version. Hugo v0.158.0 deprecated Language.LanguageName in favor of Language.Label. Keep the fallback so Hextra can continue supporting Hugo >= 0.146.0. *\/}}
{{- $language := . -}}
{{- $label := "" -}}
{{- if ge (hugo.Version) "0.158.0" -}}
  {{- $label = $language.Label -}}
{{- else -}}
  {{- $label = $language.LanguageName -}}
{{- end -}}
{{- return $label -}}
```

--------------------------------

### Get Language-Specific Page Link in Hugo

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/utils/lang-link.html

Use this partial to retrieve the relative permalink for a page in a specified language. If a direct translation is not found, it falls back to the homepage of that language, and finally to the site's root homepage.

```html
{{/* Get relative link of a page for given language */}}
{{/* If not found, return the homepage of the language page */}}
{{ $page := .context }}
{{ $lang := .lang }}
{{ $link := false }}
{{ range $page.AllTranslations }}
  {{ if eq .Language.Lang $lang }}
    {{ $link = .RelPermalink }}
  {{ end }}
{{ end }}
{{ if not $link }}
  {{ range where (partial "utils/hugo-compat/sites.html" .) ".Language.Lang" $lang }}
    {{ $link = .Home.RelPermalink }}
  {{ end }}
{{ end }}
{{ if not $link }}
  {{ $link = site.Home.RelPermalink }}
{{ end }}
{{ return $link }}
```

--------------------------------

### Render Jupyter Notebook with Source Path and Prompts

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/jupyter.html

Embeds a Jupyter Notebook and displays In/Out execution count prompts. Use named parameters for clarity.

```html
{{< jupyter src="notebook.ipynb" prompts=true >}}
```

--------------------------------

### Create a Basic Badge

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/badge.html

Use this shortcode to create a simple badge with specified content and color. It supports named parameters for customization.

```html
{{< badge content="Badge" color="blue" >}}
```

--------------------------------

### Generate Hugo Stats JSON

Source: https://github.com/imfing/hextra/blob/main/AGENTS.md

Run Hugo with the dev.toml config to enable build stats, which is necessary for Tailwind CSS to tree-shake unused styles. This command also starts a dev server that writes hugo_stats.json on every rebuild.

```bash
# Using npm (starts a dev server that writes hugo_stats.json on every rebuild):
npm run dev:theme
```

--------------------------------

### Task List

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/markdown.md

Create task lists using hyphens followed by square brackets. Checked items use '[x]' and unchecked items use '[ ]'.

```markdown
- [x] Write documentation
- [ ] Review code
- [ ] Deploy changes
```

--------------------------------

### Retrieve Page Title in Hugo

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/utils/title.html

This snippet defines logic to get a page's title. It prioritizes LinkTitle, then Title, and falls back to the file or directory name if neither is set. Use this when you need a dynamic title for pages or sections.

```html
{{/* This utility is used to retrieve the title of a page or section. If no title is set, it falls back to using the directory or file name. Based on https://github.com/thegeeklab/hugo-geekdoc/blob/v0.44.0/layouts/partials/utils/title.html */}}
{{- $title := "" -}}
{{ if .LinkTitle }}
  {{ $title = .LinkTitle }}
{{ else if .Title }}
  {{ $title = .Title }}
{{ else if and .IsSection .File }}
  {{ $title = path.Base .File.Dir | humanize | title }}
{{ else if and .IsPage .File }}
  {{ $title = .File.BaseFileName | humanize | title }}
{{ end }}
{{ return $title -}}
```

--------------------------------

### Configure Hextra Theme via Hugo Module

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/getting-started.md

Adds Hextra as a Hugo module and configures the theme in hugo.yaml. Requires Hugo modules to be initialized.

```shell
# initialize hugo module
cd my-site
hugo mod init github.com/username/my-site

# add Hextra theme
hugo mod get github.com/imfing/hextra
```

```yaml
module:
  imports:
    - path: github.com/imfing/hextra
```

--------------------------------

### Basic Details Shortcode

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/details.md

Use this shortcode to create a collapsible section with a title. Markdown content within the shortcode will be rendered.

```go
{{< details title="Details" >}}

This is the content of the details.

Markdown is **supported**.

{{< /details >}}
```

--------------------------------

### Render a File Tree Structure

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/filetree.md

Use this shortcode to render a visual file tree. It accepts nested folder and file shortcodes to define the structure.

```html
{{< filetree/container >}}
  {{< filetree/folder name="content" >}}
    {{< filetree/file name="_index.md" >}}
    {{< filetree/folder name="docs" state="closed" >}}
      {{< filetree/file name="_index.md" >}}
      {{< filetree/file name="introduction.md" >}}
      {{< filetree/file name="introduction.fr.md" >}}
    {{< /filetree/folder >}}
  {{< /filetree/folder >}}
  {{< filetree/file name="hugo.toml" >}}
{{< /filetree/container >}}
```

--------------------------------

### Basic Tabs Shortcode

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/tabs.md

Demonstrates the fundamental structure for creating a set of tabs with different content panels.

```html
{{< tabs >}}
  {{< tab name="JSON" >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}}
  {{< tab name="YAML" >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}}
  {{< tab name="TOML" >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}}
{{< /tabs >}}
```

--------------------------------

### Ordered List

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/markdown.md

Create an ordered list using numbers followed by periods.

```markdown
1. First item
2. Second item
3. Third item
```

--------------------------------

### Initially Closed Details Shortcode

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/details.md

Use this shortcode to create a collapsible section that is hidden by default. Set `closed="true"` to achieve this.

```go
{{< details title="Click me to reveal" closed="true" >}}

This will be hidden by default.

{{< /details >}}
```

--------------------------------

### Use Internal Mirror for Script Assets

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/configuration.md

Configure Hextra to load frontend dependencies from an internal mirror URL by setting the `base` parameter.

```yaml
params:
  imageZoom:
    base: "https://mirror.example.com/medium-zoom/dist"

  mermaid:
    base: "https://mirror.example.com/mermaid/dist"

  asciinema:
    base: "https://mirror.example.com/asciinema-player/dist/bundle"

  gallery:
    base: "https://mirror.example.com/photoswipe/dist"

  math:
    engine: katex
    katex:
      base: "https://mirror.example.com/katex/dist"

  search:
    flexsearch:
      base: "https://mirror.example.com/flexsearch/dist"
      # js: "flexsearch.bundle.min.js"
```

--------------------------------

### Configure Umami Analytics

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/configuration.md

Set the Umami server URL and website ID in hugo.yaml to enable Umami analytics. Optional parameters for script name, data host URL, auto-tracking, domains, tags, and exclusion rules can also be configured.

```yaml
params:
  analytics:
    umami:
      serverURL: "https://example.com"
      websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
      # scriptName: "script.js" # optional (default: script.js)
      # https://umami.is/docs/tracker-configuration#data-host-url
      # hostURL: "http://stats.example.org" # optional
      # https://umami.is/docs/tracker-configuration#data-auto-track
      # autoTrack: "false" # optional
      # https://umami.is/docs/tracker-configuration#data-tag
      # domains: "example.net,example.org" # optional
      # https://umami.is/docs/tracker-configuration#data-exclude-search
      # tag: "umami-eu" # optional
      # https://umami.is/docs/tracker-configuration#data-exclude-hash
      # excludeSearch: "true" # optional
      # https://umami.is/docs/tracker-configuration#data-do-not-track
      # excludeHash: "true" # optional
      # https://umami.is/docs/tracker-configuration#data-domains
      # doNotTrack: "true" # optional
```

--------------------------------

### Configure PhotoSwipe JavaScript URLs

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/scripts/gallery.html

Determines the URLs for PhotoSwipe's core and lightbox JavaScript modules. It prioritizes local assets but can fetch from a remote base URL if configured.

```html
{{- $lightboxUrl := "" -}}
{{- $coreUrl := "" -}}
{{- if $isRemoteBase -}}
  {{- $lightboxPath := cond (ne $galleryLightboxJsAsset "") $galleryLightboxJsAsset (printf "photoswipe-lightbox.esm%s.js" $minSuffix) -}}
  {{- $corePath := cond (ne $galleryCoreJsAsset "") $galleryCoreJsAsset (printf "photoswipe.esm%s.js" $minSuffix) -}}
  {{- $lightboxRemote := urls.JoinPath $galleryBase $lightboxPath -}}
  {{- with try (resources.GetRemote $lightboxRemote) -}}
    {{- with .Err -}}
      {{- errorf "Could not retrieve PhotoSwipe lightbox js from %s. Reason: %s." $lightboxRemote . -}}
    {{- else with .Value -}}
      {{- with resources.Copy (printf "js/photoswipe-lightbox.esm%s.js" $minSuffix) . -}}
        {{- $lightboxUrl = (. | fingerprint).RelPermalink -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
  {{- $coreRemote := urls.JoinPath $galleryBase $corePath -}}
  {{- with try (resources.GetRemote $coreRemote) -}}
    {{- with .Err -}}
      {{- errorf "Could not retrieve PhotoSwipe core js from %s. Reason: %s." $coreRemote . -}}
    {{- else with .Value -}}
      {{- with resources.Copy (printf "js/photoswipe.esm%s.js" $minSuffix) . -}}
        {{- $coreUrl = (. | fingerprint).RelPermalink -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
{{- else -}}
  {{- if $galleryLightboxJsAsset -}}
    {{- with resources.Get $galleryLightboxJsAsset -}}
      {{- $lightboxUrl = (. | fingerprint).RelPermalink -}}
    {{- else -}}
      {{- errorf "PhotoSwipe lightbox js asset not found at %q" $galleryLightboxJsAsset -}}
    {{- end -}}
  {{- end -}}
  {{- if $galleryCoreJsAsset -}}
    {{- with resources.Get $galleryCoreJsAsset -}}
      {{- $coreUrl = (. | fingerprint).RelPermalink -}}
    {{- else -}}
      {{- errorf "PhotoSwipe core js asset not found at %q" $galleryCoreJsAsset -}}
    {{- end -}}
  {{- end -}}
{{- end -}}
{{- if or (not $lightboxUrl) (not $coreUrl) -}}
  {{- errorf "PhotoSwipe JS configuration is incomplete. 
```

--------------------------------

### Main Navigation Menu Configuration

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/configuration.md

Define the main navigation menu items in the `menu.main` section. Each item can link to a page, an external URL, or be a special type like a search bar.

```yaml
menu:
  main:
    - name: Documentation
      pageRef: /docs
      weight: 1
    - name: Blog
      pageRef: /blog
      weight: 2
    - name: About
      pageRef: /about
      weight: 3
    - name: Search
      weight: 4
      params:
        type: search
    - name: GitHub
      weight: 5
      url: "https://github.com/imfing/hextra"
      params:
        icon: github
```

--------------------------------

### Render a Hero Button with Link and Text

Source: https://github.com/imfing/hextra/blob/main/layouts/_shortcodes/hextra/hero-button.html

Use this shortcode to create a button with specified text and a link. The link can be internal (relative URL) or external. The style parameter is available but not explicitly used in this snippet.

```html
{{- /* A shortcode for rendering a button with a link. @param {string} link The link of the button. @param {string} text The text of the button. @param {string} style The style of the button. @example {{< hextra/hero-button text="Get Started" link="docs" >}} */ -}}
{{- $link := .Get "link" -}}
{{- $text := .Get "text" -}}
{{- $style := .Get "style" -}}
{{- $external := hasPrefix $link "http" -}}
{{- $href := cond (hasPrefix $link "/") ($link | relURL) $link -}}
[{{- $text -}}]({{ $href }})
```

--------------------------------

### Initialize Medium Zoom with Theme Awareness

Source: https://github.com/imfing/hextra/blob/main/layouts/_partials/scripts/medium-zoom.html

Initializes Medium Zoom for elements with the 'data-zoomable' attribute. It dynamically sets the overlay background color based on the presence of the 'dark' class on the document element and observes changes to this class to update the overlay. Includes CSS for z-index management.

```javascript
document.addEventListener("DOMContentLoaded", () => {
  if (!window.mediumZoom) {
    return;
  }
  const getOverlay = () => {
    return document.documentElement.classList.contains("dark") ? "rgba(17, 17, 17, 0.98)" : "rgba(255, 255, 255, 0.98)";
  };
  const zoom = window.mediumZoom("\\[data-zoomable\\]", {
    background: getOverlay(),
  });
  const style = document.createElement("style");
  style.textContent = 
` .medium-zoom-overlay { z-index: 1000; } 
 .medium-zoom-image--opened { z-index: 1001; } 
`;
  document.head.appendChild(style);
  new MutationObserver(() => {
    zoom.update({
      background: getOverlay()
    });
  }).observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["class"],
  });
});
```

--------------------------------

### Markdown Usage of Details Shortcode

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/details.md

Demonstrates how to use the Details shortcode within Markdown files. Note the use of `/* */` to comment out the shortcode delimiters, preventing premature rendering.

```markdown
{{</* details title="Details" */>}}

This is the content of the details.

Markdown is **supported**.

{{</* /details */>}}
```

```markdown
{{</* details title="Click me to reveal" closed="true" */>}}

This will be hidden by default.

{{</* /details */>}}
```

--------------------------------

### Display Glossary Term

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/shortcodes/term.md

Use the 'term' shortcode to display a definition for a given glossary entry. If the term is not found, it will be rendered directly.

```gohtml
{{< term "static site generator" >}}
```

```gohtml
{{< term "SEO" >}}
```

--------------------------------

### Enable Page Context Menu

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/configuration.md

Globally enable the page context menu by setting `params.page.contextMenu.enable` to `true` and ensuring the `markdown` output format is enabled for pages.

```yaml
params:
  page:
    contextMenu:
      enable: true
```

```yaml
outputs:
  page: [html, markdown]
  section: [html, rss, markdown]
```

--------------------------------

### Display Markdown

Source: https://github.com/imfing/hextra/blob/main/docs/assets/example-outputs.ipynb

Renders Markdown formatted text using IPython.display.Markdown.

```python
from IPython.display import Markdown
Markdown('**Bold text** and `inline code` from display_data')
```

--------------------------------

### Add Image in Same Directory

Source: https://github.com/imfing/hextra/blob/main/docs/content/docs/guide/organize-files.md

Place image files in the same directory as the Markdown file for direct referencing.

```markdown
![](image.png)
```