DEV Community

loading...
Cover image for Publishing an Eleventy site to Github Pages

Publishing an Eleventy site to Github Pages

ddhogan profile image Donna Hogan Originally published at donnacodes.com Updated on ・3 min read

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",
Enter fullscreen mode Exit fullscreen mode
  • 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/"
}
Enter fullscreen mode Exit fullscreen mode
  • 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>
Enter fullscreen mode Exit fullscreen mode

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"
🎊

Discussion (5)

pic
Editor guide
Collapse
erwald profile image
Erich Grunewald

Thanks for this, very helpful. I would have figured there was some way of automatically appending {{site.pathPrefix}} to every link (or some subset of links following some rules) – I don't suppose you managed to figure out whether that was possible?

Collapse
ddhogan profile image
Donna Hogan Author • 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!

Collapse
erwald profile image
Erich Grunewald

Thanks, that's just what I was looking for!

Collapse
amwelles profile image
Autumn Welles

One additional step I needed to follow was adding an empty .nojekyll file to my main branch. :)

Collapse
ddhogan profile image
Donna Hogan Author

Interesting! What did adding that file fix?