Hextra

https://imfing.github.io/hextra/docs
Admin
Hextra is a modern, fast, and batteries-included Hugo theme built with Tailwind CSS for creating...
Tokens:35,822
Snippets:429
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Icon shortcode usage example

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/icon

Shows the basic usage of the icon shortcode with the icon name as a parameter. The example uses the `github` icon.

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

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

### Preview the site locally

Source: https://imfing.github.io/hextra/docs/getting-started

Starts the Hugo development server with draft and fast render options.

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

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

### Use asciinema shortcode with all parameters

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/asciinema

Advanced example using all available parameters: theme, speed, autoplay, loop, and markers. Markers use the format "time:label".

```markdown
{{</* asciinema 
  file="demo.cast"
  theme="dracula"
  speed="2"
  autoplay="true"
  loop="true"
  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
*/>}}
```

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

### Use Local KaTeX Assets

Source: https://imfing.github.io/hextra/docs/guide/latex

Load KaTeX CSS from local assets and publish additional font files. The example specifies a CSS file and font assets.

```yaml
params:
  math:
    engine: katex
    katex:
      css: "css/katex.min.css"
      assets:
        - "fonts/KaTeX_Main-Regular.woff2"
        # Add other font files here
```

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

### Synchronized tabs example

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/tabs

Two tab blocks with the same list of items (A and B) that will stay synchronized when sync 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 */>}}
```

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

### FileTree component example

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/filetree

Shows the shortcode structure for a file tree with a content folder, a docs subfolder, and a hugo.toml file. The docs folder is initially closed.

```text
{{< 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 >}}
```

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

### Chemistry Expression with mhchem

Source: https://imfing.github.io/hextra/docs/guide/latex

Use the mhchem extension (enabled by default) to render chemistry equations. The example shows a reaction sequence.

```markdown
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
```

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

### Cards Example with Images

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/cards

Shows a cards group with three image cards: an internet image, a local image from the static directory, and a local image from assets processed by Hugo with Resize method.

```markdown
{{< cards >}}
{{< card link="/" title="Image Card" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="Internet Image" >}}
{{< 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" >}}
{{< /cards >}}
```

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

### Badge with icon and link

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/others

Shows how to create badges with an icon, and optionally a link. The first example uses an icon 'sparkles', the second uses a link to GitHub releases and an icon 'github'.

```asciidoc
{{</* badge content="Badge" icon="sparkles" */>}}
{{</* badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
```

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

### Mermaid sequence diagram example

Source: https://imfing.github.io/hextra/docs/guide/diagrams

A Mermaid sequence diagram example that renders in Hextra. It defines participants Alice and Bob, includes a loop with a healthcheck, and uses notes and messages to illustrate the interaction.

```mermaid
```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!
```
```

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

### Cards Example with Icons and Tags

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/cards

Shows a basic cards group with three cards: one with a warning icon, one with a tag, and one without an icon. The cards link to the callout page or the root.

```markdown
{{< 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 >}}
```

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

### Badge default usage with code

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/others

Shortcode for creating a default badge with the content 'Badge'. The code example shows the syntax for using the badge shortcode.

```asciidoc
{{</* badge "Badge" */>}}
```

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

### Usage: Image Cards Shortcode

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/cards

Usage example for the cards shortcode with escaped braces. Shows how to create image cards with internet, local, and processed images, including custom alt text.

```markdown
{{</* 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 */>}}
```

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

### Multi-line LaTeX Environment (aligned)

Source: https://imfing.github.io/hextra/docs/guide/latex

Use a LaTeX environment like aligned inside $$ delimiters for multi-line expressions. The example shows Maxwell's equations.

```latex
$$
\begin{aligned}
  \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
  \nabla \cdot \mathbf{B} &= 0 \\
  \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
  \nabla \times \mathbf{B} &= \mu_0 \left( \mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \right)
\end{aligned}
$$
```

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

### Define extra sidebar links in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Configure extra links under `menu.sidebar` in the config file. The example includes a separator and two links.

```yaml
menu:
  sidebar:
    - name: More
      params:
        type: separator
      weight: 1
    - name: "About"
      pageRef: "/about"
      weight: 2
    - name: "Hugo Docs ↗"
      url: "https://gohugo.io/documentation/"
      weight: 3
```

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

### Usage: Basic Cards Shortcode

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/cards

Usage example for the cards shortcode with escaped braces. Shows how to create a basic cards group with icon, tag, and no icon variants.

```markdown
{{</* 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 */>}}
```

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

### Configure sidebar order with weight in front matter

Source: https://imfing.github.io/hextra/docs/guide/organize-files

Sets the sidebar order for the Guide section by assigning a weight of 2 in the front matter of content/docs/guide/_index.md. Lower weights appear earlier in the automatically generated sidebar.

```yaml
---
title: Guide
weight: 2
---
```

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

### Badge with colors and no border

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/others

Shows how to create badges with different colors and no border using the 'border=false' parameter. The code includes examples for each supported color.

```asciidoc
{{</* badge content="Badge" border=false */>}}
{{</* badge content="Badge" color="purple" border=false */>}}
{{</* badge content="Badge" color="indigo" border=false */>}}
{{</* badge content="Badge" color="blue" border=false */>}}
{{</* badge content="Badge" color="green" border=false */>}}
{{</* badge content="Badge" color="yellow" border=false */>}}
{{</* badge content="Badge" color="amber" border=false */>}}
{{</* badge content="Badge" color="orange" border=false */>}}
{{</* badge content="Badge" color="red" border=false */>}}
```

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

### Use Markdown inside tabs

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/tabs

Shows that Markdown syntax, including code blocks, is supported inside tabs. The example includes a JSON code block and a placeholder for other tabs.

```markdown
{{</* tabs */>}}

  {{</* tab name="JSON" */>}}
  ```json
  { "hello": "world" }
  ```
  {{</* /tab */>}}

  ... add other tabs similarly

{{</* /tabs */>}}
```

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

### Include remote notebook with jupyter shortcode using URL

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/jupyter

Includes a remote Jupyter Notebook by providing its URL. The example uses a raw GitHub URL for the 'What is the Jupyter Notebook' notebook.

```markdown
{{%/* jupyter "https://raw.githubusercontent.com/jupyter/notebook/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb" */%}}

```

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

### Set weights for blog series posts

Source: https://imfing.github.io/hextra/docs/guide/organize-files

Front matter for three posts in a blog series, each with a weight that determines their order. These weights are used in the example for reversePagination, where the default reversed ordering makes the next page post-a and the previous page post-c when reading post-b.

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

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

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

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

### Use asciinema shortcode with remote URLs

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/asciinema

Use the asciinema shortcode with remote URLs. The file parameter accepts any URL starting with http:// or https://.

```markdown
{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
{{</* asciinema file="https://example.com/demo.cast" */>}}
```

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

### Badge with colors

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/others

Shows how to create badges with different colors using the 'color' option. The code block lists examples for gray (default), purple, indigo, blue, green, yellow, amber, orange, and red.

```asciidoc
{{</* badge content="Badge" */>}}
{{</* badge content="Badge" color="purple" */>}}
{{</* badge content="Badge" color="indigo" */>}}
{{</* badge content="Badge" color="blue" */>}}
{{</* badge content="Badge" color="green" */>}}
{{</* badge content="Badge" color="yellow" */>}}
{{</* badge content="Badge" color="amber" */>}}
{{</* badge content="Badge" color="orange" */>}}
{{</* badge content="Badge" color="red" */>}}
```

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

### Override KaTeX CDN Base URL

Source: https://imfing.github.io/hextra/docs/guide/latex

Pin a specific version of KaTeX or use a custom CDN base URL in hugo.yaml. The example sets the base to a specific KaTeX version.

```yaml
params:
  math:
    engine: katex
    katex:
      base: "https://cdn.jsdelivr.net/npm/katex@0.16.22/dist"
```

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

### Custom CSS: Tailwind Theme Variables

Source: https://imfing.github.io/hextra/docs/advanced/customization

Starting with Hextra v0.10.0, you can override Tailwind theme variables inside the @layer theme block to customize the global look and feel. This example sets the default mono font family.

```css
@layer theme {
  :root {
    --hx-default-mono-font-family: "JetBrains Mono", monospace;
  }
}
```

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

### Initialize Git repository

Source: https://imfing.github.io/hextra/docs/getting-started

Switches to the site directory and initializes a new Git repository.

```shell
cd my-site
git init
```

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

### Create first content pages

Source: https://imfing.github.io/hextra/docs/getting-started

Creates the home page and documentation page content files.

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

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

### Details shortcode usage with title and closed attribute

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/details

Use the details shortcode to create collapsible content. The first example shows a default (open) details block with Markdown support. The second example uses the closed="true" attribute to hide the content by default.

```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 */>}}
```

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

### Initialize a new Hugo site

Source: https://imfing.github.io/hextra/docs/getting-started

Creates a new Hugo site with YAML configuration format.

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

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

### PDF shortcode with absolute URL

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/others

Shortcode to embed a PDF file from an external URL. The code example uses a sample URL.

```text
{{</* pdf "https://example.com/sample.pdf" */>}}
```

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

### Load frontend dependencies from local assets

Source: https://imfing.github.io/hextra/docs/guide/configuration

Place vendor files under assets/ and point config values to those asset paths. imageZoom.enable: true is needed because zoom is disabled by default. For KaTeX, publish all font files referenced by the CSS, not just the two shown.

```yaml
params:
  imageZoom:
    enable: true
    js: "js/vendor/medium-zoom.min.js"

  mermaid:
    js: "js/vendor/mermaid.min.js"

  asciinema:
    js: "js/vendor/asciinema-player.min.js"
    css: "css/vendor/asciinema-player.css"

  math:
    engine: katex
    katex:
      css: "css/vendor/katex.min.css"
      assets:
        - "fonts/KaTeX_Main-Regular.woff2"
        - "fonts/KaTeX_Math-Italic.woff2"

  search:
    type: flexsearch
    flexsearch:
      js: "js/vendor/flexsearch.bundle.min.js"

```

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

### Initialize Git submodules for CI/CD

Source: https://imfing.github.io/hextra/docs/getting-started

Ensures the theme submodule is populated before building the site. Required for CI/CD deployments.

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

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

### Display Math Expression with $$ Delimiters

Source: https://imfing.github.io/hextra/docs/guide/latex

Use $$ delimiters to render a LaTeX expression as a standalone block. The example shows a Fourier transform integral.

```markdown
$$F(\omega) = \int_{-\infty}^{\infty} f(t)\, e^{-j \omega t} \, dt$$
```

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

### Enable Umami Analytics in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Set `params.analytics.umami.serverURL` and `params.analytics.umami.websiteID` in `hugo.yaml`. Optional settings are commented out.

```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
```

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

### Inline Math Expression in Markdown

Source: https://imfing.github.io/hextra/docs/guide/latex

Wrap an inline LaTeX expression in \( and \) delimiters within a Markdown file. The example shows a sigma function rendered inline.

```markdown
This \(\sigma(z) = \frac{1}{1 + e^{-z}}\) is an inline expression.
```

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

### Configure Hextra theme via Hugo module

Source: https://imfing.github.io/hextra/docs/getting-started

Initializes the Hugo module and adds the Hextra theme as a dependency.

```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
```

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

### Use internal mirror URLs for frontend dependencies

Source: https://imfing.github.io/hextra/docs/guide/configuration

Set base to an internal mirror URL for each dependency. Optionally specify js/css when filenames differ. For MathJax customization, override layouts/_partials/scripts/mathjax.html.

```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"

  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"

```

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

### Deploy Hugo site to GitHub Pages with GitHub Actions

Source: https://imfing.github.io/hextra/docs/guide/deploy-site

GitHub Actions workflow for building and deploying a Hugo site to GitHub Pages. The first block is the full workflow from hextra-starter-template; the second is the modified build step for deploying to a user or organization page at https://<USERNAME>.github.io/. The workflow requires the Pages source to be set to GitHub Actions in repository settings.

```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
```

```yaml
run: |
  hugo \
    --gc --minify \
    --baseURL "https://${{ github.repository_owner }}.github.io/"
```

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

### Markdown code block with line numbers

Source: https://imfing.github.io/hextra/docs/guide/syntax-highlighting

Markdown source for a Python code block with line numbers enabled via `linenos=table` and starting at line 42 with `linenostart=42`.

```markdown
```python {linenos=table,linenostart=42}

def say_hello():
    print("Hello!")
```
```

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

### Add custom links to context menu

Source: https://imfing.github.io/hextra/docs/guide/configuration

Configure custom links with name, optional icon, and url. Placeholders {url}, {title}, and {markdown_url} are URL-encoded.

```yaml
params:
  page:
    contextMenu:
      enable: true
      links:
        - name: Open in ChatGPT
          icon: chatgpt
          url: "https://chatgpt.com/?hints=search&q=I%27m+looking+at+this+documentation%3A+{url}%0AHelp+me+understand+how+to+use+it."

```

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

### Use asciinema shortcode with assets directory

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/asciinema

Place the .cast file in the assets/ directory and reference it with the asciinema shortcode. This is the recommended method for local files.

```text
your-site/
├── assets/
│   └── demo.cast
└── content/
    └── my-page.md
```

```markdown
{{</* asciinema file="demo.cast" */>}}
```

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

### Use asciinema shortcode with static directory

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/asciinema

Place the .cast file in the static/ directory and reference it with the asciinema shortcode. This is an alternative to the assets directory method.

```text
your-site/
├── static/
│   └── demo.cast
└── content/
    └── my-page.md
```

```markdown
{{</* asciinema file="demo.cast" */>}}
```

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

### Use custom icon in shortcode and card

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/icon

Shows how to use a custom icon defined in `data/icons.yaml` with the `icon` shortcode and the `card` shortcode.

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

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

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

### Enable markdown output format for pages

Source: https://imfing.github.io/hextra/docs/guide/configuration

Add markdown to the page and section outputs to support the context menu's copy/raw Markdown features.

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

```

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

### Run production server to test analytics locally

Source: https://imfing.github.io/hextra/docs/guide/configuration

Hextra only supports analytics in production environments. Use this command to run a production server locally to test analytics.

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

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

### Include local notebook with jupyter shortcode in content/docs/my-page.md

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/jupyter

Adds a Jupyter Notebook from the assets folder to a page. Requires `math: true` in front matter for math rendering. The notebook file must be placed in the `assets` folder.

```markdown
---
title: My Page
math: true
---

{{%/* jupyter "notebook.ipynb" */%}}

```

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

### Markdown code block with highlighted lines

Source: https://imfing.github.io/hextra/docs/guide/syntax-highlighting

Markdown source for a Python code block with highlighted lines 2 and 4 using `hl_lines=[2,4]`, line numbers starting at 1, and the filename `hello.py`.

```markdown
```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}

