Migrating to hakyll

Sequence of commands that worked for me

sudo apt remove hakyll-dev
stack upgrade
stack install hakyll
hakyll-init open-notebook-wjd
cd open-notebook-wjd/
stack init
stack build
stack exec site build
stack exec site watch
mv about.rst about.markdown
stack build
stack exec site clean
stack exec site build
stack exec site watch
git init
# create .gitignore file
git checkout -b develop
git add .
git commit -m "initial commit"
git remote add origin [email protected]:williamdemeo/open-notebook-wjd.git
git fetch --all
git checkout -b master
cp -a _site/. .
git add -A
git commit -m "Publish"
git push origin master:master
git checkout develop
git branch -D master

OLD STUFF

Install/Upgrade Haskell on Ubuntu 18.04

According to https://www.haskell.org/platform/linux.html this is done with the following command:

sudo apt-get install haskell-platform

Install/Upgrade stack

curl -sSL https://get.haskellstack.org/ | sh

I get the response that stack is already installed, so I did

stack upgrade

Since stack is installed in $HOME/.local/bin, I added that to my PATH. Actually, I added it to my $HOME/.bash_profile file where my PATH gets set, and then did source ~/.bash_profile.

...so far so good...

UPDATE: Actually, that was a mistake. Make sure the new upgraded version of stack is at the front of PATH so we don't inadvertently use an older version of stack (e.g., the one in /usr/bin/stack). To put the new stack at the front of the path, do the following:

export PATH=~/.local/bin:$PATH

Install/Upgrade Hakyll

Use the command stack install hakyll. This should work fine, assuming you're using the updated version of stack.

Host site with github pages

Reference for this section: https://jaspervdj.be/hakyll/tutorials/github-pages-tutorial.html

LOCAL SETUP

Create a new Hakyll project with stack

stack new opennotebook-wjd hakyll-template

Change to the newly created directory and make sure there's a file called .gitignore with lots of stuff in it.

cd opennotebook-wjd
cat .gitignore

Mine has the following:

# Created by https://www.gitignore.io/api/haskell

### Haskell ###
dist
cabal-dev
*.o
*.hi
*.chi
*.chs.h
*.dyn_o
*.dyn_hi
.hpc
.hsenv
.cabal-sandbox/
cabal.sandbox.config
*.prof
*.aux
*.hp
.stack-work/
_cache/
_site/

Setup the local repository with a development branch called develop.

cd opennotebook-wjd
git init
git checkout -b develop
git add .
git commit -m "initial commit."
git remote add origin <URL to the remote GitHub pages repository>

Build a clean version of the site and fetch all branches.

git checkout develop
ghc --make site.hs
stack exec site clean
stack exec site build
git fetch --all

Switch to master branch and overwrite files with the ones in _site and commit and push.

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
cp -a _site/. .
git add -A
git commit -m "Publish."
git push origin master:master
```

Final clean up and return to the original state.

git checkout develop
git branch -D master
git stash pop

Summary

Here's a summary of the above workflow for automating deployment of a hakyll site to Github pages (see also: https://jaspervdj.be/hakyll/tutorials/github-pages-tutorial.html)

A deployCommand can be set as part of Hakyll's configuration options. More information and an example is provided here.

# create a new opennotebook
stack new opennotebook-wjd hakyll-template

# initialize git repo for opennotebook files and create a develop branch
cd opennotebook-wjd/
git init
git checkout -b develop
git add .
git commit -m "initial commit"

# At github.com, create a new remote repository for opennotebook (use the + icon)
# (copy the address of the remote git repository)

# Link local git repo to remote
git remote add origin [email protected]:williamdemeo/opennotebook-wjd.git

# build the opennotebook 
ghc --make site.hs
stack exec site clean
stack exec site build

# create a master branch and copy files from _site to the main opennotebook directory
git fetch --all
git checkout -b master
cp -a _site/. .

# commit the changes and push to remote repository
git add -A
git commit -m "Publish"
git push origin master:master

# configure remote repository
# go github.com/your-repo-name web page and scroll down to Github Pages section
# choose the master branch

# Get back to development state
git checkout develop
git branch -D master

Appendix: Errors and Troubleshooting

I tried to install hakyll using stack but I got the following error:

Downloaded lts-12.0 build plan.    
AesonException "Error in $.packages.cassava.constraints.flags['bytestring--lt-0_10_4']: Invalid flag name: \"bytestring--lt-0_10_4\""

after invoking the command stack install hakyll.

Not surprisingly, there's a problem. (In my experience, any install that involves a Haskell flavored package manager like cabal or stack will fail on the first try... Haskell never fails to fail.)

Next I tried

sudo apt update -y
sudo apt install libghc-hakyll-dev

which seemed to finish without errors.

Next, I installed the hakyll doc library with sudo apt install libghc-hakyll-doc.

Creating the website

Reference for this section: http://alanduncan.me/2014/02/08/migrating-from-octopress-to-hakyll/

Next I created my static site as follows:

Create a basic site (template) by invoking the command: hakyll-init my-great-site which responds with the following output:

 Creating my-great-site/images/haskell-logo.png
 Creating my-great-site/posts/2015-12-07-tu-quoque.markdown
 Creating my-great-site/posts/2015-11-28-carpe-diem.markdown
 Creating my-great-site/posts/2015-08-12-spqr.markdown
 Creating my-great-site/posts/2015-10-07-rosa-rosa-rosam.markdown
 Creating my-great-site/site.hs
 Creating my-great-site/contact.markdown
 Creating my-great-site/index.html
 Creating my-great-site/css/default.css
 Creating my-great-site/about.rst
 Creating my-great-site/templates/default.html
 Creating my-great-site/templates/archive.html
 Creating my-great-site/templates/post-list.html
 Creating my-great-site/templates/post.html
 Creating my-great-site/my-great-site.cabal

Configure the site with the command ghc --make site.hs which responds with the output
```
  [1 of 1] Compiling Main             ( site.hs, site.o )
  Linking site ...
```
Preview the site by invoking ./site watch and navigating your browser to localhost:8000.

Errors caused by old versions of stack and/or cabal

It turns out the error

Downloaded lts-12.0 build plan.    
AesonException "Error in $.packages.cassava.constraints.flags['bytestring--lt-0_10_4']: Invalid flag name: \"bytestring--lt-0_10_4\""

occurred because I had an older version of stack in my path (namely, at /usr/bin/stack). The stack upgrade command puts the upgraded version of stack in the ~/.local/bin directory. So we can either try to uninstall the stack that exists in /usr/bin or we can simply make sure ~/.local/bin appears first in our PATH. I chose the latter and invoked:

export PATH=~/.local/bin:$PATH

Then did stack upgrade

williamdemeo/hakyll.md