@@ -1,4 +1,9 @@
1−## Using Hakyll with GitHub Pages
1+---
2+title: Using Hakyll with GitHub Pages
3+author: Erik Stevenson
4+---
5+
6+## Introduction
27
38[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.
49
@@ -19,7 +24,7 @@ In the interest of keeping this guide as simple as possible, I'll be making a fe
1924
2025These instructions should be easy to adapt for any situation though.
2126
22−### GitHub Setup
27+## GitHub Setup
2328
24291. If required, create a new repository for your blog.
25302. If required, create a ```master``` branch.
@@ -32,7 +37,7 @@ _site/
3237.stack-work/
3338```
3439
35−### Local setup
40+## Local setup
3641
37421. If required, create a new Hakyll project. If you're a stack user, there is a Hakyll template available that makes this step easy.
3843
@@ -53,11 +58,11 @@ git commit -m "initial commit."
5358git remote add origin <URL to your GitHub pages repository>
5459```
5560
56−### Deployment
61+## Deployment
5762
5863So everything's all setup and we're ready to deploy.
5964
60−> Note: Performing the following commands from your ```develop``` branch is recommended since you will end up back in that branch at the end.
65+> **Note:** Performing the following commands from your ```develop``` branch is recommended since you will end up back in that branch at the end.
6166
6267Temporarily save any uncommitted changes that may exist in the current branch.
6368
@@ -84,13 +89,17 @@ Update the local list of remote branches to ensure we're able to checkout the br
8489git fetch -all
8590```
8691
87−Switches 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.
92+Switch to the `master` branch.
93+
94+> **Note:** Checking out this branch does not overwrite the files that Hakyll just produced because we have '_site' listed in both .gitignore files.
8895
8996```
90−git checkout -b publish --track origin/master
97+git checkout -b master --track origin/master
9198```
9299
93−Copy 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.
100+Next, copy the freshly made contents of '_site' over the old ones.
101+
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.
94103
95104```
96105cp -a _site/. .
@@ -100,24 +109,66 @@ Commit our changes.
100109
101110```
102111git add -A
103−git commit -m "publish."
112+git commit -m "Publish."
104113```
105114
106115And send them to GitHub.
107116
108117```
109−git push origin publish:master
118+git push origin master:master
110119```
111120
112121Final clean up and return to the original state.
113122
114123```
115124git checkout develop
116−git branch -D publish
125+git branch -D master
126+git stash pop
127+```
128+
129+## Putting it all together
130+
131+Below 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).
132+
133+```
134+# Temporarily store uncommited changes
135+git stash
136+
137+# Verify correct branch
138+git checkout develop
139+
140+# Build new files
141+stack exec myblog clean
142+stack exec myblog build
143+
144+# Get previous files
145+git fetch -all
146+git checkout -b master --track origin/master
147+
148+# Overwrite existing files with new files
149+cp -a _site/. .
150+
151+# Commit
152+git add -A
153+git commit -m "Publish."
154+
155+# Push
156+git push origin master:master
157+
158+# Restoration
159+git checkout develop
160+git branch -D master
117161git stash pop
118162```
119163
120−### *And that's it.*
164+*And that's it.*
165+
166+## Removing old files with `rsync`
121167
122−A full listing of the "script" is available [here](https://gist.github.com/narrative/5edb976b2f8754a79104).
168+Earlier 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`.
169+
170+```
171+rsync -a --filter='P _site/' --delete-excluded _site/ .
172+```
123173
174+The 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.