9 ms·

The Web Book Boilerplate - Writing books for almost every platform

118 points by PascalPrecht 14y ago

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.

bjcubsfan 14y ago
This looks interesting. Is there an example of a book published with this?
- PascalPrecht 14y ago
  No, not yet.
- PascalPrecht 14y ago
  But you can find a little demo right here: https://github.com/PascalPrecht/wbb#demo https://github.com/PascalPrecht/wbb#demo
mahmoudimus 14y ago
Hmm, besides using pandoc for conversion, how does this break down against Sphinx (http://sphinx-doc.org http://sphinx-doc.org)?
- PascalPrecht 14y ago
  Have to take a look at it, thanks! :)
thesteg 14y ago
We need a demo/example :)
- PascalPrecht 14y ago
  There's now a link to a demo: https://github.com/PascalPrecht/wbb#demo https://github.com/PascalPrecht/wbb#demo An adaption of Scott Chacon's Pro Git
PascalPrecht 14y ago
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 :)
- afeezaziz 14y ago
  Yes, I agree with you, is there any alternative to this book 'boilerplate'?
rickhanlonii 14y ago
I'm really interested in this, and it would really sell me on using it if there was a demo provided.
- PascalPrecht 14y ago
  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 https://github.com/PascalPrecht/wbb/wiki
  - asimjalis 14y ago
    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?
  - asimjalis 14y ago
    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.
  - feralmoan 14y ago
    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'
  - nbashaw 14y ago
    I think people want to see what the generated HYML looks like
  - nbashaw 14y ago
    I want to see what the generated HTML looks like
asimjalis 14y ago
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?
- PascalPrecht 14y ago
  Interesting! I will have a look at these cases. Didn't thought of syntax inconsistency
spatten 14y ago
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 http://kramdown.rubyforge.org/syntax.html [2]: https://leanpub.com/help/manual https://leanpub.com/help/manual
- PascalPrecht 14y ago
  Whoa! Thank you very much! :) Will take a look at it later this eve!
danso 14y ago
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 http://ruby.bastardsbook.com and http://photography.bastardsbook.com 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.
jamesbritt 14y ago
I'm working on a set of self-published E-books (http://justthebestparts.com 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.
- martininmelb 14y ago
  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.
- anonymouz 14y ago
  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.
  - TylerE 14y ago
    ConTeXt is probably even better if you're doing lots of layouts and inline figures, sidebars, etc.
    - jamesbritt 14y ago
      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.
luigi 14y ago
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
- PascalPrecht 14y ago
  You're totally right! And that's exactly what's planned for future versions :)
martininmelb 14y ago
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.
__mharrison__ 14y ago
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).
- scottfr 14y ago
  You certainly can create high quality printable PDF's. Check out this example: https://dl.dropbox.com/u/94002/postmortem/docs/EmeryRoe/out/article.pdf 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.
tspike 14y ago
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 http://github.com/tspike/wbb-demo for source or http://tspike.github.com/wbb-demo http://tspike.github.com/wbb-demo for HTML Thanks for making this tool! It's very timely for me.
- PascalPrecht 14y ago
  Thank YOU for trying it out! Much appreciated!
PascalPrecht 14y ago
Thank you very much for your feedback! Much appreciated!

118 points by PascalPrecht 14y ago

bjcubsfan 14y ago

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

PascalPrecht 14y ago
No, not yet.
PascalPrecht 14y ago
But you can find a little demo right here: https://github.com/PascalPrecht/wbb#demo https://github.com/PascalPrecht/wbb#demo

mahmoudimus 14y ago

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

PascalPrecht 14y ago
Have to take a look at it, thanks! :)

thesteg 14y ago

We need a demo/example :)

PascalPrecht 14y ago
There's now a link to a demo: https://github.com/PascalPrecht/wbb#demo https://github.com/PascalPrecht/wbb#demo An adaption of Scott Chacon's Pro Git

PascalPrecht 14y ago

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 :)

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

rickhanlonii 14y ago

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

PascalPrecht 14y ago
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 https://github.com/PascalPrecht/wbb/wiki
- asimjalis 14y ago
  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?
- asimjalis 14y ago
  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.
- feralmoan 14y ago
  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'
- nbashaw 14y ago
  I think people want to see what the generated HYML looks like
- nbashaw 14y ago
  I want to see what the generated HTML looks like

asimjalis 14y ago

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?

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

spatten 14y ago

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 http://kramdown.rubyforge.org/syntax.html [2]: https://leanpub.com/help/manual https://leanpub.com/help/manual

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

danso 14y ago

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 http://ruby.bastardsbook.com and http://photography.bastardsbook.com 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.

jamesbritt 14y ago

I'm working on a set of self-published E-books (http://justthebestparts.com 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.

martininmelb 14y ago
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.
anonymouz 14y ago
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.
- TylerE 14y ago
  ConTeXt is probably even better if you're doing lots of layouts and inline figures, sidebars, etc.
  - jamesbritt 14y ago
    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.

luigi 14y ago

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

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

martininmelb 14y ago

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.

__mharrison__ 14y ago

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).

scottfr 14y ago
You certainly can create high quality printable PDF's. Check out this example: https://dl.dropbox.com/u/94002/postmortem/docs/EmeryRoe/out/article.pdf 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.

tspike 14y ago

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 http://github.com/tspike/wbb-demo for source or http://tspike.github.com/wbb-demo http://tspike.github.com/wbb-demo for HTML Thanks for making this tool! It's very timely for me.

PascalPrecht 14y ago
Thank YOU for trying it out! Much appreciated!

PascalPrecht 14y ago

Thank you very much for your feedback! Much appreciated!