From 1369b45721a1e06d61072cedf30d7cfe375e8b53 Mon Sep 17 00:00:00 2001 From: erik Date: Sat, 27 Feb 2016 20:05:29 -0500 Subject: Create github-pages-tutorial.md As requested in #397. --- web/tutorials/github-pages-tutorial.md | 130 +++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 web/tutorials/github-pages-tutorial.md (limited to 'web/tutorials') 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 +``` + +### 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 +``` -- cgit v1.2.3 From 03dbc4e99b2a662cb9d4f0a6616cc6465483b9dd Mon Sep 17 00:00:00 2001 From: erik Date: Sun, 28 Feb 2016 03:34:21 -0500 Subject: Adds introduction and fixed formatting issues --- web/tutorials/github-pages-tutorial.md | 67 +++++++++++++++------------------- 1 file changed, 30 insertions(+), 37 deletions(-) (limited to 'web/tutorials') diff --git a/web/tutorials/github-pages-tutorial.md b/web/tutorials/github-pages-tutorial.md index 5e5c104..f81c593 100644 --- a/web/tutorials/github-pages-tutorial.md +++ b/web/tutorials/github-pages-tutorial.md @@ -1,5 +1,16 @@ ## Using Hakyll with GitHub Pages +[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. + +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. + +This guide will walkthrough the creation and setup of a GitHub site that has two independent branches. + +1. ```master``` - This is where your site lives. It's what you see when you go to ```https://.github.io```. This branch *needs* to be called master. +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. + +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. + 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/). @@ -50,11 +61,15 @@ So everything's all setup and we're ready to deploy. Temporarily save any uncommitted changes that may exist in the current branch. -```git stash``` +``` +git stash +``` Ensure we are in the correct branch. -```git checkout develop``` +``` +git checkout develop +``` Get a clean build of our site. @@ -65,15 +80,21 @@ 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``` +``` +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``` +``` +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/. .``` +``` +cp -a _site/. . +``` Commit our changes. @@ -84,7 +105,9 @@ git commit -m "publish." And send them to GitHub. -```git push origin publish:master``` +``` +git push origin publish:master +``` Final clean up and return to the original state. @@ -96,35 +119,5 @@ git stash pop ### *And that's it.* -Here is a full listing of the script. +A full listing of the "script" is available [here](https://gist.github.com/narrative/5edb976b2f8754a79104). -``` -# 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 -``` -- cgit v1.2.3 From c0e576a8bd51c425ada0dd3801e93af9d70bf0fd Mon Sep 17 00:00:00 2001 From: Erik Stevenson Date: Tue, 29 Mar 2016 18:30:14 -0400 Subject: Rename branch, inline script listing, add metadata --- web/tutorials/github-pages-tutorial.md | 77 ++++++++++++++++++++++++++++------ 1 file changed, 64 insertions(+), 13 deletions(-) (limited to 'web/tutorials') diff --git a/web/tutorials/github-pages-tutorial.md b/web/tutorials/github-pages-tutorial.md index f81c593..77d370f 100644 --- a/web/tutorials/github-pages-tutorial.md +++ b/web/tutorials/github-pages-tutorial.md @@ -1,4 +1,9 @@ -## Using Hakyll with GitHub Pages +--- +title: Using Hakyll with GitHub Pages +author: Erik Stevenson +--- + +## Introduction [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. @@ -19,7 +24,7 @@ In the interest of keeping this guide as simple as possible, I'll be making a fe These instructions should be easy to adapt for any situation though. -### GitHub Setup +## GitHub Setup 1. If required, create a new repository for your blog. 2. If required, create a ```master``` branch. @@ -32,7 +37,7 @@ _site/ .stack-work/ ``` -### Local setup +## 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. @@ -53,11 +58,11 @@ git commit -m "initial commit." git remote add origin ``` -### Deployment +## 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. +> **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. @@ -84,13 +89,17 @@ Update the local list of remote branches to ensure we're able to checkout the br 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. +Switch to the `master` branch. + +> **Note:** Checking out this branch does not overwrite the files that Hakyll just produced because we have '_site' listed in both .gitignore files. ``` -git checkout -b publish --track origin/master +git checkout -b master --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. +Next, copy the freshly made contents of '_site' over the old ones. + +> **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. ``` cp -a _site/. . @@ -100,24 +109,66 @@ Commit our changes. ``` git add -A -git commit -m "publish." +git commit -m "Publish." ``` And send them to GitHub. ``` -git push origin publish:master +git push origin master:master ``` Final clean up and return to the original state. ``` git checkout develop -git branch -D publish +git branch -D master +git stash pop +``` + +## Putting it all together + +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). + +``` +# 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 master --track origin/master + +# Overwrite existing files with new files +cp -a _site/. . + +# Commit +git add -A +git commit -m "Publish." + +# Push +git push origin master:master + +# Restoration +git checkout develop +git branch -D master git stash pop ``` -### *And that's it.* +*And that's it.* + +## Removing old files with `rsync` -A full listing of the "script" is available [here](https://gist.github.com/narrative/5edb976b2f8754a79104). +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`. + +``` +rsync -a --filter='P _site/' --delete-excluded _site/ . +``` +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. -- cgit v1.2.3