Docs

Configuration

Options to customize Axiom, starting from the top of the Config file (config.toml).

If you started with the Quick Start step, the Config file will be located at /axiom-example/config.toml. Open this file now and change/add/remove options as we work down the list of options.

Paths

When entering paths in the Config file or in Content files, the most portable and robust option is to use a relative path:

  • Don't use a beginning forward slash: NO:/images/example.png, YES:images/example.png
  • Local file paths are relative to the publishDir Config option (default: public)
  • CDN file paths are relative to the params.cdn.provider constructed URL
  • Local file URLs will be output as absolute or root-relative based on the canonifyURLs Config setting
  • When using Leaf Page Bundles, resource paths should be relative to the bundle, i.e., my-post/feature.png or my-post/data-table.md
  • CDN file URLs are always absolute

Examples of where relative paths are recommended:

  • In the params.logo Config section
  • In the params.images Config section
  • In a Page or Post's Frontmatter when setting the Feature image
  • In a Page or Post's Content when linking to a PDF, or using the Figure shortcode to display an image
  • When using Leaf Page Bundles or any other structure where resources are not on a CDN
  • Anywhere else an asset path is entered, excepting links to third-party websites/assets

If you use a different Permalink structure than Axiom's default, you'll need to adjust your Paths in Content to match that, i.e., posts/my-post/, or blog/my-post-2020-01-01, etc.

Core

Options related to Hugo's Core build settings:

# Change to your website's URL (NO trailing slash)
# For local dev, change to: http://localhost:1313
baseURL = "https://example.com"

# Change to your Brand or Website Title
title = "Axiom A Hugo Theme"
# Language codes (lowercase)
languageCode = "en-us"
defaultContentLanguage = "en"

# Which theme to use
theme = "axiom"

# Pagination (increase number for production)
paginate = 2
# Canonify relative URLs using baseURL
canonifyURLs = false
# Length of snippet on post index and structured data
summaryLength = 40
# Max posts to show in atom feed
rssLimit = 100
# Enable Emoji's in posts
enableEmoji = true
# Output a robots.txt file (see the 'Frontmatter' Docs page)
enableRobotsTXT = true
# Don't automatically mangle titles
pluralizelisttitles = false

If you change the defaultContentLanguage you must add the new language in the Config [languages] table, and an i18n language file in /i18n/lang-code.toml.

There are many more Core options that can be added to suit your needs. See the Hugo Configuration Documentation for more information.

Axiom is configured to use the file name slug as the publicly accessible URL:

[permalinks]
posts = "/:filename"

The post variable name refers to individual files in the post content Section.

Params

Options related to Hugo's Param settings:

[params]
# Sections to include in lists and indexes
mainSections = ["posts"]
# Footer copyright start year, prepended to current year, e.g., 2000-2020
copyrightYear = 2019
# Posts Date format
# Go Reference time: Mon Jan 2 15:04:05 MST 2006
dateFormat = "Jan 2, 2006 3:04PM"
# Chroma Syntax Highlighting
# Options: dark, light, false
highlight = "dark"
disableThemeAttribution = false

# Max Width Page sections
maxWidthTitle = "max-w-2xl"
maxWidthFeature = "max-w-5xl"
maxWidthContent = "max-w-2xl"

# Max Width Template parts
maxWidthHeader = "max-w-6xl"
maxWidthFooter = "max-w-6xl"

Max widths are optional and don't need to be set in your Config file unless you want to override the default values. Max widths can also be set in individual Page's Frontmatter. The value for the max width param must be a valid CSS class name that is defined in Tailwind CSS or in Custom CSS.

To enable Axiom's Syntax Highlighting color schemes to take effect, you will need to enable Markup Highlight Classes:

[markup]
[markup.highlight]
codeFences = true
noClasses = false

# Optional line numbers:
# lineNos = true
# lineNumbersInTable = false

Note about [markup.highlight] -> codeFences. The Hugo default for this is true. Hugo code fence style syntax highlighting will NOT work if it's set to false. This config variable doesn't need to be in your Config file unless you want to turn OFF Hugo syntax highlighting completely.

Axiom does not support line numbers in a table. If line numbers is on, make sure lineNumbersInTable = false.

There are many more Param options that can be added to suit your needs. See the Hugo Configuration Documentation for more information.

Branding

Config options related to your brand or website:

[params.brand]
# Just domain name, no www
domain = "example.com"
# Contact email address
email = "info@example.com"

Mainly used for Contact options.

Social

Settings relating to social networks:

[params.social]
# Replace USERNAME with your own
facebook = "https://www.facebook.com/USERNAME"
github = "https://github.com/USERNAME"
instagram = "https://instagram.com/USERNAME"
linkedin = "https://www.linkedin.com/in/USERNAME"
pinterest = "https://www.pinterest.com/USERNAME"
stackoverflow = "https://stackoverflow.com/users/USERNAME"
twitter = "https://twitter.com/USERNAME"
youtube = "https://www.youtube.com/USERNAME"

# Show these linked icons in the footer
footer = ["twitter", "github", "instagram"]

The footer option allows you to show specific social network icons with links in the footer of the website. Each entry must match one of the network names defined.

Services

Options for third party services, such as analytics, tracking, ads, and APIs:

[params.services]
# Google Analytics Property Id
googleAnalyticsId = ""
# Google Tag Manager Container Id
googleTagManagerId = ""
# Google Ads Id (provided when you setup a Conversion)
googleAdsId = ""
# Google Adsense Publisher Id
googleAdsenseId = ""
# Google Adsense Ad Slot Id (for ad unit shown below Posts)
googleAdsenseAdSlotId = ""
# Google Adsense Load Style
# Options: async, defer, lazy. Default: async
googleAdsenseLoad = ""
# Google Ads Conversion Id
googleAdsConversionId = ""
# Google Ads Conversion value (integer, no quotes, 00.00)
googleAdsConversionValue = 0
# Facebook App Id
facebookApp = "FB-DEV"
# Facebook Pixel Id
facebookPixel = "FB-DEV"
# Disqus Comments
disqusShortname = ""

