Hakyll is a Haskell library and program for creating static sites such as simple blogs. Hakyll sites are configured in Haskell in a similar way to xmonad. Moreover, Hakyll sites use Pandoc, which means content can be written in markup languages like Markdown and LaTeX.
Getting started with Hakyll is easy thanks to the Hakyll tutorials and examples. In addition, there are several blog posts about how to build and publish a Hakyll site:
To create a user or organization site:
Once your site is ready, add and commit all changes (except
Now, create a
Since Hakyll sites can be used with Git and GitHub, my favorite solution for drafts is simply creating a separate branch and using a pull request for each post. You can preview your site, but it'll only include the draft if you merge it to the
from https://www.stackbuilders.com/news/dr-hakyll-create-a-github-page-with-hakyll-and-circleci
--------------
using-docker-and-circleci-with-hakyll
Juan Pedro Villa published a great article (Dr. Hakyll: Create a GitHub page with Hakyll and CircleCI) explaining how to use circleci to provide continuous deliver for a hakyll site.
However, I ran into some trouble with circleci. My builds kept timing out or I’d get a cabal build error. So I figured I should take advantage of circleci’s docker support.
I started off with a simple docker image that has every thing I need to build the site.
The next step was to tell circleci to use docker to carry out the
build steps. I started out with the following, but came to find out that
circleci doesn’t currently support
Fortunately, circleci has some great documentation that provides a work around. It’s not pretty, but I was able to replace
from http://desfo.org/posts/2016-10-25-using-docker-and-circleci-with-hakyll.html
Getting started with Hakyll is easy thanks to the Hakyll tutorials and examples. In addition, there are several blog posts about how to build and publish a Hakyll site:
- Hakyll, GitHub, and building a static site with Travis CI by Tim Baumann
- Create a static site with Hakyll, GitHub, and Travis CI by Joe Nelson
- Using Hakyll with CircleCI and GitHub Pages by Sridhar Ratnakumar
- Write your blog with Hakyll and Git by Chris Done
Configure Git and GitHub
GitHub Pages gives you one user (and organization) site and one project site for each of your repositories. The most important difference between user and project sites is that GitHub uses themaster
branch to publish user sites and the gh-pages
branch to publish project sites.To create a user or organization site:
- Create a GitHub repository named username.github.io, where username is your GitHub username or organization name.
- Create an empty Git repository for your site, commit, and push:
The$ mkdir username.github.io/ $ cd username.github.io/ $ git init $ git commit --allow-empty -m "Create master branch" $ git remote add origin git@github.com:username/username.github.io.git $ git push -u origin master
master
branch is used by GitHub to publish your site. This is just an empty commit to create the branch. When your site is ready, you can push tomaster
manually, but the idea is to have a continuous integration service do that for you. - Create an orphan branch named
hakyll
for the source of your site:
The$ git checkout --orphan hakyll
hakyll
branch will contain your site's configuration and content. - Add your GitHub repository as a Git submodule at
_site
, commit, and push:
GitHub Pages is not designed to work immediately with tools like Hakyll. Since Hakyll generates your site in a directory called$ git submodule add git@github.com:username/username.github.io.git _site $ git commit -m "Create hakyll branch" $ git push -u origin hakyll
_site
, you can use that directory to update the site published by GitHub.
gh-pages
instead of master
:- Create an orphan branch named
gh-pages
, commit, and push:
$ git clone git@github.com:username/repository.git $ cd repository/ $ git checkout --orphan gh-pages $ git rm -rf . $ git commit --allow-empty -m "Create gh-pages branch" $ git push origin gh-pages
- Create an orphan branch named hakyll for the source of your site, add the GitHub repository as a submodule at
_site
, commit, and push:
$ git checkout --orphan hakyll $ git rm -rf . $ git submodule add git@github.com:username/repository.git _site $ git commit -m "Add hakyll branch" $ git push -u origin hakyll
gh-pages
branch instead of master
.Configure Hakyll
The easiest way to configure Hakyll is to use thehakyll-init
program as described in the installation instructions. Basically:- Install Hakyll:
$ cabal install hakyll
- Create the example site:
$ hakyll-init .
- Configure and build:
$ cabal configure $ cabal build
- Generate the site:
Run the preview server:$ cabal run build
And go to http://localhost:8000/.$ cabal run watch
- If you change the configuration of your site, rebuild it:
Or:$ cabal run clean $ cabal run build
$ cabal run rebuild
- It uses Bootstrap and Mark Otto's Bootstrap blog example.
- It includes a basic feed configuration for RSS and Atom as described in Hakyll's feeds tutorial.
Once your site is ready, add and commit all changes (except
_cache
, _site
, and other Haskell ignored files):$ git add --all
$ git commit -m "Configure Hakyll"
You can now push the changes or wait until CircleCI is configured:$ git push origin hakyll
Configure CircleCI
To configure CircleCI, follow your GitHub repository, add a user key to the SSH keys in your project's settings, and make sure it's selected by default.Now, create a
circle.yml
file and add your configuration:- Add a GHC version to the machine configuration:
Or:machine: ghc: version: 7.8.4
machine: ghc: version: 7.10.1
- Override the dependencies section to install dependencies and configure the package:
dependencies: override: - cabal update - cabal sandbox init - cabal install --only-dependencies -j - cabal configure
- Override the test section to simply build the package:
If building succeeds, CircleCI should initialize and update thetest: override: - cabal build
_site
submodule, and switch to themaster
(orgh-pages
) branch there. Adittionally, it should generate your site:
post: - git submodule init - git submodule update - cd _site/ && git checkout master - cabal run build
- Add a deployment section to update your site every time you push to the
hakyll
branch. First, push all changes in_site
tomaster
using the current date and time as reference in the commit message. Also, add[ci skip]
to make CircleCI skip buildingmaster
:
Second, update the submodule in thedeployment: production: branch: hakyll commands: - git config --global user.email circleci@circleci - git config --global user.name CircleCI - cd _site/ && git status - cd _site/ && git add --all - cd _site/ && git commit -m "Update (`date '+%F %T %Z'`) [ci skip]" - cd _site/ && git push origin master
hakyll
branch. A Git submodule is a static reference to a specific commit in a repository. In this case, thehakyll
branch has a reference to a commit in themaster
branch. Since themaster
branch was just updated, the reference inhakyll
must be updated to point to the latest commit. CircleCI should just add_site
and push. Again, add[ci skip]
to the commit message to avoid building everything again. For more information about Git submodules, see the reference or Nicola Paolucci's Git submodules.
- git status - git add _site/ - git commit -m "Update _site (`date '+%F %T %Z'`) [ci skip]" - git push origin hakyll
- If you want to use your time zone with the
date
command, add it to the machine configuration:
Or directly to themachine: ... timezone: America/Guayaquil
date
command:
TZ=America/Guayaquil date '+%F %T %Z'
$ git add circle.yml
$ git commit -m "Configure CircleCI"
$ git push origin hakyll
Once CircleCI is done building your site, you're done. Go to http://username.github.io.Notes
I think Hakyll is an excellent static site generator. The examples and tutorials make it even better. And it's Haskell. However, there are some things that don't work immediately which are worth mentioning:Comments
By default, there are no comments in a Hakyll blog. There are several examples of sites proudly generated by Hakyll that use services such as Disqus, which is good enough for me.Drafts
By default, Hakyll has no way to work with drafts. But you can configure your site to do so. For detailed information about one way to do it, see Drafts in Hakyll by Jorge Israel Peña.Since Hakyll sites can be used with Git and GitHub, my favorite solution for drafts is simply creating a separate branch and using a pull request for each post. You can preview your site, but it'll only include the draft if you merge it to the
hakyll
branch.from https://www.stackbuilders.com/news/dr-hakyll-create-a-github-page-with-hakyll-and-circleci
--------------
using-docker-and-circleci-with-hakyll
Juan Pedro Villa published a great article (Dr. Hakyll: Create a GitHub page with Hakyll and CircleCI) explaining how to use circleci to provide continuous deliver for a hakyll site.
However, I ran into some trouble with circleci. My builds kept timing out or I’d get a cabal build error. So I figured I should take advantage of circleci’s docker support.
I started off with a simple docker image that has every thing I need to build the site.
FROM rdesfo/stack:latest
Maintainer Ryan Desfosses <ryan@desfo.org>
RUN stack setup --compiler ghc-7.10.3
RUN stack install --resolver lts-6.25 hakyll
Now that I have the docker image I can use the same git repo that I
setup following Juan outlined in his article. The only difference I ran
into was that I had to add a -f
to the submodule command since I had added _site
to my .gitignore
file.git submodule add -f https://github.com/rdesfo/hakyll-test.git _site
docker exec
.machine:
services:
- docker
dependencies:
override:
- docker pull rdesfo/hakyll
test:
override:
- docker run -d --name hakyll -i rdesfo/hakyll bash
- docker cp . hakyll:/home/user/app/
- docker exec -u root hakyll chown -R user:user /home/user/app
- docker exec -u user hakyll sh -c "cd /home/user/app; stack build; stack exec -- site build"
docker exec
with the following lxc-attach
. - sudo lxc-attach -n "$(docker inspect --format "{{.Id}}" hakyll)" -- bash -c "chown -R user:user /home/user/app"
- sudo lxc-attach -n "$(docker inspect --format "{{.Id}}" hakyll)" -- su user - bash -c "export LANG='C.UTF-8'; cd /home/user/app; stack build; stack exec -- site build"
The full circleci yaml file can be found here.from http://desfo.org/posts/2016-10-25-using-docker-and-circleci-with-hakyll.html
No comments:
Post a Comment