ଧମ୍ମପଥ – Introduction

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start from Template

You could quickly get started by using the above template repository.

We have provided a GitHub Actions workflow which can help automatically build and deploy your site to GitHub Pages, and host it for free. For more options, check out Deploy Site.

🌐 Demo ↗

Start as New Project

There are two main ways to add the Hextra theme to your Hugo project:

Hugo Modules (Recommended): The simplest and recommended method. Hugo modules let you pull in the theme directly from its online source. Theme is downloaded automatically and managed by Hugo.
Git Submodule: Alternatively, add Hextra as a Git Submodule. The theme is downloaded by Git and stored in your project’s themes folder.

Setup Hextra as Hugo module

Prerequisites

Before starting, you need to have the following software installed:

Steps

Initialize a new Hugo site

hugo new site my-site --format=yaml

Configure Hextra theme via module

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

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

Configure hugo.yaml to use Hextra theme by adding the following:

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

Create your first content pages

Create new content page for the home page and the documentation page:

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

Preview the site locally

hugo server --buildDrafts --disableFastRender

Voila, your new site preview is available at http://localhost:1313/.

How to update theme?

To update all Hugo modules in your project to their latest versions, run the following command:

hugo mod get -u

To update Hextra to the latest released version, run the following command:

hugo mod get -u github.com/imfing/hextra

See Hugo Modules for more details.

Setup Hextra as Git submodule

Prerequisites

Before starting, you need to have the following software installed:

Steps

Initialize a new Hugo site

hugo new site my-site --format=yaml

Add Hextra theme as a Git submodule

git submodule add https://github.com/imfing/hextra.git themes/hextra

Configure hugo.yaml to use Hextra theme by adding the following:

theme: hextra

Create your first content pages

Create new content page for the home page and the documentation page:

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

Preview the site locally

hugo server --buildDrafts --disableFastRender

Your new site preview is available at http://localhost:1313/.

When using CI/CD for Hugo website deployment, it’s essential to ensure that the following command is executed before running the hugo command.

git submodule update --init

Failure to run this command results in the theme folder not being populated with Hextra theme files, leading to a build failure.

How to update theme?

To update all submodules in your repository to their latest commits, run the following command:

git submodule update --remote

To update Hextra to the latest commit, run the following command:

git submodule update --remote themes/hextra

See Git submodules for more details.

Explore the following sections to start adding more contents:

Organize Files Configuration Markdown

Multi-language

Mon, 01 Jan 0001 00:00:00 +0000

Hextra supports creating site with multiple languages using Hugo’s multilingual mode.

Enable Multi-language

To make our site multi-language, we need to tell Hugo the supported languages. We need to add to the site configuration file:

hugo.yaml

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

Manage Translations by Filename

Hugo supports managing translations by filename. For example, if we have a file content/docs/_index.md in English, we can create a file content/docs/_index.fr.md for French translation.

- _index.md
- _index.fr.md
- _index.ja.md

Note: Hugo also supports Translation by content directory.

Translate Menu Items

To translate menu items in the navigation bar, we need to set the identifier field:

hugo.yaml

menu:
  main:
    - identifier: documentation
      name: Documentation
      pageRef: /docs
      weight: 1
    - identifier: blog
      name: Blog
      pageRef: /blog
      weight: 2

and translate them in the corresponding i18n file:

i18n/fr.yaml

documentation: Documentation
blog: Blog

Translate Strings

To translate strings on the other places, we need to add the translation to the corresponding i18n file:

i18n/fr.yaml

readMore: Lire la suite

A list of strings used in the theme can be found in the i18n/en.yaml file.

Organize Files

Mon, 01 Jan 0001 00:00:00 +0000

Directory Structure

By default, Hugo searches for Markdown files in the content directory, and the structure of the directory determines the final output structure of your website. Take this site as an example:

_index.md
- _index.md
- getting-started.md
- - _index.md
  - organize-files.md
- _index.md
- post-1.md

Each of the _index.md files is the index page for the corresponding section. The other Markdown files are regular pages.

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/

Layouts

Hextra offers three layouts for different content types:

Layout	Directory	Features
`docs`	`content/docs/`	Ideal for structured documentation, same as this section.
`blog`	`content/blog/`	For blog postings, with both listing and detailed article views.
`default`	All other directories	Single-page article view without sidebar.

To customize a section to mirror the behavior of a built-in layout, specify the desired type in the front matter of the section’s _index.md.