def say_hello():
    print("Hello!")

def main():
    say_hello()
```
```

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

### Customize breadcrumb link title with linkTitle

Source: https://imfing.github.io/hextra/docs/guide/organize-files

Sets the breadcrumb link title to 'Foo Bar' for the page at content/docs/guide/organize-files.md. The breadcrumb will display 'Documentation > Guide > Foo Bar' instead of the default 'Organize Files'.

```yaml
---
linkTitle: Foo Bar
title: Organize Files
---
```

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

### Enable tab sync globally in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/tabs

Global configuration in `hugo.yaml` to enable tab synchronization across the site.

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

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

### Set footer copyright text in i18n/en.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Create a file named i18n/en.yaml and specify the copyright text. Markdown format is supported.

```yaml
copyright: "© 2024 YOUR TEXT HERE"
```

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

### Generate Chroma syntax highlighting styles

Source: https://imfing.github.io/hextra/docs/advanced/customization

Run this Hugo command to generate a stylesheet for a specific syntax highlighting theme.

```shell
hugo gen chromastyles --style=github
```

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

### Enable multi-language in hugo.yaml

Source: https://imfing.github.io/hextra/docs/advanced/multi-language

Add this to hugo.yaml to enable multi-language support. It sets the default content language to English and defines English, French, and Japanese with weights that control menu order. Note that starting with Hugo v0.158.0, languageName is deprecated; use label instead.

