diff options
| -rw-r--r-- | web/tutorials/github-pages-tutorial.md | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/web/tutorials/github-pages-tutorial.md b/web/tutorials/github-pages-tutorial.md new file mode 100644 index 0000000..5e5c104 --- /dev/null +++ b/web/tutorials/github-pages-tutorial.md @@ -0,0 +1,130 @@ +## Using Hakyll with GitHub Pages + +In the interest of keeping this guide as simple as possible, I'll be making a few assumptions. + +1. Haskell is being used with [Stack](http://docs.haskellstack.org/en/stable/README/). +2. Creating a user/organization site (vice a project site). +3. You haven't changed Hakyll's default output directory of '_site/'. + +These instructions should be easy to adapt for any situation though. + +### GitHub Setup + +1. If required, create a new repository for your blog. +2. If required, create a ```master``` branch. +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/). +3. Create a ```.gitignore``` file with at a minimum, the following entries: + +``` +_cache/ +_site/ +.stack-work/ +``` + +### Local setup + +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. + +```stack new myblog hakyll-template``` + +2. Create a ```.gitignore``` file in your blog's directory with at a minimum, the same directories listed as in the GitHub repository. +3. Use the following git commands to setup your local repository. + +``` +git init +# create new branch called develop and switch to it. +git checkout -b develop +# track all the source files for our blog. +git add . +# make our first commit +git commit -m "initial commit." +# and add the GitHub repository as a remote. +git remote add origin <URL to your GitHub pages repository> +``` + +### Deployment + +So everything's all setup and we're ready to deploy. + +> Note: Performing the following commands from your ```develop``` branch is recommended since you will end up back in that branch at the end. + +Temporarily save any uncommitted changes that may exist in the current branch. + +```git stash``` + +Ensure we are in the correct branch. + +```git checkout develop``` + +Get a clean build of our site. + +``` +stack exec myblog clean +stack exec myblog build +``` + +Update the local list of remote branches to ensure we're able to checkout the branch we want in the next step. + +```git fetch -all``` + +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. + +```git checkout -b publish --track origin/master``` + +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. + +```cp -a _site/. .``` + +Commit our changes. + +``` +git add -A +git commit -m "publish." +``` + +And send them to GitHub. + +```git push origin publish:master``` + +Final clean up and return to the original state. + +``` +git checkout develop +git branch -D publish +git stash pop +``` + +### *And that's it.* + +Here is a full listing of the script. + +``` +# Temporarily store uncommited changes +git stash + +# Verify correct branch +git checkout develop + +# Build new files +stack exec myblog clean +stack exec myblog build + +# Get previous files +git fetch -all +git checkout -b publish --track origin/master + +# Overwrite existing files with new files +cp -a _site/. . + +# Commit +git add -A +git commit -m "publish." + +# Push +git push origin publish:master + +# Restoration +git checkout develop +git branch -D publish +git stash pop +``` |