content/my-docs/_index.md

---
title: My Docs
cascade:
  type: docs
---

The above example configuration ensures that the content files inside content/my-docs/ will be treated as documentation (docs type) by default.

Sidebar Navigation

The sidebar navigation is generated automatically based on the content organization alphabetically. To manually configure the sidebar order, we can use the weight parameter in the front matter of the Markdown files.

content/docs/guide/_index.md

---
title: Guide
weight: 2
---

ℹ️

It is recommended to keep the sidebar not too deep. If you have a lot of content, consider splitting them into multiple sections.

Breadcrumb Navigation

Breadcrumbs are auto-generated based on the directory structure of /content.

For example, consider the file structure demonstrated above. Given that structure, the breadcrumbs atop the page at /docs/guide/organize-files/ would appear automatically as follows:

Documentation > Guide > Organize Files

Customizing Breadcrumb Link Titles

By default, each breadcrumb link is generated based on that page’s title parameter. You can customize this by specifying a linkTitle.

For example, if instead of Organize Files we wanted the breadcrumb to be Foo Bar:

content/docs/guide/organize-files.md

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

This would now generate the following breadcrumbs:

Documentation > Guide > Foo Bar

Hiding Breadcrumbs

You can hide breadcrumbs completely from a page by specifying breadcrumbs: false in its front matter:

content/docs/guide/organize-files.md

---
breadcrumbs: false
title: Organize Files
---

Configure Content Directory

By default, the root content/ directory is used by Hugo to build the site. If you need to use a different directory for content, for example docs/, this can be done by setting the contentDir parameter in the site configuration hugo.yaml.

Add Images

To add images, the easiest way is to put the image files in the same directory as the Markdown file. For example, add an image file image.png alongside the my-page.md file:

- my-page.md
- image.png

Then, we can use the following Markdown syntax to add the image to the content:

content/docs/my-page.md

![](image.png)

We can also utilize the page bundles feature of Hugo to organize the image files together with the Markdown file. To achieve that, turn the my-page.md file into a directory my-page and put the content into a file named index.md, and put the image files inside the my-page directory:

- - index.md
  - image.png

content/docs/my-page/index.md

![](image.png)

Alternatively, we can also put the image files in the static directory, which will make the images available for all pages:

- image.png

- my-page.md

Note that the image path begins with a slash / and is relative to the static directory:

content/docs/my-page.md

![](/images/image.png)

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Hugo reads its configuration from hugo.yaml in the root of your Hugo site. The config file is where you can configure all aspects of your site. Check out the config file for this site exampleSite/hugo.yaml on GitHub to get a comprehensive idea of available settings and best practices.

Navigation

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

There are different types of menu items:

Link to a page in the site with pageRef
```
- name: Documentation
  pageRef: /docs
```

Link to an external URL with url

- name: GitHub
  url: "https://github.com"

Search bar with type: search

- name: Search
  params:
    type: search

Icon

- name: GitHub
  params:
    icon: github

These menu items can be sorted by setting the weight parameter.

Logo and Title

To modify the default logo, edit hugo.yaml and add the path to your logo file under static directory. Optionally, you can change the link that users are redirected to when clicking on your logo, as well as set the width & height of the logo in pixels.

hugo.yaml

params:
  navbar:
    displayTitle: true
    displayLogo: true
    logo:
      path: images/logo.svg
      dark: images/logo-dark.svg
      link: /
      width: 40
      height: 20

Sidebar

Main Sidebar

For the main sidebar, it is automatically generated from the structure of the content directory. See the Organize Files page for more details.

To exclude a single page from the left sidebar, set the sidebar.exclude parameter in the front matter of the page:

content/docs/guide/configuration.md

---
title: Configuration
sidebar:
  exclude: true
---

Extra Links

Sidebar extra links are defined under the menu.sidebar section in the config file:

hugo.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

Right Sidebar

Table of contents is automatically generated from the headings in the content file. It can be disabled by setting toc: false in the front matter of the page.

content/docs/guide/configuration.md

---
title: Configuration
toc: false
---

Page Edit Link

To configure the page edit link, we can set the params.editURL.base parameter in the config file:

hugo.yaml

params:
  editURL:
    enable: true
    base: "https://github.com/your-username/your-repo/edit/main"

The edit links will be automatically generated for each page based on the provided url as root directory. If you want to set edit link for a specific page, you can set the editURL parameter in the front matter of the page:

content/docs/guide/configuration.md

---
title: Configuration
editURL: "https://example.com/edit/this/page"
---

Footer

Copyright

To modify the copyright text displayed in your website’s footer, you’ll need to create a file named i18n/en.yaml. In this file, specify your new copyright text as shown below:

i18n/en.yaml

copyright: "© 2024 YOUR TEXT HERE"

For your reference, an example i18n/en.yaml file can be found in the GitHub repository. Additionally, you could use Markdown format in the copyright text.

Others

Favicon

To customize the favicon for your site, place icon files under the static folder to override the default favicons from the theme:

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

Include favicon.ico, favicon.svg and favicon-dark.svg files in your project to ensure your site’s favicons display correctly.

While favicon.ico is generally for older browsers, favicon.svg and favicon-dark.svg are supported by modern browsers. Use tools like favicon.io or favycon to generate such icons.

Theme Configuration

Use the theme setting to configure the default theme mode and toggle button, allowing visitors to switch between light or dark mode.

hugo.yaml

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

Options for theme.default:

light - always use light mode
dark - always use dark mode
system - sync with the operating system setting (default)

The theme.displayToggle parameter allows you to display a toggle button for changing themes. When set to true, visitors can switch between light or dark mode, overriding the default setting.

Page Last Modification

The date of the page’s last modification can be displayed by enabling the params.displayUpdatedDate flag. To use Git commit date as the source, enable also the enableGitInfo flag.

To customize the date format, set the params.dateFormat parameter. Its layout matches Hugo’s time.Format.

hugo.yaml

# Parse Git commit
enableGitInfo: true

params:
  # Display the last modification date
  displayUpdatedDate: true
  dateFormat: "January 2, 2006"

Page Width

The width of the page can be customized by the params.page.width parameter in the config file:

hugo.yaml

params:
  page:
    # full (100%), wide (90rem), normal (1280px)
    width: wide

There are three available options: full, wide, and normal. By default, the page width is set to normal.

Similarly, the width of the navbar and footer can be customized by the params.navbar.width and params.footer.width parameters.

Search Index

Full-text search powered by FlexSearch is enabled by default. To customize the search index, set the params.search.flexsearch.index parameter in the config file:

hugo.yaml

params:
  # Search
  search:
    enable: true
    type: flexsearch

    flexsearch:
      # index page by: content | summary | heading | title
      index: content

Options for flexsearch.index:

content - full content of the page (default)
summary - summary of the page, see Hugo Content Summaries for more details
heading - level 1 and level 2 headings
title - only include the page title

To customize the search tokenize, set the params.search.flexsearch.tokenize parameter in the config file:

hugo.yaml

params:
    # ...
    flexsearch:
      # full | forward | reverse | strict 
      tokenize: forward

Options for flexsearch.tokenize:

strict - index whole words
forward - incrementally index words in forward direction
reverse - incrementally index words in both directions
full - index every possible combination

To exclude a page from the search index, set the excludeSearch: true in the front matter of the page:

content/docs/guide/configuration.md

---
title: Configuration
excludeSearch: true
---

Google Analytics

To enable Google Analytics, set services.googleAnalytics.ID flag in hugo.yaml:

hugo.yaml

services:
  googleAnalytics:
    ID: G-MEASUREMENT_ID

Markdown

Mon, 01 Jan 0001 00:00:00 +0000

Hugo supports Markdown syntax for formatting text, creating lists, and more. This page will show you some of the most common Markdown syntax examples.

Markdown Examples

Styling Text

Style	Syntax	Example	Output
Bold	`bold text`	`bold text`	bold text
Italic	`italicized text`	`italicized text`	italicized text
Strikethrough	`~~strikethrough text~~`	`~~strikethrough text~~`	~~strikethrough text~~
Subscript	`<sub></sub>`	`This is a <sub>subscript</sub> text`	This is a _subscript text
Superscript	`<sup></sup>`	`This is a <sup>superscript</sup> text`	This is a ^superscript text

Blockquotes

Blockquote with attribution

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

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.

Alerts

New in v0.9.0

Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. GitHub-style alerts are supported. Please make sure you are using the latest version of Hextra and Hugo v0.134.0 or later.

Note

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goal.

Warning

Urgent info that needs immediate user attention to avoid problems.

Caution

Advises about risks or negative outcomes of certain actions.

Markdown

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Tables

Tables aren’t part of the core Markdown spec, but Hugo supports them out-of-the-box.