```yaml
defaultContentLanguage: en
languages:
  en:
    languageName: English
    weight: 1
  fr:
    languageName: Français
    weight: 2
  ja:
    languageName: 日本語
    weight: 3
```

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

### Enable GoatCounter Analytics in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Set `params.analytics.goatCounter.code` in `hugo.yaml`. Optional settings are commented out.

```yaml
params:
  analytics:
    goatCounter:
      code: "ABCDE"

      # Optional Settings
      #------------------
      # disables automatic collection of data
      # noOnload: true
      
      # disables event binding. See more here https://www.goatcounter.com/help/events
      # noEvents: true

      # allows data collection from local addresses. Use this with a production environment to test locally
      # allowLocal: true

      # Allow data collection when a page is loaded in a frame or iframe
      # allowFrame: true
```

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

### Pin Medium Zoom asset or load from local assets

Source: https://imfing.github.io/hextra/docs/guide/configuration

Configure imageZoom with a base URL for the Medium Zoom CDN, or optionally specify a local js path relative to the base or local assets.

```yaml
params:
  imageZoom:
    enable: true
    base: "https://cdn.jsdelivr.net/npm/medium-zoom@1.1.0/dist"
    # js: "js/medium-zoom.min.js" # optional, relative to the base or local assets

```

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

