Shaun Rashid: UI Engineer and Architect

From Static to Eleventy on Netlify

In this blog post, I will outline the steps I took to convert my site from a set of files deployed through uploading a folder through Netlify's UI to a static site built using Eleventy.

While the end result (a static website) is the same before and after the conversion, changing the way that I'm building and deploying the site will enable me to do more things on my site and reduce the maintenance overhead.

The Starting Point

When I first moved my site to Netlify, I took the content from my previous Wordpress site and created a set of static HTML files for the posts I wanted to keep.

If I want to create a new post, I need to duplicate an existing HTML file and modify it accordingly. If I want to make changes across the entire site that involve changes to the HTML, I need to make the same change across a growing number of files. As I mentioned in the first entry of my "devlog", I knew this process was going to be a maintenance nightmare.

The Goal

In order to alleviate the maintenance overhead, I want to introduce a templating engine that I can use to break the HTML up into manageable chunks that can be compiled into a full webpage. Once I have that capability in place, I can start to refactor and reorganize my code.

The Process

In order to build my site using Eleventy and deploy it to Netlify, I broke the process down into five steps.

  1. Create a new Git repository to deploy the code from.
  2. Set up Eleventy.
  3. Configure Eleventy.
  4. Migrate my existing code over to the new repository.
  5. Deploy the code to Netlify.

Creating the Git Repository

If you want to do anything more than just uploading static files to Netlify, you need to upload your code to a Git repository and connect it to your Netlify site.

For my site, I chose to use Bitbucket for my Git repository. You can learn how to set up and work with a Bitbucket repository using their tutorial.

Set up Eleventy

To work with Eleventy, I needed to create a NodeJS application. I started by creating a package.json file in my project folder that looked something like this:


    {
        "name": "my-11ty-site",
        "version": "1.0.0",
        "devDependencies": {
            "@11ty/eleventy": "^0.10.0"
        }
    }

With the code above, I'm defining the name and version (required fields) and telling the application that I'm using Eleventy in my development process (to generate the static site).

As described in the Eleventy "Getting Started" documentation, you can also use npm commands to create the package.json file. I prefer to handcode most things. It's not the most efficient way to do things, but it helps me learn and remember things better.

I saved the file then ran npm install in a terminal window to install Eleventy into the application.

To generate a static site and load up a local web server, I created a test HTML file and then ran the command npx @11ty/eleventy --serve. This will take any HTML files in the project folder and generate a static set of pages in the _site folder.

When the command is run, (if all goes well) the output in the terminal will be similar to:

            
    Writing _site/index.html from ./index.html.
    Wrote 1 file in 0.08 seconds (v0.10.0)
    Watching…
    [Browsersync] Access URLs:
        ---------------------------------------
           Local: http://localhost:8080
        External: http://192.168.254.21:8080
        ---------------------------------------
                 UI: http://localhost:3002
        UI External: http://localhost:3002
        ---------------------------------------
    [Browsersync] Serving files from: _site

I opened up the "Local" URL in my browser and my test page was loaded.

Configure Eleventy

I'm a picky person when it comes to code and code organization. I wanted to change the structure of my project so that all of the files that would be used to generate my site would be in the _src folder and then output to the _static folder.

To do this, I need to create a configuration file named .eleventy.js. In this file, I had to define the input and output directories for my application:

            
    module.exports = function(eleventyConfig) {
        return {
            dir: {
                input: "_src",
                output: "_static"
            }
        }
    }

Now I was set up so that I could start moving over my existing code.

Migrate Existing Code

Now that I had organized my project folders the way that I want, I was able to copy all of the files from my static HTML site into the _src folder of my Eleventy project and run the --serve command. Eleventy processed the files and I was able to open the local URL in my browser and see my site. Success!

As I clicked through the pages on my site, I came across an issue where none of the images were loading. I verified that I had copied them into my _src but they still did not appear. I discovered that the way that Eleventy works is that it scans through the files in your input folder and processes them. It assumes that the files are template files so if it doesn't recognize a file type as a template file, it ignores the file. My image files were being ignored.

To address this issue, Eleventy has a feature called "PassThrough File Copy" which tells Eleventy to copy non-template files into the output folder based on the list of file types you configure.

You can tell Eleventy to scan through your input folder and copy files with particular file extensions or you can specify folders that you want Eleventy to copy. I chose the latter to be explicit. This method is also faster. To do this, I updated my .eleventy.js configuration file by adding this line:

            
                eleventyConfig.addPassthroughCopy("_src/images");

With this in place, the Eleventy version of my website rendered the same way as my static HTML site.

Deploy to Netlify

Once I pushed my code to Bitbucket, I was ready to deploy my site to Netlify.

I logged into Netlify and clicked on the "New site from Git" button in the top right corner and logged into Bitbucket.

Netlify loaded up my list of repositories and I chose the one with my Eleventy code. On the deploy settings screen, all the information was filled in already. I changed the Publish Directory to match the _static folder I used in my Eleventy configuration and clicked on "Deploy site".

Less than a minute later, my site was live using the new Eleventy implementation!

Return to Homepage