Upgrading to Eleventy v3.0 (beta)

Adam Jolicoeur — Tue, 17 Sep 2024 17:08:30 +0000

Jumping in

I took the plunge today and upgraded my site adamjolicoeur.com to the Eleventy v3.0 beta. I've been following along with the progress of v3 since it was announced and, with the latest news that Eleventy will be joining the team behind Font Awesome, felt that this was a good time to take the plunge.

Starting the process

What better place to start than 11ty.com? Scrolling towards the bottom, I found the link in the "News from the blog" section, which took me to the blog post, which I then used to get to the GitHub page specific to the Eleventy v3.0.0-beta.1 release notes. From there, I followed the instructions of installing the beta and then the migration plugin.

npm install @11ty/eleventy@beta
npm install @11ty/eleventy-upgrade-help@3

The instructions in the eleventy-upgrade-help plugin state to install @11ty/eleventy@3 yet there is no @3 version. Replace @3 with @beta to use the beta release.

Upgrading

After installing the required dependencies, a simple update to my .eleventy.js file was needed:

const UpgradeHelper = require("@11ty/eleventy-upgrade-help");

module.exports = function(eleventyConfig) {
  // If you have other `addPlugin` calls, UpgradeHelper should be listed last.
  eleventyConfig.addPlugin(UpgradeHelper);
};

Upgrade Plugin Placement

In my case, I added eleventyConfig.addPlugin(UpgradeHelper); above the eleventyConfig.setBrowserSyncConfig({ section, which contains my local browser configuration and is followed by library configuration settings.

After those updates were made, I proceeded to run both npm run build and npm start in order to build the initial files before starting up my local development server. (The instructions stated to run npm build but, knowing how my environment is configured, I knew that both prompts were needed.)

On your mark, get set, migrate!

Now that my environment was configured, it was time to kick off the migration from v2 to v3. I quickly realized though, that when updating .eleventy.js, that I had placed the UpgradeHelper plugin in the wrong area of the file. If done correctly, you should see the following in your prompt:

Unfortunately, I received this:

Realizing that I was not getting to the UpgradeHelper while also receiving a new v3 error, I rechecked my configuration file (see upgrade plugin placement) and added a new line to bypass this error: eleventyConfig.setFreezeReservedData(false);.

Plugin Output

If you're seeing output similar to what is shown in the screenshot above, you're on the right path! For me, the most important output was seeing [11ty/eleventy-upgrade-help] This plugin is intended for temporary use: once you’re satisfied please remove this plugin from your project.. This told me that the plugin had been run and that any issues would (or should) be caught and thrown.

Additional output messages

[11ty/eleventy-upgrade-help] PASSED All of your project’s .html output files (×0) are using <meta name="generator" content="Eleventy …">

Informs the reader that all files are using the correct <meta> information for Eleventy.

[11ty/eleventy-upgrade-help] PASSED Eleventy will fail with an error when you point --config to a configuration file that does not exist. You are not using --config —so don’t worry about it! Read more: https://github.com/11ty/eleventy/issues/3373

Let me know that my configuration file is in good shape while also telling me what to avoid using.

[11ty/eleventy-upgrade-help] PASSED You aren’t using --formats= or  --formats='' but if you were you should know that these are now empty template format sets. In previous versions, they were aliased to "*". Read more: https://github.com/11ty/eleventy/issues/3255

Informing me that I do not have any empty format sets.

[11ty/eleventy-upgrade-help] PASSED No {pug,ejs,haml,mustache,handlebars} templates were found in this project. If you were, you would have needed to install plugins for these: https://github.com/11ty/eleventy-plugin-template-languages. Learn more: https://github.com/11ty/eleventy/issues/3124

The upgrader checked for any files other than Markdown (.md) or (/html), which would require an additional plugin. None were found, so that plugin is not needed.

These are only a few of the messages that were given by the upgrade plugin - each one was informational and provided references to GitHub issues.

Final thoughts

The upgrade from Eleventy v2 to Eleventy v3 was fairly straightforward and simple to incorporate into my site. There was a noticeable improvement in build time and responsiveness in the process. As part of the completed build, the final line was as follows: Copied 150 Wrote 27 files in 0.11 seconds (v3.0.0-beta.1). Not bad at all!

Once the final release drops, I'll be sure to go full v3. My site builds cleanly, fast, and I'll be able to simplify things moving forward.

If you have any questions, feel free to drop them in the comments below and I'll answer as best I can! Thanks for reading!

Setting active state on navigation with Eleventy

Adam Jolicoeur — Thu, 21 Sep 2023 18:07:31 +0000

In creating my portfolio site, I wanted to have dynamic elements that would add/remove classes based on the site's structure, as well as the page content. The first step in this was the navigation.

Problem

Setting the active class to be applied when parsing through my collections, and having it only apply to particular a page, was just not working. I tried using various properties such as tag, title, and even the eleventyNavigation plugin.

{% set navPages = collections.all | eleventyNavigation %}
  <div class="navbar-nav col-md-6 justify-content-md-center">
    <a class="navbar-brand col-md-1 me-0 text-center" href="/">
      <img src="{{ "/img/navbar-logo.png" | url }}" alt="Avatar" width="32" height="32">
    </a>
    {%- for entry in navPages %}
    {# <a class="nav-link" href="{{ entry.url }}" alt="{{entry.description}}">{{ entry.title }}</a> #}
    <a class="nav-link {{ 'active' if 'entry.title' in entry.url }}" href="{{ entry.url }}" alt="{{ entry.abbreviation }}">{{ entry.title }}</a>
    {%- endfor %}
  </div>

No matter what I tried, nothing would set the active state of the page to the proper one.

Solution (easy way out)

After stumbling around through various #eleventy guides, I came across various implementations of the <% if %> statement, but none of them ever worked for me. In the end, I decided to simplify my navigation to, instead of using collections, fall back to the tried and true individual <a> for each navigation item. This allowed me to utilize the <% if %> statement to look for a specific location and, if the URL contained that string, apply the active class.

<a class="nav-link {% if '/designs' in page.url %}active{% endif %}" href="/designs" alt="Link to Designs that I have created and worked on.">designs</a>

This now applies the active class to any page that has /designs in the URL. No longer am I reliant on the collections information being read, nor am I having to worry about a page ending up on the wrong place and applying the class incorrectly.

Next steps

Ideally, I would be able to set my site to read through all of the items in my collections and then parse through that information to apply the active class correctly. As I build out my site and want to rely less on manually updating the navigation, this will become paramount (looking at you, breadcrumbs).

Conclusion

If you found this short bit of information helpful, let me know in the comments or by adding a reaction. If you have any suggestions, I'm open to hearing any and all!

View source on GitHub

DEV Community: Adam Jolicoeur