### Glossary page front matter (content/glossary/_index.en.md)

Source: https://imfing.github.io/hextra/docs/advanced/additional-pages

Creates the glossary index page for a language. The filename must include the language code suffix.

```markdown
---
title: Glossary
layout: glossary
---
```

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

### Display page tags in blog list and table of contents

Source: https://imfing.github.io/hextra/docs/guide/configuration

Enable tag display in blog list and table of contents by setting the respective flags.

```yaml
params:
  blog:
    list:
      displayTags: true
  toc:
    displayTags: true
```

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

### Configure theme mode and toggle in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Set the default theme mode (light, dark, or system) and enable the display toggle button. The default for theme.default is 'system'.

```yaml
params:
  theme:
    # light | dark | system
    default: system
    displayToggle: true
```

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

### Enable Matomo Analytics in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Set `params.analytics.matomo.URL` and `params.analytics.matomo.ID` in `hugo.yaml`.

```yaml
params:
  analytics:
    matomo:
      serverURL: "https://example.com"
      websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
```

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

### Enable tab sync per page in front matter

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/tabs

Per-page front matter configuration to enable tab synchronization for a specific page.

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

Example content.
```

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

### Use asciinema shortcode with page bundle

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/asciinema

For page bundles, place the .cast file alongside the markdown file and reference it with the asciinema shortcode.

```text
your-site/
└── content/
    └── my-page/
        ├── index.md
        └── demo.cast
