130 lines
3.5 KiB
Markdown
130 lines
3.5 KiB
Markdown
## 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
|
|
```
|