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 deployto push to our gh-pages branch from our_sitedirectory (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 correctindex.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)
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, andurlindicates to use theurlfilter.All I had to change was the formatting of those links to other posts, and add the trailing slash to the
pathPrefixin.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!
One additional step I needed to follow was adding an empty .nojekyll file to my main branch. :)
Interesting! What did adding that file fix?
Just want to say thank you. Even 2.5 years later this is what finally got me on the right track and fixed my deploy.