Eleventy website to GitHub Pages with GitHub Actions
Let’s talk about our today’s goals:
- Develop a fully static website
- Host the website on GitHub Pages
- Implement GitHub Actions for CI/CD.
Initial setup
To start off, make a fresh folder and get it going by using this command. By doing so, you’ll have a package.json file ready and waiting in your directory.
npm init -y
npm install @11ty/eleventy@latest sass@latest --save-exactOnce the packages have been installed, simply access the package.json file and insert these commands within the scripts section.
"watch:sass": "sass src/static/scss:public/static/css --watch",
"build:sass": "sass src/static/scss:public/static/css",
"watch:eleventy": "eleventy --serve",
"build:eleventy": "ELEVENTY_ENV=development eleventy",
"start": "npm run watch:eleventy & npm run watch:sass",
"build": "npm run build:eleventy & npm run build:sass"Before we can start using our Eleventy skeleton, we have to include some elements. Let’s set up the folder structure as follows…
After completing that task, make sure to generate a .eleventy.js file in the main directory with the specified content:
module.exports = function (eleventyConfig) {
eleventyConfig.setBrowserSyncConfig({
files: './public/static/**/*.css',
});
return {
dir: {
input: 'src',
output: 'public',
},
};
};The configuration for the project is set in the .eleventy.js file. This is where we specify filters, add plugins, and more. With the current setup, the website reloads automatically whenever there is a change in our scss files. Additionally, the compiled scss output can be found in the public/static/css folder.
To complete the setup, we need to add the last 3 files. Start by creating an empty file named main.scss in the static/scss folder. Then, create a template file named base.njk and place it in the _includes folder. You can use the content provided below.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>{{ title }}</title>
</head>
<body>
{% block content %} {{ content | safe }} {% endblock %}
</body>
</html>Finally, include an index.md file in the src directory containing the specified content, then execute the npm run start command in your terminal.
---
layout: 'base.njk'
permalink: /
title: 'Our Eleventy page'
---
# Hola Medium!Go ahead and open up a browser, then type in localhost:8080 in the address bar. You should see “Hola Medium!” displayed on the page. To double-check that our website’s styling is working correctly, we need to edit the base.njk file by inserting the URL to our stylesheet within the <head> tag.
<link rel="stylesheet" type="text/css" href="{{ 'static/css/main.css' | url }}" media="screen" />Sure, how about we spice things up and include this in main.scss?
After that, let’s head back to the browser and check out the outcome. Thanks to setBrowserSyncConfig in our configuration, the browser should refresh on its own.
h1 {
color: green;
background-color: black;
text-align: center;
padding: 50px;
}GitHub integration
First things first. Make sure you create a .gitignore file in the main folder. This way, we can avoid pushing any unnecessary files to the repository.
# Dependencies
/node_modules
# Misc
/public
# Intellij
/.idea
# Sass
.sass-cache/
*.css.map
*.sass.map
*.scss.map
# Visual Studio Code
/.vscode
.historyGo to GitHub and make a fresh repository named my-eleventy-website. Make sure to leave the README, .gitignore, and LICENCE options unchecked, as they will be deselected by default.
Head over to the main directory of your project and execute the subsequent instructions. Remember to customize the sections between << … >>
git init
git add .
git commit -m "initial commit"
git branch -M master
git remote add origin https://github.com/ << github-username >> /eleventy-github.git
git push -u origin masterSetup GitHub pages
Okay, now that we’ve set up our repository, let’s enable GitHub Pages. Head over to the page of the repository you just created and click on the settings button located in the top right corner.
Next, click on the Pages button and choose your default branch from the dropdown menu. We will stick to our master branch. Make sure to leave /(root) as the selected folder. Finally, click on save to confirm the settings.
Construct your website utilizing GitHub Actions.
By default, GitHub pages utilizes Jekyll to generate your website. However, in our case, we’re using Eleventy, so we need to notify GitHub Pages about this. To achieve this, make an empty file named .nojekyll and place it in the root directory.
Then, create a .github folder in the root directory and within that folder, create another folder named workflows. Inside this folder, we will place the workflows that are executed by GitHub Actions.
We will be setting up 2 workflows. The first one will trigger a build when a pull request is created. Create a file named build.yml. If your default branch is not main, remember to update this in the branches array.
This particular workflow is solely for building and does not deploy your changes yet. This serves as a safety measure.
name: Build PR
on:
pull_request:
branches: ['master']
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: ['20']
steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install packages
run: npm ci
- name: Run npm build
run: npm run buildNow let’s make the build-and-deploy.yml file. This file is designed to build and deploy our website to GitHub Pages whenever there is a push on the main branch, like when a PR is merged.
name: Build and Deploy
on:
push:
branches: ['master']
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: ['20']
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install packages
run: npm ci
- name: Run npm build
run: npm run build:prod
- name: Deploy to gh-pages
uses: peaceiris/actions-gh-pages@v4
with:
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}To get started with this workflow, we first have to create an ACTIONS_DEPLOY_KEY. This key is essential for deploying our code to GitHub Pages. Just follow the instructions provided in the documentation to generate the ACTIONS_DEPLOY_KEY.
Now, let’s enhance our scripts property in the package.json file by adding extra commands when we run our build on GitHub.
"build:sass:prod": "sass src/static/scss:public/static/css --style compressed",
"build:eleventy:prod": "ELEVENTY_ENV=production eleventy",
"build:prod": "npm run build:eleventy:prod & npm run build:sass:prod"Once we’ve completed that task, we can upload all the modifications to our repository and watch the magic unfold!
git add .
git commit -m "build and deploy"
git pushGo to your GitHub repository and click on the Actions tab at the top. You’ll usually find the Build & Deploy workflow running, followed by the pages-build-deployment workflow which deploys the website to GitHub Pages once the first one is completed.
Once the Build & Deploy workflow runs, a new branch named gh-pages is automatically generated. This branch will contain the output of your Eleventy site. To ensure the website can be hosted correctly, we must notify GitHub Pages. Go to the Settings tab, choose Pages from the menu on the left, switch the branch for your GitHub Pages site to gh-pages, and click save.
Once the pages-build-deployment workflow is completed, it will automatically be triggered again. After it’s done, you can check out the final result by visiting the URL where your website is published.
Great job!
Conclusion
We’ve learned the process of setting up a simple Eleventy website, establishing workflows to build it using GitHub Actions, and ultimately publishing it on GitHub Pages.
You can find the entire source code for this project in the GitHub repository.
