diff options
Diffstat (limited to 'web/tutorials')
| -rw-r--r-- | web/tutorials/01-installation.markdown | 32 | ||||
| -rw-r--r-- | web/tutorials/02-basics.markdown | 22 | ||||
| -rw-r--r-- | web/tutorials/04-compilers.markdown | 8 | ||||
| -rw-r--r-- | web/tutorials/external-add-tags-to-your-hakyll-blog.md | 6 | ||||
| -rw-r--r-- | web/tutorials/external-clean-urls-with-hakyll.md | 6 | ||||
| -rw-r--r-- | web/tutorials/external-deploying-with-widely.md | 6 | ||||
| -rw-r--r-- | web/tutorials/external-functionfield.md | 6 | ||||
| -rw-r--r-- | web/tutorials/external-inlining-and-compressing-css.md | 6 | ||||
| -rw-r--r-- | web/tutorials/faq.markdown | 12 | ||||
| -rw-r--r-- | web/tutorials/github-pages-tutorial.md | 174 |
10 files changed, 243 insertions, 35 deletions
diff --git a/web/tutorials/01-installation.markdown b/web/tutorials/01-installation.markdown index cede105..ce4e30b 100644 --- a/web/tutorials/01-installation.markdown +++ b/web/tutorials/01-installation.markdown @@ -6,17 +6,13 @@ author: Jasper Van der Jeugt Installation ------------ -Installation is provided using [cabal], and some packages are available for -different distributions. +Installation is provided via Hackage, and some packages are available for +different distributions. For installation from source (i.e. via Hackage), +[stack] is recommended: - $ cabal install hakyll + $ stack install hakyll -[cabal]: http://www.haskell.org/cabal/ - -If you have a recent installation of `cabal` and your time is somewhat valuable, -use: - - $ cabal install -j hakyll +[stack]: http://www.haskellstack.org/ Linux distro packages: @@ -34,27 +30,21 @@ started: This creates a folder `my-site` in the current directory, with some example content and a generic configuration. -If `hakyll-init` is not found, you should make sure `$HOME/.cabal/bin` is in -your `$PATH`. - -(If you're on OS X you may not have a bin directory in `$HOME/.cabal`. In this -case, check `$HOME/Library/Haskell/bin` and put it on your path if you find -`hakyll-init` there. See [here] for more information on installation paths on -OS X.) - -[here]: http://www.haskell.org/haskellwiki/Mac_OS_X_Common_Installation_Paths +If `hakyll-init` is not found, you should make sure your stack bin path +(usually `$HOME/.local/bin`) is in your `$PATH`. You can check your stack local +bin path by running `stack path --local-bin-path`. The file `site.hs` holds the configuration of your site, as an executable haskell program. We can compile and run it like this: $ cd my-site - $ ghc --make -threaded site.hs - $ ./site build + $ stack build + $ stack exec site build If you installed `hakyll` with a preview server (this is the default), you can now use - $ ./site watch + $ stack exec site watch and have a look at your site at [http://localhost:8000/](http://localhost:8000/). diff --git a/web/tutorials/02-basics.markdown b/web/tutorials/02-basics.markdown index 2e224a7..b79d336 100644 --- a/web/tutorials/02-basics.markdown +++ b/web/tutorials/02-basics.markdown @@ -7,24 +7,24 @@ Building and cleaning --------------------- If you followed along with the previous tutorial, you should now have the -example site up and running. By running `./site build`, you created two -directories: +example site up and running. By running `stack exec site build`, you created +two directories: - `_site`, with your site as HTML files, ready to be deployed; - `_cache`, which Hakyll uses internally. -`./site clean` removes these directories, and `./site rebuild` performs a -`clean` and then a `build`. +`stack exec site clean` removes these directories, and `stack exec site +rebuild` performs a `clean` and then a `build`. -In general, you want to use `./site build` when you just made changes to the -contents of your website. If you made important changes to `site.hs`, you need -to recompile `site.hs` followed by a rebuild: +In general, you want to use `stack exec site build` when you just made changes +to the contents of your website. If you made changes to `site.hs`, you need to +recompile `site.hs` followed by a rebuild: - ghc --make site.hs - ./site rebuild + stack build + stack exec site rebuild -At this point, feel free to change some files, `./site build` and see what -happens! +At this point, feel free to change some files, `stack exec site build` and see +what happens! Pages and metadata ------------------ diff --git a/web/tutorials/04-compilers.markdown b/web/tutorials/04-compilers.markdown index d283e9a..a9423dc 100644 --- a/web/tutorials/04-compilers.markdown +++ b/web/tutorials/04-compilers.markdown @@ -1,5 +1,5 @@ --- -title: More on compilers: load, and templates +title: 'More on compilers: load, and templates' author: Jasper Van der Jeugt --- @@ -115,8 +115,10 @@ you to use: - `$path$` for the original filepath of the page; - `$foo$` where foo is specified in the metadata. -`$date$` is not provided by default, you can see how we add it in the definition -of `postCtx` in `site.hs`: +`$date$` is not provided by default. In the scaffold, we use the convenience +context function `dateField`, which will parse an `Item`'s filename to check if +it begins with a date. You can see how we add it in the definition of `postCtx` +in `site.hs`: ```haskell postCtx :: Context String diff --git a/web/tutorials/external-add-tags-to-your-hakyll-blog.md b/web/tutorials/external-add-tags-to-your-hakyll-blog.md new file mode 100644 index 0000000..188e2ea --- /dev/null +++ b/web/tutorials/external-add-tags-to-your-hakyll-blog.md @@ -0,0 +1,6 @@ +--- +title: Add tags to your Hakyll blog +author: Javran Cheng +url: https://javran.github.io/posts/2014-03-01-add-tags-to-your-hakyll-blog.html +external: true +--- diff --git a/web/tutorials/external-clean-urls-with-hakyll.md b/web/tutorials/external-clean-urls-with-hakyll.md new file mode 100644 index 0000000..127a192 --- /dev/null +++ b/web/tutorials/external-clean-urls-with-hakyll.md @@ -0,0 +1,6 @@ +--- +title: Clean URLs with Hakyll +author: Rohan Jain +url: http://www.rohanjain.in/hakyll-clean-urls/ +external: true +--- diff --git a/web/tutorials/external-deploying-with-widely.md b/web/tutorials/external-deploying-with-widely.md new file mode 100644 index 0000000..635ce09 --- /dev/null +++ b/web/tutorials/external-deploying-with-widely.md @@ -0,0 +1,6 @@ +--- +title: Deploying with Widely +author: Kyle Marek-Spartz +url: http://kyle.marek-spartz.org/posts/2013-12-09-widely-and-hakyll.html +external: true +--- diff --git a/web/tutorials/external-functionfield.md b/web/tutorials/external-functionfield.md new file mode 100644 index 0000000..91df254 --- /dev/null +++ b/web/tutorials/external-functionfield.md @@ -0,0 +1,6 @@ +--- +title: Hakyll's functionField +author: Beerend Lauwers +url: http://beerendlauwers.be/posts/2015-09-21-hakylls-functionfield.html +external: true +--- diff --git a/web/tutorials/external-inlining-and-compressing-css.md b/web/tutorials/external-inlining-and-compressing-css.md new file mode 100644 index 0000000..30beca5 --- /dev/null +++ b/web/tutorials/external-inlining-and-compressing-css.md @@ -0,0 +1,6 @@ +--- +title: Inlining and compressing CSS +author: Kyle Marek-Spartz +url: http://kyle.marek-spartz.org/posts/2014-12-09-hakyll-css-template-compiler.html +external: true +--- diff --git a/web/tutorials/faq.markdown b/web/tutorials/faq.markdown index 87c1a92..e978c8d 100644 --- a/web/tutorials/faq.markdown +++ b/web/tutorials/faq.markdown @@ -27,6 +27,18 @@ You should also add this to your `.profile`, or whatever config file you use. On Windows, running `chcp 65001` before running your Hakyll executable has been reported to work. +Alternatively, you can specify this in your `site.hs`: + +```haskell +import qualified GHC.IO.Encoding as E + +main :: IO () +main = do + E.setLocaleEncoding E.utf8 + hakyll $ do + ... +``` + ## "File name does not match module name" on Mac OS Hakyll.hs:1:1: diff --git a/web/tutorials/github-pages-tutorial.md b/web/tutorials/github-pages-tutorial.md new file mode 100644 index 0000000..77d370f --- /dev/null +++ b/web/tutorials/github-pages-tutorial.md @@ -0,0 +1,174 @@ +--- +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. + +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://<your repo>.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/). +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 +``` + +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 master --track origin/master +``` + +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/. . +``` + +Commit our changes. + +``` +git add -A +git commit -m "Publish." +``` + +And send them to GitHub. + +``` +git push origin master:master +``` + +Final clean up and return to the original state. + +``` +git checkout develop +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.* + +## Removing old files with `rsync` + +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. |