Migrating from Eleventy

Moving from Eleventy to Ehundu is a short migration, because both follow the same model: Markdown with front matter, data by folder, collections by tag. What changes is the template engine, from Nunjucks to Twig, and that everything has its own folder. Premium Dental Clinics (in Spanish) went this way: when the original and the new one were built, 360 of the 388 files came out identical, and the other 28 had an explanation.

What translates almost as it is¶

A missing field comes out empty, as in Nunjucks, so {% if pagina.imagen %} is still valid. What in Eleventy was collections.blog | reverse | head(6) is here coleccion('blog')|invertir|limite(6).

The names of the folders, the fields other than those seven, the filters and the commands are Spanish; the quick reference has them all in one table.

What has to be rewritten¶

The templates. They go from Nunjucks (or Liquid) to Twig, which is very similar: the {% for %}, the {% if %}, the {% extends %} and the {% include %} hardly change. The templates, partials and data of other generators (.njk, .liquid, .11tydata.js) are never copied to the output, and Ehundu warns about every one it finds, so that none gets left behind.

The shortcodes. An Eleventy shortcode written in JavaScript has no equivalent, because Ehundu does not run code from the site. What it did is solved with a Twig partial, and images, videos and files inside the Markdown, with the shortcodes imagen, video and archivo, which are a closed vocabulary. The guide Templates and shortcodes explains them.

Processed images. Ehundu does not process images: it copies what is in publico/. If the original generated variants with eleventy-img, copy the ones that came out of the build of the original and describe in a data file which variants each image has. A template paints the <picture> and reads the width and the height of each file with dimensiones() (“dimensions”).

What changes without warning¶

They are few, but it is worth knowing them before comparing.

• The slug. For ordinary titles it gives the same as slugify. It differs on the diaeresis (bilingüe gives bilinguee in Eleventy), on &, on € and on the apostrophe. The affected pages keep their address with an explicit url.
• The order without a date. Eleventy gives a page without a date the creation date of the file, which changes from one machine to another. Ehundu leaves them at the end, by path, so that the result is the same on any computer.
• Indented paragraphs. Eleventy disables indented code blocks; Ehundu follows CommonMark. A paragraph that starts with four spaces after a blank line is here a code block, so when migrating you remove the indentation.
• Links. A web or email address written as it is in the Markdown is a link.
• The name of the template. layout: post works as an alias, but layout: post.njk does not: plantilla is the name of an Ehundu template, without an extension. The error tells you what it would look like.

How to check that it comes out the same¶

Build the original with its own Eleventy on a copy, not with the _site you have to hand: it usually carries leftovers from old builds. Then build the migrated site and compare the two HTMLs, normalising the whitespace. Any comparison tool will do. What matters is that every remaining difference has an explanation.

The failures of the original come to light, and it is worth fixing them in the migration instead of reproducing them. In Premium Dental, the sitemap.xml and the robots.txt came out wrapped in an HTML page, with its header and its menu, and the dentists' profiles had no title. The new site has them right.

When everything matches, deploy first to a test address, go through the pages and change the domain last. The guide Deploying the site explains how.