The Web Book Boilerplate - Writing books for almost every platform | Hacker News Reader

The Web Book Boilerplate - Writing books for almost every platform

github.com

118 pointsPascalPrecht35 comments

I've started to build boilerplate to make writing books for different platforms easier. It sits on top of grunt.js and pandoc to make different file formats (.rtf, .mobi, .epub) possible. It also helps for the publishing process on leanpub.com.

Open articleView on HN

This looks interesting. Is there an example of a book published with this?

But you can find a little demo right here: https://github.com/PascalPrecht/wbb#demo

No, not yet.

We need a demo/example :)

There's now a link to a demo: https://github.com/PascalPrecht/wbb#demo

An adaption of Scott Chacon's Pro Git

Hmm, besides using pandoc for conversion, how does this break down against Sphinx (http://sphinx-doc.org)?

Have to take a look at it, thanks! :)

I'm working on a set of self-published E-books (http://justthebestparts.com).

Among my goals was to be able to publish to the Web while writing and have the option for public comments. I also wanted to write the books using Markdown or Textile.

I ended up writing some tools to convert the generated (X)HTML to epub and mobi, and the results are pretty good. However, I also want to have a PDF version and I've yet to find an automated tool that does a good job. I'm deeply skeptical that any tool can take HTML and output nicely formated PDF with proper page breaks, image handling, no dangling sentences or paragraphs, no distracting rivers of white-space in the text, etc.

I'll give this a shot but I'm not sure if there's a better solution than periodically hand-crafting the PDF.

If you're interested in creating a PDF from Markdown, I would suggest that you look at Pandoc (used by wbb). It generates LaTeX from the Markdown and generates a PDF from the LaTeX. I've yet to play with it to see if LaTeX metacommands can be placed in the Markdown.

I don't know what your requirements for the handling of images and layout are, but LaTeX does a pretty good job with the type-setting.

If you don't do anything to complicated in your HTML or Markdown, it might be worth trying to generate a LaTeX file and generating the PDF from that.

ConTeXt is probably even better if you're doing lots of layouts and inline figures, sidebars, etc.

Thanks, this looks interesting.

Since I'm also doing epub/mobi there are some limits on how clever I can be, so my PDF needs are not all that sophisticated.

I'm really interested in this, and it would really sell me on using it if there was a demo provided.

But what should the demo provide? wbb generates html, mobi, epub or rtf files from your markdown. I don't really can demonstrate that. But you can just clone it and run 'grunt wbb:publish' and you'll see a generated book in all formats :).

Checkout the wiki: https://github.com/PascalPrecht/wbb/wiki

How about a book generated from the wiki markdown? I think for people who haven't written a book before, there's a conceptual gap where it would be handy to see visually 'if you write this markdown, this is the book that gets generated'

I guess the issue is that once you get beyond core markdown there are variations. Pandoc and LeanPub use different ways to indicate code highlighting and tables. There might be other variations as well. A demo would show me how to use these features in a portable way.

I think a demo would be useful if it provided examples of how to format tables, and code, and lists. For example, suppose I want to have a code block that is Ruby and another code block that is Objective-C. How would I do this in wbb?

I want to see what the generated HTML looks like

Just take a look at Addy Osmani's

http://addyosmani.github.com/backbone-fundamentals/

I think people want to see what the generated HYML looks like

Hey, co-founder of Leanpub here.

If you're interested in the differences between Pandoc and Leanpub, there are two places to look. Leanpub is based off of Kramdown, so there's the Kramdown documentation[1]. We have made a few extensions to Kramdown to support things that books need, so you'll also want to look at the Leanpub manual[2].

If you have any questions, send us an email at hello@leanpub.com.

Looks like an exciting project. I'll take a look.

[1]: http://kramdown.rubyforge.org/syntax.html [2]: https://leanpub.com/help/manual

Whoa! Thank you very much! :) Will take a look at it later this eve!

This may get buried, but I took a stab at creating a first draft of a demo by adapting Scott Chacon's Pro Git to WBB's directory structure.

It's not working for all output formats (and images are missing and there's no stylesheet, etc) but I'm hoping to invite collaboration by just throwing it up there:

http://github.com/tspike/wbb-demo for source or http://tspike.github.com/wbb-demo for HTML

Thanks for making this tool! It's very timely for me.

Thank YOU for trying it out! Much appreciated!

Lightweight markup languages are not powerful enough to create pdf's suitable for printing.

PDF/dead tree is a still a huge platform. Dealing with front/back matter is the 20% end of the solution that no one wants to deal with ;(

Disclaimer - I've written multiple ebooks (which are relatively easy, though older kindle/mobi7 has quite a few warts), yet still have big demand for print. I've yet to see one source to rule them all. (Personally use rST and tools around it).

You certainly can create high quality printable PDF's.

Check out this example:

https://dl.dropbox.com/u/94002/postmortem/docs/EmeryRoe/out/...

This was generated using Markdown run through Pandoc (which the OP is using) which was configured to target a LaTeX template which then converts to a very nicely formatted PDF.

The key to moving from Markdown to PDF is to have a nice LaTeX template to format the content generated from Markdown.

This looks like a product that I could use. I tried installing it - and found it easy enough to install Kindlegen. When I got to the 'npm install' part, I discovered that I had to install Node.js (at least I assume I did). I then tried running it and found that Grunt was not installed. Maybe update the installation instructions.

To me a "Web Book" should take advantage of some HTML5 features in order to get some of the benefits of the richer Kindle/iBooks experience:

* Offline in-browser reading using AppCache

* Highlighting, bookmarks, notes, last place read using localStorage or indexedDB and then synced to the server when online

You're totally right! And that's exactly what's planned for future versions :)

I'm currently writing a book. I think it'll take a while til it's online, but I've often thought about a boilerplate where I can just start to write a book and don't have to care about all the other formats.

So, no.. unfortunately there's no demo :( Just try it out :)

Yes, I agree with you, is there any alternative to this book 'boilerplate'?

Question: LeanPub and Pandoc have some differences in markdown. This is because LeanPub uses Kramdown not Pandoc. For example they use different syntax for code highlighting and for defining tables. Does Wbb handle these differences in a portable way?

Interesting! I will have a look at these cases. Didn't thought of syntax inconsistency

Thank you very much for your feedback! Much appreciated!

This looks interesting but as others have mentioned, I would also like to see an HTML version in action.

I've self published two draft books, one using a custom-rails setup and the other using the Octopress/Jekyll platform (http://ruby.bastardsbook.com and http://photography.bastardsbook.com)...but they are only books in name only...However, I think moving them over to Markdown won't be too much of a problem.

But my main concern is how to turn a list of markdown files into a decent website without too much hassle. For example, I would like the code snippets to "live" on github (or in an external directory) and pulled only into the page templates where specified by the publishing-script. Octopress handles this pretty nicely with its liquid tags. I haven't worked it out yet but I think it can't be too hard to design a rake task that compiles the Octopress site and delivers the Markdown to leanpub as specified...I'm eagerly waiting for Octopress 2.1 to come out.

Reply on news.ycombinator.com