Publish guide as mdbook

[milesfrain]

The mdbook viewer is a bit nicer than clicking through a tree of markdown files on github. Plus it gives you a single page / print view, which makes finding stuff a lot easier.

Here's an instance hosted on my fork:
https://milesfrain.github.io/purescript-halogen/

But we'll want to host it on this repo's gh-pages site, e.g.:
https://purescript-halogen.github.io/purescript-halogen/
We might also be able to redirect from halogen.purescript.org

To transfer, you'll just need to create a new encrypted deploy key for this repo, and overwrite github_deploy_key.enc with it.
Concise instructions for that process can be found here:
https://gist.github.com/qoomon/c57b0dc866221d91704ffef25d41adcf

[milesfrain]

These are some general notes about purs syntax highlighting in mdbook. Not particular to halogen, but figured I should document it somewhere.

There are a few options to get syntax highlighting to work for purs blocks.

1. For this PR, I'm providing an overriding highlight.js theme that adds purs as a Haskell alias. Instructions for generating this file can be found in my highlight.js fork.
2. It would be less hacky to create a PureScript language that simply wraps Haskell syntax. That's what github does for their markdown highlighting with linguist. I believe subLanguage is the way to do this with highlight.js.
3. An even better solution is to write PureScript-specific highlighting rules (not sure what all the haskell differences would be), and we could even customize for repl blocks too (see python, julia, shell, etc. examples). An additional challenge of this option and the previous option is that we'd need to get mdbook to pickup a custom highlight.js, as new languages aren't allowed to be upstreamed into highlight.js core. (see Mint's attempt and policy discussion). I suspect the mdbook team would rather stick to official releases. Not sure what the story is with Prism, and if mdbook would be up for pivoting to that. In any case, this isn't a side quest I'm excited to pursue.
4. Another option that lets us ignore incorporating a custom theme/highlight.js is to simply change all purs snippets to hs:

find docs/ -exec sed -i 's/```purs/```hs/' {} \;

[JordanMartinez]

I like this, but I wonder if hosting it at halogen.purescript.org is desirable. Yes, Halogen is used by many, but doing this might make it look like core contributors favor one frontend library over others (e.g. concur, react, etc.)

[thomashoneyman]

I'm on board with adding the documentation in mdbook form for this repository; I tried following the instructions to do so but travis encrypt-file seems to think I don't have a valid Travis account and the command fails. Maybe @garyb will have more luck?

As a note, this will be a short-term-ish solution as we have some plans to put together a nicely-designed documentation site from the documentation which includes more information on Halogen -- kind of like the React docs site.

[thomashoneyman]

@milesfrain I've added a deploy key and I believe everything's good to go. When the build completes I'll merge to master and we can take it from there wrt ensuring it's working properly and any design improvements.

[thomashoneyman]

The generated site is available now:
https://purescript-halogen.github.io/purescript-halogen

Thanks @milesfrain! I've also updated links -- some still point at the docs folder, but the main links point to the docs site.