Donna Hogan

Posted on Mar 3, 2020 • Edited on Mar 31, 2020 • Originally published at donnacodes.com

Publishing an Eleventy site to Github Pages

#codenewbie #tutorial

Eleventy is a relatively new static site generator. I've heard it's "almost fascinatingly simple", and I have a situation at work that is perfect for this tool.

My situation

I have a small collection of one-off "posts" that are hosted on the repo's Github Pages site, almost like a blog, sort of. Some posts have a template that I just shamelessly lifted from some of the org's other communications for visual continuity.

The problem, of course, is that this is repetitive: if I ever have to make a change to that template (and I have) it must be made on each post.

Additionally, I want to continue to host it on gh-pages (to avoid making this a whole huge thing by changing), so I made an extremely minimal silly little test case to see how Eleventy plays with Github Pages.
I'm sure Netlify is amazing, but I really want to change only one thing at a time (and I also just want to see if this will work 😁)

Initializing

I started by following along with their getting started guide in the docs.
I added a single HTML template (just an <h1> element, basically), and two posts: one in Markdown and the other in HTML (since my use-case involves both). Just some text and a little image in each. I put the posts in the src directory and the template in the _includes directory, just following along with the gorgeously easy to understand docs. So far easy-peasy!

Bringing it to GitHub Pages

'0.' After pushing to Github, make a branch called gh-pages (or whatever you'd like) and go into the settings and enable Github Pages.

'1.' Then, back in your terminal, install the gh-pages package: npm install gh-pages --save-dev.

'2.' Because of this package's command line utility, we can add this item to package.json:

"scripts": {
    "deploy": "gh-pages -d _site"
},
"homepage": "/silly-eleventy-demo",

This allows us to use the command npm run deploy to push to our gh-pages branch from our _site directory (which is effectively the build/dist), and, if our account is already mapped to a custom domain, add the repo name to the url so we still land on the correct index.html.

'3.' Add this to .eleventy.js:

return {
    pathPrefix: "/silly-eleventy-demo/"
}

Because we're aiming to publish to a sub-directory (namely, the specific repo in our domain, as described here), this enables the use of Eleventy's built-in URL filter to prefix all urls with this path.

'4.' Then, assuming you have a permalink (like "myFirstPost/") in the front matter of the md or html content, make your links to it look like this:

<a href="{{ '/myFirstPost' | url }}">First Post</a>
or
<a href="{{ '/'  | url }}">Home</a>

where the | is the nunjucks pipe operator (this is also built-in to eleventy) and says to use the url filter on the string to the left of the pipe.

And finally, run npx @11ty/eleventy if you haven't already since your last edits (you can add the --serve if you want to see it live, as described in the docs) to generate the _site directory, and then run npm run deploy. The page is ready to go at "https://yourGitHubName.github.io/theRepoName"
🎊

Top comments (4)

Donna Hogan • Mar 31 '20 • Edited

Thank you for the feedback, Erich!
Your reply inspired me to look into it a little further, and learned I can use the built-in URL filter since I'm deploying to a sub-directory.

Using this, one of my links looks like this: <a href="{{ '/myFirstPost' | url }}">First Post</a>, where the | is the filter operator, and url indicates to use the url filter.

All I had to change was the formatting of those links to other posts, and add the trailing slash to the pathPrefix in .eleventy.js.
This also means I can delete _data/site.json, since there's no need to declare the pathPrefix there too.

I am going to update this mini-tutorial, thank you again!