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

Announcements
#1

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.
20 Likes
#2

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.

2 Likes
#3

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

#4

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
#5

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.

#6

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.

#7

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.

#8

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

#9

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.

#10

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.

#11

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"]