-
Notifications
You must be signed in to change notification settings - Fork 27
3. Config & Params
Customizations you can make to the site config.
The site config is organized into 3 distinct subdirectories.
-
_defaultcontains the default configuration. This will be used in any Hugo build environment (HUGO_ENVenvironment variable). Each file can be overridden by files belonging to a different environment. -
developmentis for development only configs. This is the environment set when you run the development server withhugo server. -
productionis for production only configs. This is the environment set when you build your site withhugo, or on any static host like Netlify.
For example, if you add a setting in config/production/hugo.toml that doesn't already exist in config/_default/hugo.toml, that parameter would just be included in your production build. However, if you add a setting that ALREADY exists in config/_default/hugo.toml, the production setting would override the default in production builds.
The files we're going to work with the most in config/_default/ are hugo.toml, params.toml and menus.toml.
Most of the settings are documented in their respective files so we'll only go over the most important ones here. The ones not covered are generally okay to leave as is or are up to personal preference (e.g. language, timezone, etc.). Please see the official Hugo docs for a list of all built-in configuration settings.
Config settings can be customized within config/_default/hugo.toml. Make sure this is copied to your project (editing the exampleSite in the theme won't have any impact, and you want to keep your submodule clean anyway).
Before you deploy your site, set the base URL to the FQDN (Fully Qualified Domain Name) of your site.
The title of your site. This is used in the header, footer, <title> tag on non-single pages, social share buttons, RSS feed, and schema markup (Open Graph tags / Twitter cards / Google structured data).
Enter your GA tracking ID to enable Google Analytics 4. This requires creating a GA4 property in GA. To use GTM instead of GA4, see params section.
Note: Universal Analytics was deprecated by Google on 07/01/2023 and removed from the theme.
Enter your Disqus short name to enable Disqus comments. You can also disable comments on a per-post basis in page front matter (see front matter section).
The default pagination limit for list pages (posts, taxonomy term pages, etc.).
Which taxonomies to enable.
Generally, you should comment out series and project-type to start if you haven't created a series of posts or tagged a project type in the front matter of your posts/projects. But it's not 100% necessary as those pages will still be created with placeholders.
If you create nested subsections in your content/posts/ directory, the example permalink settings will remove 'posts' from the permalink structure to keep cleaner URLs (e.g. /sub-section/example-post/ instead of /posts/sub-section/example-post/).
The [permalinks.page] settings change this for pages, while the [permalinks.section] settings change this for sections. So for the latter, it would change permalinks from /posts/sub-section/ to /subsection/.
You can comment either of these out to revert to the default behavior.
The rest of the config settings are mostly Hugo defaults (besides the Netlify ones which are covered in a different section). Please reference the Hugo documentation for help.
Params can be customized within config/_default/params.toml.
Enable or disable Netlify forms for the newsletter and contact form. If set to true, data-netlify=true will be added as an attribute to your forms and Netlify will handle the rest. To disable Netlify forms, set netlify_forms to false or disable form processing in the Netlify dashboard.
Use Google Tag Manager instead of Google Analytics 4. Generally, if you use GTM, you would want to add your GA tracking script there as having duplicate tags may be bad for performance and will lead to duplicate tracking results.
WARNING: Enabling this setting will instruct search engines not to crawl your site. You most likely want to keep this set to false or commented out.
If set to true, add your favicon files to the static directory to use a custom favicon.
Replace the default avatar image with your own custom image. First, create an assets directory at the root of the project if you don't have one already. Then, create an image file under assets and set this setting to the file path relative to assets.
Apply a grayscale filter to the avatar image. Applied by default prior to v3.2.0. Defaults to false in v3.2.0+.
Your name, most likely. Used for the author meta tag in <head>.
A global meta description for <head>. If a page has a description set in front matter, it will be overridden. Also used by the Open Graph, Twitter cards and Google structured data templates for certain fields.
Customize the text in the footer with plain text or markdown.
Custom fallback text for empty content.
Add a draft label to the title of any built drafts in a development environment only.
Customize the heading of the newsletter opt-in.
Customize the body text of the newsletter opt-in.
Customize the CTA text of the newsletter opt-in.
Enable the newsletter just above the footer text site-wide.
You can also enable the newsletter on a per-post basis in page front matter. This is not necessary if this setting is enabled in your config.
If global newsletter is false in the config, enabling it in front matter will override the global setting and vice-versa.
Enable PostCSS processing for your project. This requires the postcss-cli and autoprefixer packages which you can install with npm. See the Hugo docs for more details.
If you don't want to install these or use PostCSS, you can safely set this to false and ignore it.
custom_css allows you to specify a CSS file from which to add custom CSS.
First, create an assets directory at the root of the project if you don't already have one. Then, create a CSS file under assets and set this setting to the file path relative to assets. Otherwise, you'll get an error.
Please see Customizing for further details.
The same as above except for JS.
The next few sections are related to Open Graph tags, Twitter cards and Google structured data. Fill out the fields to the best of your ability and audit them in your <head> after building your site.
Open Graph tags behave very similarly to your site's normal metadata, with a title and description from page-level front matter and a fallback from the global site values.
The images param allows you to list the paths of images relative to your site root that can be used as a fallback for og:image in the event that no feature_image is set for the page in question. It will also look for an image file named feature.* and a list of images in page front matter before falling back to this value.
The ogLocale is simply the locale of your content (e.g. en_US).
Similarly, Twitter Cards pull metadata from your page and site-level params. The image field outlined above is also used for twitter:image with the same fallback chain.
Additionally, you can enter your Twitter handle in twitterSite and twitterCreator to populate the twitter:site and twitter:creator tags, respectively.
The available fields for Schema.org are mapped to the Person schema. So they should be related to you, the person associated with the site.
Fill your name in as the schemaName, your content's locale as the schemaLocale, and a path to an image of yourself relative to the site root for schemaImage. schemaImageWidth and schemaImageHeight should be integers that match the dimensions of the schemaImage.
There is a separate ImageObject schema that follows the same fallback rules as the og:image and twitter:image fields above, which is the primary image related to the page in question. This is separate from the schemaImage which is again, related to the Person schema.
Setting footer_socials, home_hero_socials and about_page_socials to false will disable social links in the footer, hero section of the home page, and about page, respectively. true will enable them in those locations.
Fill out your social media profile details under [social.links]. Comment out any social link you want to disable entirely.
Setting individual [social.share] values to false will disable those social share links on pages where social share links are enabled in front matter.
Menus can be customized within config/_default/menus.toml. Please see the Hugo docs for guidance.
The sample menu configuration has nested submenus included out-of-the-box. These are set using the parent field which is tied to the identifier of the top-level menu entry.
Feel free to comment out any [[main]] sections and all child fields to disable a particular menu entry. The subsection entry is just there to illustrate how you would link to a subsection under posts. You may want to disable that or modify it to match your subsection name/path.