Dhammapatha – Guide

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.

Shortcodes

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

Hugo Shortcodes are simple snippets inside your content files calling built-in or custom templates.

Hextra provides a collection of beautiful shortcodes to enhance your content.

Callout Cards Details FileTree Icon Steps Tabs

Additional shortcodes provided by Hugo and Hextra:

Jupyter Notebook

alpha

Others

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

Dhammapatha – Guide

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

Supported Functions

Chemistry

Diagrams

Mermaid

Shortcodes

Deploy Site

GitHub Pages

Cloudflare Pages

Netlify

Vercel