@@ -1,5 +1,16 @@
11## Using Hakyll with GitHub Pages
22
3+[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.
4+
5+Working 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.
6+
7+This guide will walkthrough the creation and setup of a GitHub site that has two independent branches.
8+
9+1. ```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.
10+2. ```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.
11+
12+When you're finished, you will be able to, with one command, refresh your website's contents and send any changes to your GitHub Page.
13+
314In the interest of keeping this guide as simple as possible, I'll be making a few assumptions.
415
5161. Haskell is being used with [Stack](http://docs.haskellstack.org/en/stable/README/).
@@ -50,11 +61,15 @@ So everything's all setup and we're ready to deploy.
5061
5162Temporarily save any uncommitted changes that may exist in the current branch.
5263
53−```git stash```
64+```
65+git stash
66+```
5467
5568Ensure we are in the correct branch.
5669
57−```git checkout develop```
70+```
71+git checkout develop
72+```
5873
5974Get a clean build of our site.
6075
@@ -65,15 +80,21 @@ stack exec myblog build
6580
6681Update the local list of remote branches to ensure we're able to checkout the branch we want in the next step.
6782
68−```git fetch -all```
83+```
84+git fetch -all
85+```
6986
7087Switches to a new branch called "publish" that tracks the origin "master" branch. **Note:** Checking out the publish branch does not overwrite the files that Hakyll just produced because we have '_site' in both .gitignore files.
7188
72−```git checkout -b publish --track origin/master```
89+```
90+git checkout -b publish --track origin/master
91+```
7392
7493Copy the freshly made contents of '_site' over the old ones. Note that if a file is *no longer* being produced (for example if you deleted a blog posting), it will continue to persist in your published site until it's been removed from that repository as well.
7594
76−```cp -a _site/. .```
95+```
96+cp -a _site/. .
97+```
7798
7899Commit our changes.
79100
@@ -84,7 +105,9 @@ git commit -m "publish."
84105
85106And send them to GitHub.
86107
87−```git push origin publish:master```
108+```
109+git push origin publish:master
110+```
88111
89112Final clean up and return to the original state.
90113
@@ -96,35 +119,5 @@ git stash pop
96119
97120### *And that's it.*
98121
99−Here is a full listing of the script.
122+A full listing of the "script" is available [here](https://gist.github.com/narrative/5edb976b2f8754a79104).
100123
101−```
102−# Temporarily store uncommited changes
103−git stash
104−
105−# Verify correct branch
106−git checkout develop
107−
108−# Build new files
109−stack exec myblog clean
110−stack exec myblog build
111−
112−# Get previous files
113−git fetch -all
114−git checkout -b publish --track origin/master
115−
116−# Overwrite existing files with new files
117−cp -a _site/. .
118−
119−# Commit
120−git add -A
121−git commit -m "publish."
122−
123−# Push
124−git push origin publish:master
125−
126−# Restoration
127−git checkout develop
128−git branch -D publish
129−git stash pop
130−```