Name	Age
Bob	27
Alice	23

Markdown

|   Name | Age  |
|--------|------|
|    Bob | 27   |
|  Alice | 23   |

Inline Markdown within tables

Italics	Bold	Code
italics	bold	`code`

Markdown

| Italics   | Bold     | Code   |
| --------  | -------- | ------ |
| *italics* | **bold** | `code` |

Code Blocks

Syntax Highlighting

Lists

Ordered List

First item
Second item
Third item

Markdown

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

Unordered List

List item
Another item
And another item

Markdown

* List item
* Another item
* And another item

Nested list

Fruit
- Apple
- Orange
- Banana
Dairy
- Milk
- Cheese

Markdown

* Fruit
  * Apple
  * Orange
  * Banana
* Dairy
  * Milk
  * Cheese

Images

Markdown

![landscape](https://picsum.photos/800/600)

With caption:

Unsplash Landscape

Markdown

![landscape](https://picsum.photos/800/600 "Unsplash Landscape")

For more advanced functionality, use Hugo’s built-in Figure shortcode.

Configuration

Hugo uses Goldmark for Markdown parsing. Markdown rendering can be configured in hugo.yaml under markup.goldmark. Below is the default configuration for Hextra:

hugo.yaml

markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    noClasses: false

For more configuration options, see Hugo documentation on Configure Markup.

Learning Resources

The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015. ↩︎

Syntax Highlighting

Mon, 01 Jan 0001 00:00:00 +0000

Hugo uses Chroma, a general purpose syntax highlighter in pure Go, for syntax highlighting. It is recommended to use backticks for code blocks in Markdown content. For example:

Markdown

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

will be rendered as:

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

Features

Filename

To add a filename or title to the code block, set attribute filename:

Markdown

```python {filename="hello.py"}
def say_hello():
    print("Hello!")
```

hello.py

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

Link to File

New in v0.9.2

You can use the base_url attribute to provide a base URL that will be combined with the file name to generate a link.

The file name can include a relative path if it specifies the file’s location within the base path.

Markdown

```go {base_url="https://github.com/imfing/hextra/blob/main/",filename="exampleSite/hugo.work"}
go 1.20
```

exampleSite/hugo.work

go 1.20

Line Numbers

To set line numbers, set attribute linenos to table and optionally set linenostart to the starting line number:

Markdown

```python {linenos=table,linenostart=42}
def say_hello():
    print("Hello!")
```

42
43

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

Highlighting Lines

To highlight lines, set attribute hl_lines to a list of line numbers:

Markdown

```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
def say_hello():
    print("Hello!")

def main():
    say_hello()
```

hello.py

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

def main():
    say_hello()

Copy Button

By default, copy button is enabled for code blocks. Its behavior can changed by modifying the site configuration file:

hugo.yaml

params:
  highlight:
    copy:
      enable: true
      # hover | always
      display: hover

Supported Languages

For a list of supported languages, please see the Chroma documentation.

LaTeX

Mon, 01 Jan 0001 00:00:00 +0000

$\KaTeX$ is used for rendering LaTeX math expressions. It can be enabled per page by setting math to true in the page front matter.

page.md

---
title: "My Page with LaTeX"
math: true
---

When enabled, the scripts, stylesheets and fonts from KaTeX will be included automatically in your site. You can start using LaTeX math expressions in your Markdown content.

Example

Both inline and separate paragraph LaTeX math expressions are supported in the Markdown content.

Inline

page.md

This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.

This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.

Separate Paragraph

page.md

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

will be rendered as:

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

Important

Please enable and configure the passthrough extension in the Hugo configuration file. It preserves raw content within the delimiters to avoid rendering issues for complex expressions.

hugo.yaml

markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
        enable: true

For example, using the aligned environment:

page.md

$$
\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}
$$

will be rendered as:

\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}

Supported Functions

For a list of supported functions, see KaTeX supported functions.

Chemistry

Chemistry expressions are supported via mhchem extension.

Inline: $\ce{H2O}$ is water.

Separate paragraph:

page.md

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

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

Diagrams

Mon, 01 Jan 0001 00:00:00 +0000

Currently, Hextra supports Mermaid for diagrams.

Mermaid

Mermaid is a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser. For example, Mermaid can render flow charts, sequence diagrams, pie charts and more.

Using Mermaid in Hextra is as simple as writing a code block with language set mermaid:

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

