GuideMigrate to Douze
Migrate from Eleventy
Map Eleventy's folders, data, collections, pagination and plugins to Douze, and port a Liquid site step by step.
Douze follows Eleventy's model closely: _includes and _data folders, layouts that wrap content, directory data
files, tags that build collections, the same pagination front matter and the same collection order (date, then
source path). A site written in Liquid ports with few changes. Nunjucks, WebC and JavaScript templates, JavaScript data
files and everything registered in eleventy.config.js (filters, shortcodes, collections, plugins) have to be
rewritten.
ConceptsLink to this heading
| Eleventy | Douze |
|---|---|
eleventy.config.js / .eleventy.js |
douze.yml, optional (Configuration) |
dir.input |
-s <dir>, or site.content in douze.yml |
dir.output (_site) |
-o <dir> or site.output (default _site) |
dir.includes (_includes), dir.layouts |
site.includes (default _includes); layouts live there too |
dir.data (_data) |
site.data (default _data) |
pathPrefix and the url filter |
the path of site.url and the relative_url filter |
| Liquid templates (liquidjs) | Liquid templates (Fluid) |
| Nunjucks, WebC, 11ty.js, Handlebars, Pug templates | not supported: rewrite in Liquid |
markdownTemplateEngine: liquid (the default) |
Markdown is always rendered as Liquid first, fences excepted |
addPassthroughCopy |
not needed: files that no step claims are copied as they are |
.eleventyignore, .gitignore |
not read: keep the site in a content folder, or narrow the inputs of the workflow |
| Front matter (YAML, also JSON or JS) | YAML front matter only |
layout: layouts/post.njk |
layout: layouts/post.liquid, or layouts/post (tries .liquid, then .html) |
addLayoutAlias |
none: name the file |
{{ content \| safe }} (Nunjucks) |
{{ content }} |
{% include "x.liquid" %}, {% render "x.liquid", a: 1 %} |
the same, from the includes folder |
addShortcode, addPairedShortcode |
a Liquid file in _includes/shortcodes/ (Includes and shortcodes) |
addFilter |
none: a shortcode, a computation in Liquid, or a command step |
Global data _data/site.json |
the same, site.title |
Global data _data/*.js |
not supported: JSON, YAML or XML, or a file written by a command or script before the build |
Directory data posts/posts.json |
the same, and the file can have any name (posts/defaults.yml) |
Template data post.11tydata.json |
none: front matter, or a folder of its own |
eleventyComputed |
none: compute in the template |
tags, collections.all, collections.<tag> |
the same (Collections) |
addCollection |
where_exp, sort_by, group_by_exp on collections.all |
eleventyExcludeFromCollections |
none; permalink: false removes a page from the build and the collections |
Collection item post.url, post.data.title |
post.url (with index.html), post.data.title |
post.date, post.inputPath |
the same: post.date is the front matter date, else the file time |
post.content, post.templateContent |
post.content with a collect step that sets content: true |
page.url |
url, which ends with index.html |
page.date (front matter date, else the file's creation time) |
date is the front matter value; page.date is always the file's modification time |
page.fileSlug, page.inputPath, page.outputPath |
none |
permalink: /about/, permalink: false |
the same |
pagination (data, size, alias, resolve: values) |
the same (Pagination) |
pagination.href.next, pagination.href.previous |
pagination.page.next.href, pagination.page.previous.href |
pagination.filter, reverse, before, addAllPagesToCollections |
none |
getNextCollectionItem, getPreviousCollectionItem |
a loop that compares p.url with url (below) |
| Syntax highlighting plugin | the highlight step |
| Image plugin | the image tag and the image steps (Images) |
| RSS plugin | a feed.xml.liquid template (Add an RSS feed) |
Navigation plugin (eleventyNavigation) |
a sidebar data file and the nav_* filters (Navigation) |
| i18n plugin | site.locales and the localize step (Internationalization) |
--serve, --watch, --incremental |
douze serve, douze watch; every build is incremental (Cache) |
Differences to watch forLink to this heading
- HTML encoding. Eleventy's Liquid writes values as they are. Douze encodes what
{{ }}writes as HTML in pages (XML in feeds): a value that holds HTML needs therawfilter. See Liquid output is encoded. .liquidpages. A page namedblog.liquidis written by Eleventy to/blog/. Douze writes a.liquidfile without a second extension under its own name: rename itblog.html(HTML pages are rendered as Liquid too), or give it apermalink.feed.xml.liquidis written asfeed.xml, as expected.- Filters. Recent liquidjs versions have Jekyll's filters; Douze has only some of them:
slugifyisslug, andgroup_by,push,array_to_sentence_string,number_of_words,date_to_stringdo not exist and return their input unchanged. See From Jekyll for the full list. - Markdown. Eleventy's markdown-it renders tables and strikethrough by default; Douze renders CommonMark until a
markdownsection enables extensions. - What is published. Eleventy processes its template formats and copies only what
addPassthroughCopynames. Douze copies every file of the content folder that no step claims, and treats.json,.ymland.xmlfiles there as folder data. - Dates. A front matter
datewithout a time is midnight in the build machine's time zone.
Port a site, step by stepLink to this heading
The example is a small Eleventy blog with its sources in src/: two layouts, a directory data file for the posts, and
a paginated blog index.
1. Build with the source folderLink to this heading
Eleventy's src/_includes and src/_data are Douze's default folders when src is the source folder, so the site
builds without a douze.yml:
douze -s src -o _site
When the input folder is the project root, add a content folder rather than publishing the whole project: move the
pages into _content/ (keeping _includes and _data at the root), or set site.content, site.includes and
site.data in douze.yml.
2. Convert the templates to LiquidLink to this heading
Rewrite Nunjucks templates in Liquid: {% extends %} and {% block %} become a layout chain (a layout's own front
matter names its layout), {{ x | safe }} becomes {{ x | raw }} where x holds HTML, and macros become includes or
shortcodes. Rename blog.liquid to blog.html.
<!doctype html>
<html lang="en">
<head><title>{{ title }} | {{ metadata.title }}</title></head>
<body><main>{{ content }}</main></body>
</html>
---
layout: layouts/base.liquid
---
<article>
<h1>{{ title }}</h1>
<time datetime="{{ date | date_to_xmlschema }}">{{ date | date: "%B %-d, %Y" }}</time>
{{ content }}
</article>
The next post in a layout, as getNextCollectionItem gives it (forloop.index is the index of the next item):
{%- for p in collections.posts %}
{%- if p.url == url %}{% assign next = collections.posts[forloop.index] %}{% endif %}
{%- endfor %}
{%- if next %}<a href="{{ next.url | replace: 'index.html', '' }}">{{ next.data.title }}</a>{% endif %}
3. Keep the data filesLink to this heading
src/_data/metadata.json is metadata, as in Eleventy. The directory data file keeps working:
{ "tags": "posts", "layout": "layouts/post.liquid" }
Convert .11tydata.js and _data/*.js files to JSON or YAML, or have a script write them before the build
(Data files).
4. Update collection loops and paginationLink to this heading
Items of collections have their front matter under data (url, date and inputPath are also at their root), and pagination links are under
pagination.page:
---
title: Blog
layout: layouts/base.liquid
pagination:
data: collections.posts
size: 10
alias: posts
permalink: "/blog/{% if pagination.pageNumber > 0 %}{{ pagination.pageNumber | plus: 1 }}/{% endif %}"
---
<ul>
{%- for post in posts %}
<li><a href="{{ post.data.url | replace: 'index.html', '' }}">{{ post.data.title }}</a></li>
{%- endfor %}
</ul>
{%- if pagination.page.previous %}
<a href="{{ pagination.page.previous.href | replace: 'index.html', '' }}">Newer</a>
{%- endif %}
{%- if pagination.page.next %}
<a href="{{ pagination.page.next.href | replace: 'index.html', '' }}">Older</a>
{%- endif %}
Collections are sorted oldest first and pagination has no reverse: this index lists the oldest posts first. To list
the newest first without pagination, loop with reversed.
5. Replace filters, shortcodes and pluginsLink to this heading
A shortcode registered in JavaScript becomes a Liquid file. addShortcode("youtube", id => ...) is:
---
args: [id]
---
<iframe src="https://www.youtube-nocookie.com/embed/{{ id }}" title="YouTube video" allowfullscreen></iframe>
Pages call it the same way, {% youtube "dQw4w9WgXcQ" %}. Replace the syntax highlighting plugin with the highlight
step, the image plugin with the image tag, and the RSS plugin with a feed template.
6. Compare the outputLink to this heading
Build both and compare:
npx @11ty/eleventy --input=src --output=old
douze -s src -o _site --plain
diff -r old _site
Tag pagesLink to this heading
Eleventy generates one page per tag with pagination: { data: collections, size: 1, alias: tag, filter: [all] }.
Douze's pagination has no filter, and collections also has all and urls, so paginating it writes
/tags/all/ and /tags/urls/ too. List the tags in a data file and paginate that instead:
- posts
- notes
---
pagination:
data: tagList
size: 1
alias: tag
permalink: "/tags/{{ tag | slug }}/"
---
<h1>{{ tag }}</h1>
{%- for post in collections[tag] %}
<a href="{{ post.data.url | replace: 'index.html', '' }}">{{ post.data.title }}</a>
{%- endfor %}