Hugo

Hugo organizes content under content/<section>/ by convention, with each section mapping to a list template and each markdown file's front matter driving its page template. md0 CMS collections point at those same section folders, so editing visually doesn't change how Hugo builds the site - a full rebuild of a few thousand pages typically finishes in a few seconds since Hugo compiles directly to static HTML with no bundler step. No configuration changes needed.

How It Works

The Architecture

GitHub Repository
├── content/
│   ├── posts/         ← md0 CMS edits here
│   └── docs/
└── themes/
    └── your-theme/

Workflow:

1. Edit in md0 CMS
2. Commits to GitHub
3. Hugo reads markdown files
4. Builds static site

Hugo's file-based architecture is perfect for md0 CMS.

Setup

Prerequisites

• Hugo site (v0.110+ recommended)
• GitHub repository
• Content in content/ directory

md0 CMS Configuration

Create collections matching Hugo's structure:

# Posts collection
Name: Blog Posts
Path: content/posts/**/*.md

# Documentation collection
Name: Documentation
Path: content/docs/**/*.md

# Pages collection
Name: Pages
Path: content/*.md

Content Structure

Hugo's Content Organization

Hugo uses directory structure for organization:

content/
├── posts/
│   ├── my-first-post.md
│   └── another-post.md
├── docs/
│   ├── getting-started.md
│   └── advanced.md
└── about.md

Each directory becomes a content section.

Front Matter Format

Hugo supports YAML, TOML, and JSON. md0 CMS uses YAML:

---
title: "My First Post"
date: 2024-01-15T14:30:00Z
draft: false
tags: ["hugo", "cms"]
categories: ["Tutorial"]
author: "Jane Doe"
description: "A brief description"
---
Your content here...

Schema Configuration

Blog Post Schema

fields:
  - name: title
    type: string
    required: true

  - name: date
    type: datetime
    required: true
    format: "YYYY-MM-DDTHH:mm:ssZ"

  - name: draft
    type: boolean
    default: false

  - name: tags
    type: array
    items: string

  - name: categories
    type: array
    items: string

  - name: author
    type: string

  - name: description
    type: text
    maxLength: 160

  - name: featured_image
    type: image

Documentation Schema

fields:
  - name: title
    type: string
    required: true

  - name: weight
    type: number
    description: "Order in menu (lower = higher)"

  - name: draft
    type: boolean
    default: false

  - name: description
    type: text

Hugo Features

Content Types

Hugo automatically creates types based on sections:

content/
├── posts/          → Type: posts
├── docs/           → Type: docs
└── projects/       → Type: projects

md0 CMS collections can map to these:

Collection 1: Posts → content/posts/**/*.md
Collection 2: Docs → content/docs/**/*.md
Collection 3: Projects → content/projects/**/*.md

Taxonomies

Hugo supports tags and categories by default:

---
tags: ["hugo", "cms", "markdown"]
categories: ["Tutorial", "Guide"]
---

Create taxonomy pages in Hugo:

layouts/
├── _default/
│   ├── taxonomy.html
│   └── terms.html

Page Bundles

Hugo supports page bundles (content + resources):

content/
└── posts/
    └── my-post/
        ├── index.md
        ├── image1.jpg
        └── image2.jpg

md0 CMS pattern:

content/posts/**/index.md

Archetypes

Hugo can use archetypes (templates). md0 CMS schemas serve the same purpose but with validation.

Templates

List Template

layouts/_default/list.html:

{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ range .Pages }}
<article>
  <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
  <time>{{ .Date.Format "January 2, 2006" }}</time>
  <p>{{ .Summary }}</p>
</article>
{{ end }} {{ end }}

Single Template

layouts/_default/single.html:

{{ define "main" }}
<article>
  <h1>{{ .Title }}</h1>
  <time>{{ .Date.Format "January 2, 2006" }}</time>
  {{ if .Params.author }}
  <p>By {{ .Params.author }}</p>
  {{ end }} {{ .Content }}
</article>
{{ end }}

Advanced Features

Shortcodes

Hugo shortcodes work with md0 CMS:

{{< youtube id="abc123" >}}

{{< figure src="/images/example.jpg" title="Example" >}}

Just type them in the md0 CMS editor.

Multilingual

Hugo supports multilingual content:

content/
├── posts/
│   ├── my-post.en.md
│   └── my-post.es.md

md0 CMS collections:

English Posts: content/posts/**/*.en.md
Spanish Posts: content/posts/**/*.es.md

Custom Output Formats

Hugo can output JSON, RSS, etc. md0 CMS content works with all formats.

Deployment

Hugo + GitHub Actions

.github/workflows/hugo.yml:

name: Deploy Hugo site

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Netlify

netlify.toml:

[build]
  publish = "public"
  command = "hugo --gc --minify"

[build.environment]
  HUGO_VERSION = "0.120.0"

Vercel

Vercel supports Hugo automatically. Just connect your repository.

Image Handling

Image Processing

Hugo can process images:

{{< figure src="images/example.jpg" width="600" >}}

layouts/shortcodes/figure.html:

{{ $image := .Page.Resources.GetMatch (.Get "src") }} {{ $resized :=
$image.Resize (.Get "width") }}
<figure><img src="{{ $resized.RelPermalink }}" alt="{{ .Get "alt" }}"></figure>

Page Resources

With page bundles:

content/posts/my-post/
├── index.md
└── hero.jpg

Reference in markdown:

![Hero](hero.jpg)

Best Practices

Front Matter

Keep front matter consistent:

---
title: "Post Title"
date: 2024-01-15T14:30:00Z
lastmod: 2024-01-15T14:30:00Z
draft: false
tags: ["tag1", "tag2"]
categories: ["category1"]
author: "Author Name"
description: "SEO description"
featured_image: "/images/hero.jpg"
---

File Organization

Organize by section:

content/
├── posts/           # Blog posts
├── docs/            # Documentation
├── projects/        # Projects
└── pages/           # Static pages

URL Structure

Hugo generates URLs from file paths:

content/posts/my-post.md → /posts/my-post/
content/docs/guide.md → /docs/guide/

Configure in config.toml:

[permalinks]
  posts = "/:year/:month/:title/"
  docs = "/documentation/:title/"

Troubleshooting

Draft Content Not Showing

Hugo doesn't show drafts by default:

# Development (show drafts)
hugo server -D

# Production (hide drafts)
hugo

In md0 CMS schema:

- name: draft
  type: boolean
  default: true # Start as draft

Date Format Issues

Hugo is strict about dates. Use ISO 8601:

date: 2024-01-15T14:30:00Z  # Good
date: 2024-01-15            # Works
date: Jan 15, 2024          # Bad

Build Errors

Check:

1. Front matter is valid YAML
2. Quotes are balanced
3. Dates are formatted correctly
4. Required fields exist

Performance Tips

Content Caching

Hugo is already very fast, but for huge sites:

[caches]
  [caches.getjson]
    dir = ":cacheDir/:project"
    maxAge = "10s"

Build Optimization

[build]
  writeStats = true
  [build.buildStats]
    enable = true

Next Steps

• Create Collections for Hugo sections
• Define Schemas matching front matter
• Start Editing in md0 CMS

Related Documentation

• Next.js Integration
• Gatsby Integration
• Astro Integration