will be rendered as:

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

Sequence diagram:

  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!

For more information, please refer to Mermaid Documentation.

Callout Component

Mon, 01 Jan 0001 00:00:00 +0000

A built-in component to show important information to the reader.

Note

GitHub-style alerts are supported since v0.9.0. It leverages Markdown syntax to render the callout which ensures better portability and readability of the content.

Example

👾

A callout is a short piece of text intended to attract attention.

ℹ️

A callout is a short piece of text intended to attract attention.

⚠️

A callout is a short piece of text intended to attract attention.

🚫

A callout is a short piece of text intended to attract attention.

Usage

Default

🌐

Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more.

{{< callout emoji="🌐" >}}
  Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more.
{{< /callout >}}

Info

ℹ️

Please visit GitHub to see the latest releases.

{{< callout type="info" >}}
  Please visit GitHub to see the latest releases.
{{< /callout >}}

Warning

⚠️

This API will be deprecated in the next version.

{{< callout type="warning" >}}
  A **callout** is a short piece of text intended to attract attention.
{{< /callout >}}

Error

🚫

Something went wrong and it’s going to explode.

{{< callout type="error" >}}
  Something went wrong and it's going to explode.
{{< /callout >}}

Cards Component

Mon, 01 Jan 0001 00:00:00 +0000

Example

Callout Card with tag

custom tag

No Icon

Image Card

Internet Image

Local Image

Raw image under static directory.

Local Image

Image under assets directory, processed by Hugo.

Usage

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