Google Tag Manager (GTM): If you're using GTM and have a Google Analytics tag (or any other tag such as Facebook) configured in GTM, make sure you don't set the same tag Id in the Services Params above, as this would cause the tag to load twice.

For example, if you have a Google Analytics tag setup in GTM, your Services Params googleAnalyticsId value should be "" (empty). You only need to set your GTM Id in the Services Params, then GTM will take care of firing all the tags you've setup there.

In other words, only use the Services Params for tags NOT setup in GTM.

Comments: Comments are on by default when you set a disqusShortname value. Comments can be turned off an a post-by-post basis by using the Frontmatter comments variable and setting it to false.

Tip: create a config.dev.toml file with test values for each service to prevent false positives on trackers.

The logo in the website's Header can be shown as 1) styled text, 2) an image, or 3) an inline svg.

1. TEXT: Show the website's Title (.Site.Title param) in styled text instead of a logo:

[params.logo]
inline = false
path = ""

2. IMAGE: Display the logo as an image (<img>):

[params.logo]
inline = false
path = "image/brand/logo.png"

Note: any file type (extension) may be used, i.e., .jpg, .gif, .svg, etc.

3. INLINE SVG: Display the logo as an inline svg (<svg>):

Note: Axiom uses Hugo's readFile function to get the contents of the SVG as a string. The path must be relative to the Static directory (/static/) A CDN URL cannot be used with readFile.

[params.logo]
inline = true
path = "image/brand/logo.svg"

Advantages with this option include the ability to manipulate the SVG with styles, such as changing the color or adding a hover effect. Also, it reduces HTTP requests by one.

Images

General image config options:

[params.image]
# Dimensions of the 'Feature' image (pixels)
width = "2048"
height = "1024"
# Favicons (suggest to store .ico at root of website or CDN)
faviconIco = "favicon.ico"
faviconAlt = "image/brand/favicon.png"
# High-res square version of your Icon or Logo (recommended 2048x2048 px)
icon1To1 = "image/brand/icon-1-1.png"
# High-res rectangular version of your Icon or Logo (recommended 2048x1024 px)
icon2To1 = "image/brand/icon-2-1.png"
# Default 'Feature' image
default = "image/page-default.webp"

Further detail on some of the options in the Images section:

default: Choose a default image that represents the overall theme of the brand or website. This will be used for Structured Data and Open-Graph for Pages/Posts without a Feature image. It should be size to match the settings entered for width and height.

Fonts

The Font section controls if the Type CSS (/assets/type.css) stylesheet is used, and if font files are preloaded:

See also the Extending Typography documentation.

[params.font]
# MIME type of font files
type = ""
# Path to font files
path = ""
# List of font files from 'type.css' to preload (setting to empty, disables)
files = []

If the files array is populated, Axiom will preload the list of font files, and link the Type CSS stylesheet in the website's <head> section. You'll need to have the font files either stored locally in a /static/font/ directory or hosted on a CDN supported by Axiom. You can set the directory where the font files are located with the path option.

Example settings to load fonts:

type = "font/woff"
path = "font/"
files = ["title-400.woff", "sans-400.woff", "serif-italic-400.woff"]

If you have many font files added in the Type CSS file, you don't have to preload all of them. You can list a subset of the most important ones in the Config, and let the others load normally. As long as at least one font file is in the files array, the Type CSS features will be enabled.

If the files array is empty, Axiom will use the Tailwind CSS font-family fallback settings. Either way, the display will look very similar, unless your eye is trained to typography.

CDNs

Axiom supports CDNs or local file storage. Currently Cloudinary is the only CDN implemented.

[params.cdn]
# Asset delivery provider (values: local, cloudinary)
provider = "local"
# Default asset type (values: image, video, raw)
type = "image"

# Cloudinary CDN
[params.cloudinary]
# Base URL for your account (replace CLOUD_NAME, note: add trailing slash)
host = "https://res.cloudinary.com/CLOUD_NAME/"
# URL versioning, e.g., "v12345/"
version = ""
# Cloudinary Internal paths. DON'T EDIT!
image = "image/upload/"
raw = "raw/upload/"
video = "video/upload/"

# Cloudinary asset transformation presets
# Applied internally by Axiom or when using Shortcodes in Content
[params.cloudinary.presets]
# Image: general use, all-around
base = "f_auto,q_auto/"
# Image: content body
page = "w_auto,dpr_auto,c_scale,f_auto,q_auto/"
# Image: content feature
feature = "w_auto,dpr_auto,c_scale,f_auto,q_auto/"
# Image: content summary
summary = "w_auto,dpr_auto,c_scale,f_auto,q_auto/"

When provider is set to one of the supported CDN values, all paths will be output as absolute URLs. The URL structure will be assembled based on each CDN's design. See the /axiom/layouts/partials/cdn-src.html file for details.

Alert: All config paths/URLs must end with a trailing slash /!

Axiom comes with two configurable menus. Refer to the Hugo Menus Documentation to learn how to add or remove links:

[menu]
[[menu.main]]
[[menu.foot]]

NOTE: Be careful adding too many items to the menus, as this could degrade mobile user experience.

Languages

Axiom is multi-language ready:

[languages]
[languages."en"]
weight = 1
languageName = "English"

NOTE: If additional languages are added, be sure to create the corresponding lang file in the i18n directory, and menus in the Config file.

Refer to the Hugo Multilingual Documentation to learn how to add additional language support.