Documentation
Advanced
Customization

Customizing Hextra

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

Component Layout Variables

Hextra provides CSS variables to customize the width of pages, navbar, and footer:

assets/css/custom.css
:root {
  /* Page width - also configurable via hugo.yaml params.page.width */
  --hextra-max-page-width: 80rem; /* default: 80rem (normal), 90rem (wide), 100% (full) */

  /* Navbar width - also configurable via hugo.yaml params.navbar.width */
  --hextra-max-navbar-width: 90rem; /* independent navbar width */

  /* Footer width - also configurable via hugo.yaml params.footer.width */
  --hextra-max-footer-width: 80rem; /* independent footer width */
}

Tailwind Theme Variables

Starting with Hextra v0.10.0, which is built on Tailwind CSS v4, you can customize the theme by overriding CSS variables inside the @layer theme block.

This lets you customize the global look and feel without having to modify every individual class.

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

Check out Tailwind Theme Variables documentation for details.

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
  • hextra-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

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

Footer

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

Search

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

Optional nested classes used within the search UI:

  • hextra-search-title - The result title element
  • hextra-search-active - The active result anchor
  • hextra-search-no-result - The empty state element
  • hextra-search-prefix - The breadcrumb/prefix label for grouped results
  • hextra-search-excerpt - The result snippet text
  • hextra-search-match - The highlighted query span

Table of Contents

  • hextra-toc - The table of contents container

Sidebar

  • hextra-sidebar-container - The sidebar container
  • hextra-sidebar-active-item - The active item in the sidebar

Language Switcher

  • hextra-language-switcher - The language switcher button
  • hextra-language-options - The language options container

Theme Toggle

  • hextra-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
  • hextra-copy-icon - The copy icon element
  • hextra-success-icon - The success icon element

Code Block

  • hextra-code-block - The code block container
  • hextra-code-filename - The filename element for code blocks

Feature Card

  • hextra-feature-card - The feature card link element

Feature Grid

  • hextra-feature-grid - The feature grid container

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!

Last updated on
Comments