Alberto Luna's blog

Updating 11ty from version 2 to 3

I decided to update my blog the latest version of 11ty. My blog was created over 2 years ago using eleventy-base-blog. Luckily for me I did not personalised almost anything so I was not expecting to have too many issues.

What I did

I went to the package.json and I just updated all the dependencies to their latest versions. I did not read any of the migration guides, I just wanted to upgrade and see what happens. I went from this:

{
	"@11ty/eleventy": "^2.0.1",
	"@11ty/eleventy-img": "^3.1.1",
	"@11ty/eleventy-navigation": "^0.3.5",
	"@11ty/eleventy-plugin-bundle": "^1.0.4",
	"@11ty/eleventy-plugin-rss": "^1.2.0",
	"@11ty/eleventy-plugin-syntaxhighlight": "^5.0.0",
	"dotenv": "^16.3.1",
	"dotenv-cli": "^7.3.0",
	"luxon": "^3.3.0",
	"markdown-it-anchor": "^8.6.7",
	"webdav": "^5.3.1",
	"wrangler": "^3.22.4"
}

To this:

{
	"@11ty/eleventy": "^3.1.2",
	"@11ty/eleventy-img": "^6.0.4",
	"@11ty/eleventy-navigation": "^1.0.4",
	"@11ty/eleventy-plugin-bundle": "^3.0.7",
	"@11ty/eleventy-plugin-rss": "^2.0.4",
	"@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2",
	"dotenv": "^17.2.3",
	"dotenv-cli": "^11.0.0",
	"luxon": "^3.7.2",
	"markdown-it-anchor": "^9.2.0",
	"webdav": "^5.8.0",
	"wrangler": "^4.47.0"
}

Then I just run the preview version and checked everything that broke.

Issues I found

Broken build

The first thing I saw is that it seems like the plugin infrastructure has changed and the 11ty configuration was no longer valid. To fix this I went to the current blog template and I just copied the up to date config and I replaced it in my project.

No blog content

The content of the blog is hosted in my personal Nextcloud instance, where all my Obsidian notes are. Using a simple NodeJS script I download all the Markdown files to a .gitignored folder in content and then I run 11ty. After the update I saw the regular pages, but not any of my blog posts. After a web search it seems that now .gitignored files are excluded from the build, so I had to opt out of this in my config file with eleventyConfig.setUseGitIgnore(false);.

URL slugs

During the update I also copied blog.11tydata.js to my repo and it didn't include the computed property permalink. This is how the property looks in my case:

permalink(data) {
	if (data.draft && !process.env.BUILD_DRAFTS) {
		return false;
	}

	if (data.permalink) {
		return data.permalink;
	}

	return `blog/${this.slugify(data.page.fileSlug)}/`;
}

And I got this error:

[11ty] Problem writing Eleventy templates:
[11ty] 1. Having trouble rendering njk template ./content/eleventy-plugin-feed-alberto-luna-personal-blog-atom.njk (via TemplateContentRenderError)
[11ty] 2. (./content/eleventy-plugin-feed-alberto-luna-personal-blog-atom.njk)
[11ty]   EleventyNunjucksError: Error in Nunjucks Filter `htmlBaseUrl` (./content/eleventy-plugin-feed-alberto-luna-personal-blog-atom.njk) (via Template render error)
[11ty] 3. Invalid url transformed in the HTML `` plugin. Did you attempt to link to a `permalink: false` page? Received: false

The solution for this was to remove the draft condition:

permalink(data) {
	if (data.permalink) {
		return data.permalink;
	}

	return `blog/${this.slugify(data.page.fileSlug)}/`;
}

After this change everything was working as expected again.

Conclusion

Maybe I just want software not to change and I am being to naive, but I wish the upgrade process was just updating all the dependencies to latest, build and deploy. I hope I don't have to change any of code in the next 2 years when (probably) upgrading to v4.