Render book to single file

[flip111]

Would be nice to be able to render to book into a single file (like pdf). I know i can use pandoc, but i think it could use a little more like a Contents section.

[flip111]

pandoc -t html -s -o purescript.pdf $(ls text/*.md | sort -V)

[milesfrain]

I'm hoping we could render the final output somewhat like the original book, where you have everything searchable on a single page, along with a collapseible table of contents.

[flip111]

Maybe a static html generator in that case so it can be used online and offline. Maybe a static html documentation generator would do.

https://docsify.js.org/#/ https://github.com/sourcey/spectacle https://docs.stoplight.io/documentation/download-static-html https://www.mkdocs.org/ https://docusaurus.io/

[s0kil]

What about enabling GitHub pages for the repo? Here is an example and the config that enables is.

[milesfrain]

@s0kil I'm all for easy steps that improve the current situation, and so I'd be happy to start with a github pages version for now while we continue our investigation into the available options. If you make the PR, I'll merge it.

Some missing features from the original book that I'd like to eventually see are:

• Render entire book on a single web page, this makes searching a lot easier
• Show contents on side bar
• Allow linking to sections within chapters
• Render exercise heading. Not sure why ## is supported in regular .md markdown but not in the webpage output.

[s0kil]

@milesfrain To add the functionality that you have mentioned, we could rather start off using Gitbook. This will also enable PDF export.

[milesfrain]

GitBook looks promising. Here's an example.

Some questions / concerns are:

• Do we need to update the SUMMARY.md when chapter sections change. That might become annoying.
• Still can't view entire book as a single page
• Not clear how to download book as PDF

[s0kil]

Here is what it turns out like https://daniel-sokil.gitbook.io/purescript-book/ Also PDF export requires a paid subscription, maybe free for open-source?. What is the reasoning behind single page layout? The search indexes through all pages.

[milesfrain]

Nice work! I think GitBook gets us most of the way there, but there are still some annoyances:

• Pages load kinda slow. Takes about a second for the loading bar at the top of the screen to complete. I'd expect this to be instant for cached static pages. I wonder if this is punishment for free tier users.
• Their search feature is not as good as simple browser-based search. For example searching for kind gives me all sorts of stuff that isn't kind. Adding quotes doesn't help either.

[milesfrain]

Some other GitBook concerns:

• It's more strict than markdown about escaping parenthesis and other symbols. Example.
• It doesn't like numbered list shorthand of just repeating 1.. Example.

[JordanMartinez]

What about pandoc?

[milesfrain]

I was wondering how the Rust Book configures their GitBook instance to enable one-page-view and printing. Turns out they made their own GitBook clone. I propose we explore using mdBook, and we can use the rust-book repo as a guideline on how to setup this repo along with the necessary Travis-CI job to keep it up to date.

[milesfrain]

What about pandoc?

@JordanMartinez Could you point us to an example project that uses pandoc?

[JordanMartinez]

Meaning, pandoc could be used to create a single downloadable PDF file of this entire repo. I'm guessing you could set up a Travis CI deploy hook to run such a program when you make a release build? Unfortunately, I don't know of a project that uses it already.

[s0kil]

What about sticking to something as simple as https://s0kil.github.io/purescript-book/book/ ?

• Sure we could add content navigation.
• Take advantage of browser search and export to PDF using print -> save as PDF, it turns out pretty good, Purescript Book.pdf

[milesfrain]

What about sticking to something as simple as https://s0kil.github.io/purescript-book/book/ ?

That seems to tackle most of the requirements, and I'd be happy to go with that for now.

I'm probably going to also investigate the mdbook option in the next day or so unless someone else wants to take-on that effort.

[s0kil]

Should I open a PR?

[milesfrain]

Should I open a PR?

PR looks good. Will wait a few hours for others to provide feedback before merging.

[JordanMartinez]

What else needs to be done before this issue can be closed? Are there any other chapters in the Readme that we should explicitly mention are still being updated?

[milesfrain]

To leave no stone unturned, I gave mdbook a try with a minimal config.

Here's the output: https://milesfrain.github.io/purescript-book/

I like that TOC appears in a collapsible sidebar, although more work is needed to display all section headings.

Another cool feature is that we can link code snippets in the text directly to .purs files so the book stays in sync with the code.

It also has a single-page view and handles duplicate anchors gracefully. The current sequential anchoring approach from #80 will break old links if any previous sections are added or removed. For example if: https://book.purescript.org/#108-Superclasses becomes https://book.purescript.org/#107-Superclasses Fixing this is straightforward in our custom solution, but I'm wondering if it's wiser to take advantage of the work already put into developing mdbook, rather than reinvent a custom alternative.

[s0kil]

I also would prefer going with mdbook, it seems to be a better option for long term. Also, you previously wanted to view entire book as a single page, what about now? Is it possible to style mdbook? What about PDF export?

[JordanMartinez]

Yeah, that does come with a few features that the current approach does not have:

• a dark theme
• a search bar
• each chapter exists as its own page, so one can easily navigate throughout the page via the left/right arrow keys without feeling overwhelmed with the entire book displayed in one page.
• potentially, a way to run PureScript code...?

[JordanMartinez]

Is it possible to style mdbook?

Seems like it. See https://rust-lang.github.io/mdBook/format/config.html#html-renderer-options

[s0kil]

If we continue with mdbook and a custom theme, that would be good. Let's not make it end up looking generic as most mdbook pages.

[emiel]

+1 for mdbook

[milesfrain]

Also, you previously wanted to view entire book as a single page, what about now? What about PDF export?

Yep, see the single-page view link in the previous post (also opens-up print-to-pdf dialog).

I believe #82 is the next step to move forward with mdbook. Might be part of what #34 had in-mind too.

[JordanMartinez]

Nice!

[s0kil]

@milesfrain has made good progress with mdbooks and #82 has been merged, it's a good time to close this issue.

[s0kil]

Sometimes using the mdbooks print page could cause system to run out of memory, so here is a friendlier way: chrome --headless --print-to-pdf=PureScript-Book.pdf https://book.purescript.org/print.html

[milesfrain]

Wondering if that printing note should be added to the main readme.

Feel free to file additional tasks for the other todos, such as adding a custom theme, like we had in with @s0kil's version.

Closing this issue