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.

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!

ଧମ୍ମପଥ – Advanced Topics

Multi-language

Enable Multi-language

Manage Translations by Filename

Translate Menu Items

Translate Strings

Read More

Comments System

giscus

Customizing Hextra

Custom CSS

Font Family

Inline Code Element

Primary Color

Further Theme Customization

General

Shortcodes

Badge

Card

Cards

Jupyter Notebook

PDF

Steps

Tabs

Filetree

Folder

Navbar

Footer

Search

Table of Contents

Sidebar

Language Switcher

Theme Toggle

Code Copy Button

Code Block

Feature Card

Feature Grid

Breadcrumbs

Syntax Highlighting

Custom Scripts

Custom Extra Section in Footer

Custom Layouts

Further Customization