Layout Customization

October 29, 2025· 3 min · Gautham Chettiar

Table Of Contents

Learn how to customize the Freedom theme’s layout visibility settings. Control which components display on your pages using configuration toggles for titles, breadcrumbs, metadata, navigation, and more.

Overview #

Freedom theme provides flexible layout customization through boolean configuration flags. You can control the visibility of various UI components at different levels:

Site-wide configuration - Apply settings globally via hugo.yaml
Kind-level configuration - Different settings for home, page, section, taxonomy, term
Section-level configuration - Override for specific content sections
Type-level configuration - Override for specific content types
Page-level configuration - Individual page overrides via front matter

Configuration Hierarchy #

Configuration resolution follows this priority (highest to lowest):

Page front matter: Parameters in individual page front matter (highest priority)
Type-level: Based on page type (params.type.<typename>)
Section-level: Based on content section (params.section.<sectionname>)
Kind-level: Based on page kind - home, page, section, taxonomy, term (params.kind.<kindname>)
Site-level: Global site parameters (params)
Defaults: Built-in theme defaults (lowest priority)

Available Configuration Options #

Config Key	Default	Description
`showPageTitle`	`true`	Display title on regular content pages
`showTitle`	`true`	Display title on section/taxonomy/term pages
`showThemeToggle`	`true`	Light/dark mode switcher button
`showMenu`	`true`	Main navigation menu display
`showBreadcrumb`	`true`	Hierarchical navigation showing page location in site structure
`breadcrumbSeparator`	`" » "`	Custom separator between breadcrumb items
`showHeadingAnchor`	`true`	Display anchor link on every heading on a page

Page Metadata #

Config Key	Default	Description
`showAuthor`	`true`	Display author name
`showAuthorIcon`	`true`	Display user icon before author
`showDate`	`true`	Display publication date
`showDateIcon`	`true`	Display calendar icon before date
`dateType`	`"date"`	Date field to display: `date`, `publishDate`, or `lastmod`
`dateFormat`	`":date_long"`	Date format for metadata display
`showReadTime`	`true`	Display estimated reading time
`showReadTimeIcon`	`true`	Display clock icon before reading time
`readTimeWordsPerMinute`	`200`	Words per minute for reading time calculation
`showToc`	`true`	Auto-generated TOC from headings

Taxonomy Components #

Config Key	Default	Description
`showTags`	`true`	Display page tags
`showTagsCount`	`true`	Display post count for each tag
`showCategories`	`true`	Display page categories
`showCategoriesCount`	`true`	Display post count for each category
`show{Name}`	`true`	Display custom taxonomy (series, authors, etc.)
`show{Name}Count`	`true`	Display post count for custom taxonomy

List Components #

Config Key	Default	Description
`showPostList`	`true`	Display list of pages on section/taxonomy pages
`showPostListDate`	`true`	Show dates in page lists
`postListStyle`	`"none"`	List bullet style: none, disc, circle, square
`postListDateFormat`	`":date_medium"`	Date format using Hugo date formats
`postListSortBy`	`"date"`	Sort field: “date”, “weight”, or “title”
`postListSortOrder`	`"desc"`	Sort order: “asc” or “desc”
`postListPaginate`	`true`	Enable pagination for lists
`postListPageSize`	`15`	Number of items per page

Config Key	Default	Description
`showFooterText`	`true`	Display footer text section
`footerText`	(empty)	Custom footer text or HTML content

Markdown & Content Components #

Config Key	Default	Description
`showHeadingAnchor`	`true`	Display anchor links on headings for easy linking
`showCodeblockLang`	`true`	Display language label on code blocks
`showCodeblockCopy`	`true`	Display copy button on code blocks
`showBlockquoteCite`	`true`	Display cite attribution in blockquotes
`showBlockquoteCaption`	`true`	Display caption in blockquotes
`showExternalLinkIndicator`	`true`	Display indicator icon for external links
`openExternalLinkInNewTab`	`true`	Open external links in new tab

Best Practices #

Start with Defaults #

The theme provides sensible defaults. Only override what you need:

hugo.yaml
## ✅ Good - Override only what's needed
params:
  showBreadcrumb: false

## ❌ Unnecessary - These are already the defaults
params:
  showTitle: true
  showDate: true
  showAuthor: true

Use Hierarchy Wisely #

Apply settings at the appropriate level:

Site-wide (params) - Settings that apply everywhere
Kind-level (params.kind) - Different layouts for different page types
Section-level (params.section) - Section-specific overrides
Page-level (front matter) - One-off exceptions only

Keep It Consistent #

Maintain consistency within content types:

hugo.yaml
params:
  ## All blog posts get the same layout
  section:
    blog:
      showAuthor: true
      showDate: true
      showTags: true
      showReadTime: true

Test Across Page Types #

Configuration affects different page kinds:

home - Homepage (/)
page - Regular content pages
section - Section list pages (/blog/)
taxonomy - Taxonomy list pages (/tags/)
term - Individual term pages (/tags/hugo/)

Test your configuration on each type:

hugo.yaml
params:
  ## Global defaults
  showTitle: true
  
  kind:
    home:
      showTitle: false      ## Hide on home
    section:
      showTitle: true       ## Show on sections
      showPostList: true    ## With post lists

Troubleshooting #

Configuration Not Taking Effect #

Check hierarchy: Lower priority configs don’t override higher priority ones.

Configuration resolution order (highest to lowest priority):

Page front matter - params.showTitle: true (wins over everything)
Type-level - type.blog.showTitle: false
Section-level - section.blog.showTitle: false
Kind-level - kind.page.showTitle: false
Site-level - showTitle: true (lowest priority)

Icons Not Hiding #

Icon visibility is separate from component visibility:

yaml
## ✅ Correct - Hide the icon
params:
  showDate: true
  showDateIcon: false

## ❌ Won't work - Wrong key
params:
  showDate: true
  showIcon: false  ## No such key

Section Config Not Working #

Use exact section name from content directory (case-sensitive):

yaml
## ✅ Correct - matches content/blog/
params:
  section:
    blog:
      showAuthor: true

## ❌ Wrong - case mismatch
params:
  section:
    Blog:  ## Won't match 'blog' folder
      showAuthor: true

Kind Config Not Applying #

Use exact kind names: home, page, section, taxonomy, term

yaml
## ✅ Correct
params:
  kind:
    page:
      showBreadcrumb: false

## ❌ Wrong - not a valid kind
params:
  kind:
    post:  ## Use 'page' instead
      showBreadcrumb: false

Freedom