{{< 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" >}}
{{< /cards >}}

Card Parameters

Parameter	Description
`link`	URL (internal or external).
`title`	Title heading for the card.
`subtitle`	Subtitle heading (supports Markdown).
`icon`	Name of the icon.
`tag`	Text in tag.
`tagColor`	Color of the tag: `gray` (default), `yellow`, `red` and `blue`.

Image Card

Additionally, the card supports adding image and processing through these parameters:

Parameter	Description
`image`	Specifies the image URL for the card.
`method`	Sets Hugo’s image processing method.
`options`	Configures Hugo’s image processing options.

Card supports three kinds of images:

Remote image: the full URL in the image parameter.
Static image: use the relative path in Hugo’s static/ directory.
Processed image: use the relative path in Hugo’s assets/ directory.

Hextra auto-detects if image processing is needed during build and applies the options parameter or default settings (Resize, 800x, Quality 80, WebP Format). It currently supports these method: Resize, Fit, Fill and Crop.

For more on Hugo’s built in image processing commands, methods, and options see their Image Processing Documentation.

Columns

You can specify the maximum number of columns for cards to span by passing the cols parameter to the cards shortcode. Note that columns will still be collapsed on smaller screens.

Top Card Bottom Card

Left Card Right Card

{{< cards cols="1" >}}
  {{< card link="/" title="Top Card" >}}
  {{< card link="/" title="Bottom Card" >}}
{{< /cards >}}

{{< cards cols="2" >}}
  {{< card link="/" title="Left Card" >}}
  {{< card link="/" title="Right Card" >}}
{{< /cards >}}

Comments System

Mon, 01 Jan 0001 00:00:00 +0000

Hextra supports adding comments system to your site. Currently giscus is supported.

giscus

giscus is a comments system powered by GitHub Discussions. It is free and open source.

To enable giscus, you need to add the following to the site configuration file:

hugo.yaml

params:
  comments:
    enable: false
    type: giscus

    giscus:
      repo: <repository>
      repoId: <repository ID>
      category: <category>
      categoryId: <category ID>

The giscus configurations can be constructed from the giscus.app website. More details can also be found there.

Comments can be enabled or disabled for a specific page in the page front matter:

content/docs/about.md

---
title: About
comments: true
---

Customizing Hextra

Mon, 01 Jan 0001 00:00:00 +0000

Hextra offers some default customization options in the hugo.yaml config file to configure the theme. This page describes the available options and how to customize the theme further.

Custom CSS

To add custom CSS, we need to create a file assets/css/custom.css in our site. Hextra will automatically load this file.

Font Family

The font family of the content can be customized using:

assets/css/custom.css

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

Inline Code Element

The color of text mixed with other text can customized with:

assets/css/custom.css

.content code:not(.code-block code) {
  color: #c97c2e;
}

Primary Color

The primary color of the theme can be customized by setting the --primary-hue, --primary-saturation and --primary-lightness variables:

assets/css/custom.css

:root {
  --primary-hue: 100deg;
  --primary-saturation: 90%;
  --primary-lightness: 50%;
}

Further Theme Customization

The theme can be further customized by overriding the default styles via the exposed css classes. An example for customizing the footer element:

assets/css/custom.css

.hextra-footer {
  /* Styles will be applied to the footer element */
}

.hextra-footer:is(html[class~="dark"] *) {
  /* Styles will be applied to the footer element in dark mode */
}

The following classes can be used to customize various parts of the theme.

General

hextra-scrollbar - The scrollbar element
content - Page content container

Shortcodes

Badge

hextra-badge - The badge element

Card

hextra-card - The card element
hextra-card-image - The card image element
hextra-card-icon - The card icon element
hextra-card-subtitle - The card subtitle element

Cards

hextra-cards - The cards grid container

Jupyter Notebook

hextra-jupyter-code-cell - The Jupyter code cell container
hextra-jupyter-code-cell-outputs-container - The Jupyter code cell outputs container
hextra-jupyter-code-cell-outputs - The Jupyter code cell output div element

PDF

hextra-pdf - The PDF container element

Steps

steps - The steps container

Tabs

hextra-tabs-panel - The tabs panel container
hextra-tabs-toggle - The tabs toggle button

Filetree

hextra-filetree - The filetree container

Folder

hextra-filetree-folder - The filetree folder container

Navbar

nav-container - The navbar container
nav-container-blur - The navbar container in blur element
hamburger-menu - The hamburger menu button

Footer

hextra-footer - The footer element
hextra-custom-footer - The custom footer section container

Search

search-wrapper - The search wrapper container
search-input - The search input element
search-results - The search results list container

hextra-toc - The table of contents container

Sidebar

mobile-menu-overlay - The overlay element for the mobile menu
sidebar-container - The sidebar container
sidebar-active-item - The active item in the sidebar

Language Switcher

language-switcher - The language switcher button
language-options - The language options container

Theme Toggle

theme-toggle - The theme toggle button

Code Copy Button

hextra-code-copy-btn-container - The code copy button container
hextra-code-copy-btn - The code copy button

Code Block

hextra-code-block - The code block container

Feature Card

hextra-feature-card - The feature card link element

Feature Grid

hextra-feature-grid - The feature grid container

Breadcrumbs

No specific class is available for breadcrumbs.

Syntax Highlighting

List of available syntax highlighting themes are available at Chroma Styles Gallery. The stylesheet can be generated using the command:

hugo gen chromastyles --style=github

To override the default syntax highlighting theme, we can add the generated styles to the custom CSS file.

Custom Scripts

You may add custom scripts to the end of the head for every page by adding the following file:

layouts/partials/custom/head-end.html

Custom Extra Section in Footer

You can add extra section in the footer by creating a file layouts/partials/custom/footer.html in your site.

layouts/partials/custom/footer.html

<!-- Your footer element here -->

The added section will be added before the copyright section in the footer. You can use HTML and Hugo template syntax to add your own content.

Hugo variables available in the footer section are: .switchesVisible and .displayCopyright.

Custom Layouts

The layouts of the theme can be overridden by creating a file with the same name in the layouts directory of your site. For example, to override the single.html layout for docs, create a file layouts/docs/single.html in your site.

For further information, refer to the Hugo Templates.

Further Customization

Didn’t find what you were looking for? Feel free to open a discussion or make a contribution to the theme!

Deploy Site

Mon, 01 Jan 0001 00:00:00 +0000

Hugo generates static websites, allowing for flexible hosting options. This page provides guides for deploying your Hextra site on various platforms.

GitHub Pages

GitHub Pages is the recommended way to deploy and host your website for free.

If you bootstrap the site using hextra-starter-template, it has provided GitHub Actions workflow out-of-the-box that helps automatically deploy to GitHub Pages.

GitHub Actions Configuration

Below is an example configuration from hextra-starter-template:

.github/workflows/pages.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.138.0
    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

In your repository settings, set the Pages > Build and deployment > Source to GitHub Actions:

By default, the above GitHub Actions workflow .github/workflows/pages.yaml assumes that the site is deploying to https://<USERNAME>.github.io/<REPO>/.

If you are deploying to https://<USERNAME>.github.io/ then modify the --baseURL:

.github/workflows/pages.yaml

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

If you are deploying to your own domain, please change the --baseURL value accordingly.

Cloudflare Pages

Put your site source code in a Git repository (e.g. GitHub)
Log in to the Cloudflare dashboard and select your account
In Account Home, select Workers & Pages > Create application > Pages > Connect to Git
Select the repository, and in the Set up builds and deployments section, provide the following information:

Configuration	Value
Production branch	`main`
Build command	`hugo --gc --minify`
Build directory	`public`

For more details, check out:

Netlify

Push your code to your Git repository (GitHub, GitLab, etc.)
Import the project to Netlify
If you are not using [hextra-starter-template][hextra-starter-template], configure the following manually:
- Configure the Build command to hugo --gc --minify
- Specify the Publish directory to public
- Add Environment variable HUGO_VERSION and set to 0.138.0, or alternatively, set it in netlify.toml file
Deploy!

Check Hugo on Netlify for more details.

Vercel

Push your code to your Git repository (GitHub, GitLab, etc.)
Go to Vercel Dashboard and import your Hugo project
Configure the project, select Hugo as Framework Preset
Override the Build Command and Install command:
1. Set Build Command to hugo --gc --minify
2. Set Install Command to yum install golang

Details

Mon, 01 Jan 0001 00:00:00 +0000

A built-in component to display a collapsible content.

Example

Details

This is the content of the details.

Markdown is supported.

Click me to reveal

This will be hidden by default.

Usage

{{% details title="Details" %}}

This is the content of the details.

Markdown is **supported**.

{{% /details %}}

{{% details title="Click me to reveal" closed="true" %}}

This will be hidden by default.

{{% /details %}}

FileTree Component

Mon, 01 Jan 0001 00:00:00 +0000

Example

_index.md
- _index.md
- introduction.md
- introduction.fr.md

hugo.toml

Usage

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

Icon

Mon, 01 Jan 0001 00:00:00 +0000

To use this shortcode inline, inline shortcode needs to be enabled in the config:

hugo.yaml

enableInlineShortcodes: true

List of available icons can be found in data/icons.yaml.

Example

Usage

{{< icon "github" >}}

Heroicons v1 outline icons are available out of the box.

How to add your own icons

Create data/icons.yaml file, then add your own SVG icons in the following format:

data/icons.yaml

your-icon: <svg>your icon svg content</svg>

It then can be used in the shortcode like this:

{{< icon "your-icon" >}}

{{< card icon="your-icon" >}}

Tip: Iconify Design is a great place to find SVG icons for your site.

Jupyter Notebook Component

Mon, 01 Jan 0001 00:00:00 +0000

Experimental feature to include Jupyter Notebooks via a shortcode. Note that not all cell types are supported.

Jupyter Notebook is a language-agnostic HTML notebook application for Project Jupyter. It allows you to create and share documents that contain live code, equations, visualizations, and narrative text.

How to use

Using a local notebook

To use the Jupyter Notebook shortcode, you need to have a Jupyter Notebook file in your project. Similar to how you would add images to the project, you can add Jupyter Notebooks to the assets folder.

notebook.ipynb

- my-page.md

Include the Jupyter Notebook in the page using the jupyter shortcode:

content/docs/my-page.md

---
title: My Page
math: true
---

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

Alternatively, you can utilize the page bundles feature of Hugo to organize the Jupyter Notebooks together with the Markdown file.

- - index.md
  - notebook.ipynb

content/docs/my-page/index.md

---
title: My Page
math: true
---

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

Using a remote notebook

You can also use a remote notebook by providing the URL to the notebook file. For example, to include What is the Jupyter Notebook notebook in the page, you can use the following shortcode:

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

Example Notebook

ℹ️

The following is an example of a notebook file that is included in the project assets folder.

What is the Jupyter Notebook?

The Jupyter Notebook is an interactive computing environment that enables users to author notebook documents that include:

Live code
Interactive widgets
Plots
Narrative text
Equations
Images
Video

These documents provide a complete and self-contained record of a computation that can be converted to various formats and shared with others using email, version control systems (like Git/GitHub) or nbviewer.jupyter.org.

Data Visualization

Below is an example of a simple data visualization using the Seaborn library.

# 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",
)

Matplotlib is building the font cache; this may take a moment.

<seaborn.axisgrid.FacetGrid at 0x12830caa0>

tips.head()

   total_bill   tip     sex smoker  day    time  size
0       16.99  1.01  Female     No  Sun  Dinner     2
1       10.34  1.66    Male     No  Sun  Dinner     3
2       21.01  3.50    Male     No  Sun  Dinner     3
3       23.68  3.31    Male     No  Sun  Dinner     2
4       24.59  3.61  Female     No  Sun  Dinner     4

	total_bill	tip	sex	smoker	day	time	size
0	16.99	1.01	Female	No	Sun	Dinner	2
1	10.34	1.66	Male	No	Sun	Dinner	3
2	21.01	3.50	Male	No	Sun	Dinner	3
3	23.68	3.31	Male	No	Sun	Dinner	2
4	24.59	3.61	Female	No	Sun	Dinner	4

Equations

The following is an example of a simple equation using LaTeX.

E = mc^2

Other Shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

ℹ️

Some of these are Hugo built-in shortcodes. These shortcodes are considered less stable and may be changed anytime.

Badge

{{< badge "Badge" >}}

Result:

Badge

Variants:

{{< badge content="info" type="info" >}}
{{< badge content="warning" type="warning" >}}
{{< badge content="error" type="error" >}}

Result:

info

warning

error

With link and icon:

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

Result:

Releases

YouTube

Embed a YouTube video.

{{< youtube VIDEO_ID >}}

Result:

For more information, see Hugo’s YouTube Shortcode.

PDF

With PDF shortcode, you can embed a PDF file in your content.

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

You can also place the PDF file in your project directory and use the relative path.

{{< pdf "path/to/file.pdf" >}}

Example:

Steps

Mon, 01 Jan 0001 00:00:00 +0000

A built-in component to display a series of steps.

Example

Step 1

This is the first step.

Step 2

This is the second step.

Step 3

This is the third step.

Usage

ℹ️

Please note that this shortcode is intended only for Markdown content. If you put HTML content or other shortcodes as step content, it may not render as expected.

Put Markdown h3 header within steps shortcode.

{{% steps %}}

### Step 1

This is the first step.

### Step 2

This is the second step.

{{% /steps %}}

Tabs

Mon, 01 Jan 0001 00:00:00 +0000

Example

JSON: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.

YAML: YAML is a human-readable data serialization language.

TOML: TOML aims to be a minimal configuration file format that’s easy to read due to obvious semantics.

Usage

Default

{{< tabs items="JSON,YAML,TOML" >}}

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

{{< /tabs >}}

Specify Selected Index

Use defaultIndex property to specify the selected tab. The index starts from 0.

{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}}

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