```

```markdown
{{</* asciinema file="demo.cast" */>}}
```

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

### Enable page context menu globally

Source: https://imfing.github.io/hextra/docs/guide/configuration

Set params.page.contextMenu.enable to true to enable the context menu globally. You also need to enable the markdown output format for pages.

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

```

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

### Enable llms.txt output format in hugo.yaml

Source: https://imfing.github.io/hextra/docs/guide/configuration

Add the `llms` output format to your site's `hugo.yaml` to generate an `llms.txt` file at the site root.

```diff
outputs:
- home: [html]
+ home: [html, llms]
  page: [html]
  section: [html, rss]
```

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

### Basic table

Source: https://imfing.github.io/hextra/docs/guide/markdown

Markdown source for a simple table with two columns and two rows.

```markdown
| Name  | Age |
| :---- | :-- |
| Bob   | 27  |
| Alice | 23  |
```

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

### Add image from static directory in Markdown

Source: https://imfing.github.io/hextra/docs/guide/organize-files

Use this Markdown syntax to display an image stored in the static directory. The image path must begin with a slash and is relative to the static directory, making the image available to all pages.

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

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

### Switch to MathJax Engine

Source: https://imfing.github.io/hextra/docs/guide/latex

Use MathJax instead of KaTeX by setting the math engine to mathjax in hugo.yaml. Further customization is possible by overriding the mathjax template.

```yaml
params:
  math:
    engine: mathjax
```

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

### Configure hugo.yaml for Hextra theme

Source: https://imfing.github.io/hextra/docs/getting-started

Sets the Hextra theme in the Hugo configuration file.

```yaml
theme: hextra
```

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

### Configure hugo.yaml for Hextra module

Source: https://imfing.github.io/hextra/docs/getting-started

Adds the Hextra module import to the Hugo configuration file.

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

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

### Task list

Source: https://imfing.github.io/hextra/docs/guide/markdown

Markdown source for a task list with one checked and two unchecked items.

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

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

### hextra/hero-container shortcode usage

Source: https://imfing.github.io/hextra/docs/guide/shortcodes/hextra

Creates a hero container with an image on the left side, supporting many image and layout options.

```markdown
{{</* hextra/hero-container image="images/logo.svg"  imageTitle="title" */>}}
    Content
{{</* /hextra/hero-container */>}}
```

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

### Create archives page (content/archives/_index.md)

Source: https://imfing.github.io/hextra/docs/advanced/additional-pages

Creates the archive timeline page with the archives layout and disables the table of contents.

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

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

### Menu item with search type

Source: https://imfing.github.io/hextra/docs/guide/configuration

Menu item that renders a search bar by setting params.type to search.

```yaml
- name: Search
  params:
    type: search

```

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

### Add archives to top menu (hugo.yaml)

Source: https://imfing.github.io/hextra/docs/advanced/additional-pages

Optionally adds the archives page to the main menu.

```yaml
menu:
  main:
    - identifier: archives
      name: Archives
      pageRef: /archives
```

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

### Menu item with link and icon

Source: https://imfing.github.io/hextra/docs/guide/configuration

Menu item that shows a link with an icon by setting params.type to link and params.icon.

```yaml
- name: Blog
  params:
    type: link
    icon: rss

```
Tokens:
Raw