@@ -0,0 +1,130 @@
1+## Using Hakyll with GitHub Pages
2+
3+In the interest of keeping this guide as simple as possible, I'll be making a few assumptions.
4+
5+1. Haskell is being used with [Stack](http://docs.haskellstack.org/en/stable/README/).
6+2. Creating a user/organization site (vice a project site).
7+3. You haven't changed Hakyll's default output directory of '_site/'.
8+
9+These instructions should be easy to adapt for any situation though.
10+
11+### GitHub Setup
12+
13+1. If required, create a new repository for your blog.
14+2. If required, create a ```master``` branch.
15+2. 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/).
16+3. Create a ```.gitignore``` file with at a minimum, the following entries:
17+
18+```
19+_cache/
20+_site/
21+.stack-work/
22+```
23+
24+### Local setup
25+
26+1. If required, create a new Hakyll project. If you're a stack user, there is a Hakyll template available that makes this step easy.
27+
28+```stack new myblog hakyll-template```
29+
30+2. Create a ```.gitignore``` file in your blog's directory with at a minimum, the same directories listed as in the GitHub repository.
31+3. Use the following git commands to setup your local repository.
32+
33+```
34+git init
35+# create new branch called develop and switch to it.
36+git checkout -b develop
37+# track all the source files for our blog.
38+git add .
39+# make our first commit
40+git commit -m "initial commit."
41+# and add the GitHub repository as a remote.
42+git remote add origin <URL to your GitHub pages repository>
43+```
44+
45+### Deployment
46+
47+So everything's all setup and we're ready to deploy.
48+
49+> Note: Performing the following commands from your ```develop``` branch is recommended since you will end up back in that branch at the end.
50+
51+Temporarily save any uncommitted changes that may exist in the current branch.
52+
53+```git stash```
54+
55+Ensure we are in the correct branch.
56+
57+```git checkout develop```
58+
59+Get a clean build of our site.
60+
61+```
62+stack exec myblog clean
63+stack exec myblog build
64+```
65+
66+Update the local list of remote branches to ensure we're able to checkout the branch we want in the next step.
67+
68+```git fetch -all```
69+
70+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.
71+
72+```git checkout -b publish --track origin/master```
73+
74+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.
75+
76+```cp -a _site/. .```
77+
78+Commit our changes.
79+
80+```
81+git add -A
82+git commit -m "publish."
83+```
84+
85+And send them to GitHub.
86+
87+```git push origin publish:master```
88+
89+Final clean up and return to the original state.
90+
91+```
92+git checkout develop
93+git branch -D publish
94+git stash pop
95+```
96+
97+### *And that's it.*
98+
99+Here is a full listing of the script.
100+
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+```