Publishing an Eleventy site to Github Pages
Tags: codenewbie, tutorial
Published: 2020-03-03 20:37:28

Eleventy is a relatively new static site generator.  I've heard it's "[almost fascinatingly simple](https://css-tricks.com/a-site-for-front-end-development-conferences-built-with-11ty-on-netlify/)", 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](https://www.11ty.dev/docs/getting-started/).
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](https://help.github.com/en/github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line), make a branch called `gh-pages` (or whatever you'd like) and go into the settings and [enable Github Pages](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).

'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](https://www.npmjs.com/package/gh-pages#command-line-utility), we can add this item to `package.json`: 
```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`:
```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](https://www.11ty.dev/docs/config/#deploy-to-a-subdirectory-with-a-path-prefix)), this enables the use of Eleventy's built-in [URL filter](https://www.11ty.dev/docs/filters/url/#url-universal-filter) to prefix all urls with this path.

'4.' Then, assuming you have a permalink (like `"myFirstPost/"`) in the [front matter](https://www.11ty.dev/docs/data-frontmatter/) of the md or html content, make your links to it look like this:
```html
<a href="{{ '/myFirstPost' | url }}">First Post</a>
or
<a href="{{ '/'  | url }}">Home</a>
```
where the ` | ` is the [nunjucks pipe operator](https://mozilla.github.io/nunjucks/templating.html#filters) (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" 
🎊