Now available: PureScript: Jordan's Reference via an `mdbook` website

PureScript: Jordan’s Reference, an in-depth beginner-oriented guide to learning PureScript from foundations-up.

This change comes with the following advantages:

  • you can now search the entire project
  • you can easily navigate around the content via the ToC and via left/right arrows
  • it comes in multiple themes

Various limitations:

  • Since PureScript doesn’t have a syntax highlighter via highlight.js, I’ve switched the highlighting language to haskell. It gets you 90% but some things still won’t be highlighted correctly
  • Folders are still nested at various points. This won’t change, so that people who have git cloned it locally can still follow along in their own copy of the code
  • Due to the nesting folders issue above, the sidebar’s ToC should be extended horizontally. It makes it easier to see where in the nesting you are.

Things I haven’t figured out:

  • How can I limit the problems that arise when making breaking changes (e.g. rename/delete a file)? For example, a reader gets half-way through reading Foo.html and then sleeps. I delete the file and make a new release. The reader wakes up, and suddenly finds that Foo.html leads to a 404, not a page.
  • Should this have it’s own domain name? I’d prefer not to maintain another thing.
19 Likes

It’s definitely much more readable and I also very much like the structure. It’s much more inviting to read now. You did a great thing here.

I think it’s good like this without it’s own domain name. Though I believe you can use a custom domain name for a github site.

1 Like

I think I’ll leave it without a custom domain name for now. But, that might get changed in the future.

How are the files generated? I think it would be very cool to have syntax highligh. I have been using syntax highlight on my PureScript GraphQL Docsify. Maybe I can help :slight_smile: Unfortunately, mdbook seems to be using Highlight.js, which does not support PureScript. Prism on the other hand has just added support for PureScript: https://github.com/PrismJS/prism/pull/2526

1 Like

mdbook uses highlight.js. If we added PureScript to their list, it would fix that. I don’t believe there’s a way to override mdbook's highlighter to use something else like Prism.

FWIW there’s also https://github.com/purescript-contrib/atom-language-purescript, which provides the syntax highlighting definitions which power VS Code and PureScript syntax highlighting on GitHub.

Ah, I guess that doesn’t actually help you very much, because it seems like highlightjs expects you to specify your grammar in a different way to the way it’s done in atom-language-purescript.

Yeah… Unfortunately, not. Thanks for the idea though.

Unfortunately, highlight.js is no longer allowing new languages to be added. (see Mint’s attempt and policy discussion).

We could merge purescript support with mdbook's version of the file though.

Looks like we could easily override the highlight.js file they use.

So, this could be done if one kept a fork of highlight.js that included PS as a language.

That’s exactly what was done for the halogen mdbook. But I just made purs another alias for haskell so we didn’t have to change all the existing code fence tags.

return{name:"Haskell",aliases:["hs","purs","purescript"]