{{< /tabs >}}

The YAML tab will be selected by default.

JSON: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.

YAML: YAML is a human-readable data serialization language.

TOML: TOML aims to be a minimal configuration file format that’s easy to read due to obvious semantics.

Use Markdown

Markdown syntax including code block is also supported:

{{< tabs items="JSON,YAML,TOML" >}}

  {{< tab >}}
  ```json
  { "hello": "world" }
  ```
  {{< /tab >}}

  ... add other tabs similarly

{{< /tabs >}}

{ "hello": "world" }

hello: world

hello = "world"

ଧମ୍ମପଥ – Introduction

Getting Started

Quick Start from Template

Start as New Project

Setup Hextra as Hugo module

Prerequisites

Steps

Initialize a new Hugo site

Configure Hextra theme via module

Create your first content pages

Preview the site locally

Setup Hextra as Git submodule

Prerequisites

Steps

Initialize a new Hugo site

Add Hextra theme as a Git submodule

Create your first content pages

Preview the site locally

Next

Multi-language

Enable Multi-language

Manage Translations by Filename

Translate Menu Items

Translate Strings

Read More

Organize Files

Directory Structure

Layouts

Sidebar Navigation

Breadcrumb Navigation

Customizing Breadcrumb Link Titles

Hiding Breadcrumbs

Configure Content Directory

Add Images

Configuration

Navigation

Menu

Logo and Title

Sidebar

Main Sidebar

Extra Links

Right Sidebar

Table of Contents

Page Edit Link

Footer

Copyright

Others

Favicon

Theme Configuration

Page Last Modification

Page Width

Search Index

Google Analytics

Markdown

Markdown Examples

Styling Text

Blockquotes

Alerts

Tables

Inline Markdown within tables

Code Blocks

Lists

Ordered List

Unordered List

Nested list

Images

Configuration

Learning Resources

Syntax Highlighting

Features

Filename

Link to File

Line Numbers

Highlighting Lines

Copy Button

Supported Languages

LaTeX

Example

Inline

Separate Paragraph