Hugo Integration Guide

This guide provides resources and information for integrating Sveltia CMS with Hugo, a popular static site generator.

Starter Templates

Here are some starter templates built by the community using Hugo:

• Hugo module by privatemaker
• Hugolify by sebousan

Disclaimer

These third-party resources are not necessarily reviewed by the Sveltia CMS team. We are not responsible for their maintenance or support. Please contact the respective authors for any issues or questions.

Examples

See real-world examples of Hugo integrations in our Showcase. Most of the listed sites include links to their source code, so you can explore how they implemented Sveltia CMS with Hugo.

Setup

Adding the Admin Page

Hugo serves static files from the static folder. Create static/admin/index.html and static/admin/config.yml as described in the Getting Started guide. The admin page is then available at /admin/ on the development server started with hugo server as well as on the built site.

Configuration

Hugo stores content in the content folder, and each subfolder is a section, such as content/posts. The following example manages the posts section, storing each post as a page bundle with its images in the same folder:

media_folder: static/images
public_folder: /images
collections:
  - name: posts
    label: Posts
    folder: content/posts
    path: '{{slug}}/index'
    media_folder: ''
    public_folder: ''
    create: true
    fields:
      - { name: title, label: Title }
      - { name: date, label: Date, widget: datetime }
      - { name: draft, label: Draft, widget: boolean, default: true }
      - { name: description, label: Description, required: false }
      - { name: tags, label: Tags, widget: list, required: false }
      - { name: body, label: Body, widget: markdown }

Some notes on this configuration:

• The path option saves a post as content/posts/my-post/index.md, and the empty media_folder and public_folder options store its images in the same folder. See Using Entry-Relative Folders for details. If you prefer single files like content/posts/my-post.md, remove these three options, and images are saved in the static/images folder defined at the top level instead.
• Posts with draft: true are not published unless Hugo runs with the --buildDrafts option. The default value above makes new posts drafts, so editors need to turn the option off to publish them. Alternatively, use the Editorial Workflow to review posts before they’re published.
• Hugo supports YAML, TOML and JSON front matter. Sveltia CMS detects the format of existing files automatically and saves new files with YAML front matter by default. Set the collection’s format option to toml-frontmatter if your site uses TOML.
• Hugo’s _index.md files, which hold the content of section list pages, can be managed along with the regular entries using the index_file collection option.

Support for Hugo

We have implemented specific features to enhance the integration of Sveltia CMS with Hugo:

• Entry-relative media folders: Store media files in folders relative to their associated entries, which is a common practice in Hugo projects called page bundles.
• Nested collections: Manage a tree of sections as a folder tree in the sidebar, where each entry is stored as an _index.md file in its own folder and can be moved along with its children.
• Entry redirects: Out-of-the-box support for Hugo’s aliases front matter property, which is updated when the entry slug is changed in Sveltia CMS.
• Manual entry reordering: Use the reorder option to add the weight property to entries for controlling their order in Hugo.
• Index file inclusion: Manage Hugo’s special _index.md files for section entries.
• Translation by content directory: Put the {{locale}} placeholder in a collection’s folder option, e.g. content/{{locale}}/posts, to match a multilingual Hugo site with a contentDir per language, section index files included.
• Localizing entry slugs: Generate localized slugs for multilingual Hugo sites using the translationKey property of entries.
• Editor components: Examples of custom components that insert Hugo shortcodes into Markdown content, such as an image with a caption and a YouTube embed.
• Time formatting: A standard time is saved as HH:mm:ss instead of HH:mm for compatibility with Hugo.