GuideMigrate to Douze
Migrate from Hugo
Map Hugo's folders, Go templates, sections and shortcodes to Douze, and port a site step by step.
A Hugo site keeps its content, its data and its static files when it moves to Douze, and Hugo's default URLs
(content/posts/first.md at /posts/first/) are Douze's too. Its templates do not carry over: Hugo uses Go
templates, Douze uses Liquid, and Douze has no template lookup by kind, section or type, so every layout is rewritten
and named by the pages that use it. Hugo builds more things in (taxonomy pages, feeds, sitemaps, Sass, asset bundling,
aliases); in Douze some of them are templates or command steps, and some are missing.
ConceptsLink to this heading
| Hugo | Douze |
|---|---|
hugo.toml / hugo.yaml |
douze.yml (Configuration) and _data/site.yml for values |
baseURL |
site.url |
params |
any data file: data/site.yml with params: is site.params |
content/ |
site.content: content |
layouts/ |
site.includes: layouts, with Liquid files |
layouts/shortcodes/ |
layouts/shortcodes/ when site.includes is layouts (or site.shortcodes) |
static/ |
move its files into the content folder: files no step claims are copied |
data/ |
site.data: data (JSON, YAML, XML; not TOML or CSV) |
assets/, Hugo Pipes |
files in the content folder; processing with command steps, tool: lightningcss |
i18n/en.toml |
_data/i18n/en.yml and the t filter (Internationalization) |
archetypes/, hugo new |
none |
themes/, modules |
none: copy the theme's files into the site |
public/ |
-o public or site.output: public (default _site) |
hugo server (port 1313) |
douze serve (port 8080, --port) |
TOML (+++) or JSON front matter |
YAML (---) only |
.Title, .Params.x |
title, x |
.Site.Title, .Site.Params.x |
site.title, site.params.x from data/site.yml |
.Site.Data.x |
x |
.Content in single.html |
content in a layout |
.Permalink, .RelPermalink |
url \| replace: 'index.html', '' \| absolute_url, url (with index.html) |
.Date, .Lastmod |
date (front matter), page.date (the file's modification time) |
baseof.html with block and define |
a layout chain: a layout's front matter names its own layout, which receives content |
partial "header.html" . |
{% include 'header.html' %} (the page's variables are visible) |
{{< figure src="x.png" >}}, {{% note %}} |
{% figure src: "x.png" %}, {% note %}...{% endnote %} with shortcode files |
Template lookup (_default/single.html, posts/list.html) |
layout in front matter or in the folder's data file |
_index.md (a section's list page) |
index.md; its front matter overrides the folder's data |
Page bundles (posts/x/index.md and its images) |
the same: the page is /posts/x/ and its files are copied next to it |
range .Pages, sections |
collections.<tag>: a data file in the folder sets tags |
| Taxonomies, term pages | tags and collections.<tag>; term pages with pagination over a list of tags |
weight ordering |
sort_by: "data.weight" |
.Paginate |
pagination front matter (Pagination) |
[permalinks] |
a permalink template in the folder's data file (Routing) |
slug, url front matter |
permalink |
aliases |
none |
draft: true (skipped unless -D) |
permalink: false |
.Summary, <!--more--> |
{{ content \| excerpt }} |
.TableOfContents |
the headings step and the toc filter |
.WordCount, .ReadingTime |
Liquid (reading time) |
ref, relref |
relative links to .md files, rewritten to the page's url |
relURL, absURL |
relative_url, absolute_url |
| Menus | a sidebar data file and the nav_* filters (Navigation) |
Image processing (.Resize, .Fill) |
the image tag, image_url (Images) |
| Chroma highlighting | the highlight step (TextMate grammars) |
| Goldmark (GFM extensions on) | Markdig: enable them in markdown |
| Built-in RSS, sitemap, robots.txt | templates (RSS, sitemap) |
| Multilingual sites | site.locales and the localize step |
getJSON, resources.GetRemote |
data written before the build (Data files) |
Differences to watch forLink to this heading
- Go template syntax in content. Douze renders Markdown pages as Liquid before Markdown. A Hugo shortcode call
left in a page,
{{< figure >}}, is a Liquid syntax error (A value was expected). Convert every shortcode call before the first build, or setliquid: falseon the pages you have not ported yet. - No lookup order. Hugo picks
posts/single.html, then_default/single.html. Douze renders the layout a page names. Setlayoutonce per folder in a data file (content/posts/posts.yml). - Drafts are published. Douze has no
draftkey: a draft page needspermalink: false, which also leaves it out of the collections. - Lists are built from tags. A section has no list of its pages: tag them with the folder's data file and loop over
collections.<tag>. - Encoding. Hugo's
html/templateescapes values for their context. Douze encodes Liquid output for the type of the file: HTML in pages, XML in feeds, JSON strings in.jsonfiles. In a page, a value that holds HTML needsraw. See Liquid output is encoded.
Port a site, step by stepLink to this heading
The example is a small Hugo site: posts in content/posts/, one of them a page bundle, a youtube shortcode, a
baseof.html and the single and list templates.
1. Point Douze at Hugo's foldersLink to this heading
site:
content: content
data: data
includes: layouts
url: https://example.org/
markdown:
extensions: [pipetables, strikethrough, tasklists, autolinks, footnotes, definitionlists, attributes]
title: My Hugo site
params:
description: Notes and posts
Move the files of static/ into content/. Then move Hugo's templates out of layouts/ (to hugo-layouts/, for
instance) and bring them back one by one as you rewrite them: every file of layouts/shortcodes/ is parsed as a Liquid
shortcode before the build starts, so a Go template left there stops the build
(/layouts/shortcodes/youtube.html(1,16): error: A value was expected).
2. Convert front matter to YAMLLink to this heading
+++
title = "First post"
date = 2024-05-01
+++
becomes
---
title: First post
date: 2024-05-01
---
3. Rewrite the templates in LiquidLink to this heading
baseof.html and its block "main" become a base layout that writes content, and single.html a layout whose front
matter names the base:
<!doctype html>
<html lang="en">
<head><title>{{ title }} | {{ site.title }}</title><meta name="description" content="{{ site.params.description }}"></head>
<body>{{ content }}</body>
</html>
---
layout: baseof
---
<article><h1>{{ title }}</h1>{{ content }}</article>
---
layout: baseof
---
<h1>{{ title }}</h1>
<ul>
{%- assign posts = collections.posts | sort_by: "data.weight" %}
{%- for p in posts %}
<li><a href="{{ p.data.url | replace: 'index.html', '' | relative_url }}">{{ p.data.title }}</a> {{ p.data.date | date: "%Y-%m-%d" }}</li>
{%- endfor %}
</ul>
4. Replace the template lookup with data filesLink to this heading
A data file in the section folder gives its pages a layout and a tag. The section's _index.md becomes index.md,
with its own layout and no tag:
layout: single
tags: [posts]
---
title: Posts
layout: list
tags: []
---
content/posts/second-post/index.md, a page bundle, is written to /posts/second-post/index.html, and its
photo.png next to it, so  keeps working.
5. Convert the shortcodesLink to this heading
layouts/shortcodes/youtube.html, which reads {{ .Get 0 }}, becomes
layouts/shortcodes/youtube.liquid:
---
args: [id]
---
<iframe src="https://www.youtube-nocookie.com/embed/{{ id }}" title="YouTube video" allowfullscreen></iframe>
and the call in a page changes from Hugo's syntax to a Liquid tag:
Hello. {% youtube "dQw4w9WgXcQ" %}
A shortcode with a body ({{% note %}}...{{% /note %}}) sets block: true and writes body. See
Includes and shortcodes.
6. Build and compareLink to this heading
hugo -d old
douze -o public --plain
diff -r old public
Hugo writes feeds, a sitemap and taxonomy pages that Douze does not: add the templates you need, and set redirects for
aliases on the web server.