As asserted by Stephanie Eckles of smashingmazine.com,
Eleventy (aka 11ty) is rising in the ranks among static site generators. This Node-based builder is attractive due to its zero-config starting point, purely static output, and ease of achieving the coveted top Lighthouse performance score of four perfect 100s. Let’s dive into what else makes it unique, and learn about some essential concepts to help you successfully get started.
Well why learn how to use 11ty? With the advent of microservice architecture reaching the forefront in the coming years, it is vital that it is added to your toolkit
Easy to leverage and deploy with technologies such as Netlify, 11ty can be great for compiling files in your working directory to static HTML files. In fact, the process is barely taxing as there are many templates online to aid in the development process.
11ty is great for compiling files in your working directory into static HTML files. There are a multitude of templates online that can be leveraged to aid in this process. Many of these templates that you find online are created to function effortlessly with Netlify. However, to get your site up with github pages, it will take a tad bit more effort. In this tutorial we will be making 3 different blogs that leverage 11ty and are hosted on github pages.
These are my completed blogs that display my different dev.to posts. You can view them before we start learning.
Scratch 11ty
Source Repo
Live Github Pages Site
Hax 11ty
Source Repo
Live Github Pages Site
With a Template
Source Repo
Live Github Pages site
Building an 11ty Site from Scratch and Deploying to Github Pages
First we are going to be running through how to work with 11ty from scratch. I did this by following this tutorial. This video was also of great help and offered insight into the inner workings of 11ty.
Start by creating a new folder and then CD to it in the terminal. Run the following command:
npm install @11ty/eleventy
From here you want to open up the folder in Vscode or your preferred IDE.
Open up package.json and change your scripts to match this screenshot.
Next create a new file in the root of your project called ".eleventy.js"
Add the following into this file.
_Make sure your output is set to public because this where your index.html files will be generated. _
Your next step is to make a source folder (src) with a markdown file named index.md. Github pages looks for an index when deploying so make sure that everything is lowercase as this process is case-sensitive. Addd some content to this file and npm start to check if everything is working. If you are getting the cannot get error, trace back your steps to see if you have made any mistakes with the naming of your index file.
In order for 11ty to function, it looks for a folder called _includes. Create a folder called "_includes" in the src folder.
Now we are going to add 2 njk files in this includes folder: base and post.
For VSCODE users: if your code is in all white look for plaintext at the bottom in the blue bar and type in HTML
Go back into index.md and make sure the layout is set to your new base.njk file as it is in my repo.
Now make a blog posts folder in your src folder and add a json file called blogPosts.json --> fil the content as I have done here
You can make your posts as well inside of this folder but I opted to make them in the root to make it easier with the deployment to github pages.
Make markdowns for your different posts and then head into your index markdown. Link to your different posts that you created as depicted in this screenshot.
What follows is really important if you are deploying to github
Make a .github folder in the root with a folder named "workflows" inside of it. In this workflows folder create a yml file "main.yml"
Fill the file with the following code.
name: Build and Deploy
on: [push]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: ACTIONS_ALLOW_UNSECURE_COMMANDS
id: ACTIONS_ALLOW_UNSECURE_COMMANDS
run: echo 'ACTIONS_ALLOW_UNSECURE_COMMANDS=true' >> $GITHUB_ENV
- name: set env variable actor
run: echo 'GITHUB_ACTOR=$GITHUB_ACTOR' >> $GITHUB_ENV
- name: set env variable repo
run: echo 'GITHUB_REPOSITORY=$GITHUB_REPOSITORY' >> $GITHUB_ENV
- name: Checkout 🛎️
uses: actions/checkout@v2.3.1 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly.
with:
persist-credentials: false
- name: Install and Build 🔧 # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run: |
npm install
npm run build
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@3.5.7
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages # The branch the action should deploy to.
FOLDER: _site # The folder the action should deploy.
Thats it! Not too much of a hassle considering you will rarely be leveraging 11ty from scratch. Push to github, go into settings >> pages >> and enable github pages. If you are running into errors with jekyll, add a .nojekyll file into the root and that should fix the issue. You can add a .gitignore file if you would like as well like I did --> check my repo for assistance with this.
Working with hax11ty
Now we are going to be working with hax11ty.
Start by running the following command:
curl -fsSL https://raw.githubusercontent.com/elmsln/hax11ty/master/hax11tyme.sh -o hax11tyme.sh && sh hax11tyme.sh
CD to the folder in your terminal and run:
yarn install
yarn start
Start by heading into src >> settings.js and filling in your metadata.
From here on everything is quite easy as we have a template. Just exchange the markdowns in src >> content >> posts with yours. The main problems you may run into is with getting github pages to work with this, which is what I had to spend most of my time figuring out. Fortuantely, I was able to get it to work and can guide you through the main errors you will encounter.
First and foremost, you must ensure that you have the main.yml file in the .github >> workflows folder. Check my repo for more guidance. Without this file github CANNOT build your site correctly.
Next, you must let github pages know that you are using 11ty and not jekyll. Add a filed named ".nojekyll" into your root. You can leave it empty. Now deploy to Github pages and it should look like this.
11ty with a template
Now is the easy part. Since we will be working with a template, most of the work is already done for you. All you have to do is exchange the existing content with your own metadata and then push to github. For my attempt I leveraged the base blog.
Clone the repo and install npm. Next edit the metadata in _data/metadata.json.
Run eleventy with npx elevnty.
Now to deploy you must again ensure that you are creating the .github folder with the workflows and main.yml file. Add a .nojekyll file into the root as well. Once you are done just push to github and enable github pages. If you are running into a 404 error, make sure that your index is visible in the root.
Top comments (0)