git.iko.soy/hakyll
on ccced51 help sign in
hakyll/web/tutorials/github-pages-tutorial.md
174 lines 5.4 kB history raw
1---
2title: Using Hakyll with GitHub Pages
3author: Erik Stevenson
4---
6## Introduction
8[GitHub Pages](http://pages.github.com) has become a popular static website hosting solution due to its simplicity. Simply push a couple files to a repository and it's off to the races.
10Working with Hakyll on a GitHub Pages-hosted website is complicated slightly due to Hakyll outputting files to a ```_site``` subdirectory, our desire to have the source code as well as the compiled site stored in a single repository, and our desire to automate it.
12This guide will walkthrough the creation and setup of a GitHub site that has two independent branches.
141. ```master``` - This is where your site lives. It's what you see when you go to ```https://<your repo>.github.io```. This branch *needs* to be called master.
152. ```develop``` - This is where your website's source is. That's all your Haskell code, your posts and templates, etc, and it's where you do work from. This name was chosen arbitrarily and can be freely substituted for any name of your choosing.
17When you're finished, you will be able to, with one command, refresh your website's contents and send any changes to your GitHub Page.
19In the interest of keeping this guide as simple as possible, I'll be making a few assumptions.
211. Haskell is being used with [Stack](http://docs.haskellstack.org/en/stable/README/).
222. Creating a user/organization site (vice a project site).
233. You haven't changed Hakyll's default output directory of '_site/'.
25These instructions should be easy to adapt for any situation though.
27## GitHub Setup
291. If required, create a new repository for your blog.
302. If required, create a ```master``` branch.
312. If applicable/desired, create/add to your repository any files that your site needs that will not be produced by your Hakyll project. For example, ```CNAME``` as outlined [here](https://help.github.com/articles/setting-up-your-pages-site-repository/).
323. Create a ```.gitignore``` file with at a minimum, the following entries:
34```
35_cache/
36_site/
37.stack-work/
38```
40## Local setup
421. If required, create a new Hakyll project. If you're a stack user, there is a Hakyll template available that makes this step easy.
44```stack new myblog hakyll-template```
462. Create a ```.gitignore``` file in your blog's directory with at a minimum, the same directories listed as in the GitHub repository.
473. Use the following git commands to setup your local repository.
49```
50git init
51# create new branch called develop and switch to it.
52git checkout -b develop
53# track all the source files for our blog.
54git add .
55# make our first commit
56git commit -m "initial commit."
57# and add the GitHub repository as a remote.
58git remote add origin <URL to your GitHub pages repository>
59```
61## Deployment
63So everything's all setup and we're ready to deploy.
65> **Note:** Performing the following commands from your ```develop``` branch is recommended since you will end up back in that branch at the end.
67Temporarily save any uncommitted changes that may exist in the current branch.
69```
70git stash
71```
73Ensure we are in the correct branch.
75```
76git checkout develop
77```
79Get a clean build of our site.
81```
82stack exec myblog clean
83stack exec myblog build
84```
86Update the local list of remote branches to ensure we're able to checkout the branch we want in the next step.
88```
89git fetch -all
90```
92Switch to the `master` branch.
94> **Note:** Checking out this branch does not overwrite the files that Hakyll just produced because we have '_site' listed in both .gitignore files.
96```
97git checkout -b master --track origin/master
98```
100Next, copy the freshly made contents of '_site' over the old ones.
102> **Note:** Deleting a file from your site's source will not remove it from your `master` repository if it has already been published. An alternative to `cp` is discussed at the end of this guide.
104```
105cp -a _site/. .
106```
108Commit our changes.
110```
111git add -A
112git commit -m "Publish."
113```
115And send them to GitHub.
117```
118git push origin master:master
119```
121Final clean up and return to the original state.
123```
124git checkout develop
125git branch -D master
126git stash pop
127```
129## Putting it all together
131Below is a complete listing of all the commands used to automate deployment to Github Pages. A `deployCommand` can be set as part of Hakyll's configuration options. More information and an example is provided [here](https://jaspervdj.be/hakyll/reference/Hakyll-Core-Configuration.html).
133```
134# Temporarily store uncommited changes
135git stash
137# Verify correct branch
138git checkout develop
140# Build new files
141stack exec myblog clean
142stack exec myblog build
144# Get previous files
145git fetch -all
146git checkout -b master --track origin/master
148# Overwrite existing files with new files
149cp -a _site/. .
151# Commit
152git add -A
153git commit -m "Publish."
155# Push
156git push origin master:master
158# Restoration
159git checkout develop
160git branch -D master
161git stash pop
162```
164*And that's it.*
166## Removing old files with `rsync`
168Earlier it was mentioned a flaw is that deleted files will persist in the published site until deleted manually. This is easily overcome by using `rsync` instead of `cp`.
170```
171rsync -a --filter='P _site/' --filter='P _cache/' --filter='P .git/' --filter='P .gitignore' --delete-excluded _site/ .
172```
174The only drawback this approach has is the requirement that *every* file in your site "go through" Hakyll. Fortunately, in many cases this is not an issue.