Some thoughts:
1. Code examples are the biggest problem to me in the tools that I tried. There's many little things about them, that need to look right - line numbers, display on kindle, line breaks
2. At the beginning, I've used Git and vim for writing in Markdown. However, at some point I realised that I wasn't efficient - I switched to Scrivener [2] and dropped the idea of using Git. In my case, it made me much more productive.
3. Writing an ebook is different than writing code. You probably don't need much of the history.
4. Research is for me the biggest part of writing, experimenting with different ideas, collecting code samples. It's good to have a proper tool to support it. In my case, Scrivener [2] was a huge improvement.
5. I use a combination of Scrivener, Leanpub, Dropbox and getdpd [3] for the whole project. Scrivener for research and notes organisation, Leanpub for generating the result files (PDF, mobi, epub), Dropbox for syncing those two. Getdpd for the selling part.
[1] http://rails-refactoring.com/
(I learned a lot about writing Markdown-to-epub+Web-site tools as well :))
But my book had numerous illustrations and occasionally lengthy code samples. What worked fine on a Web page did not play out so nice in a naive conversion to mobi/epub/PDF.
I ended up waiting until all content was basically done and then using InDesign to set the layout (primarily for PDF but it helped with the epub export as well). The biggest issue was making sure that breaks occurred in a sensible way. (I took a look at Scrivener and it just wasn't right for me. But I encourage people to try it out.)
I'm all for more tools that make it easier for people to focus on content over the nuts-and-bolts of production but one really needs to be sure that the tools are producing the results you want, and that's going to vary with the type of content.
but one shouldn't need to move stuff to indesign, as most e-book viewer-apps support css "page-break" now.
another good tip is to create small chapters/sections, recognition that screens tend to be smaller than pages.
-bowerbird
If I were only targeting epub/mobi I wouldn't have bothered with InDesign, but getting the PDF just right was important to me.
nother good tip is to create small chapters/sections, recognition that screens tend to be smaller than pages.
Since the user can set the font and text size the idea of page size goes pretty much out the window.
Using CSS page-break doesn't quite help, since it presumes what has come before and how it fit on the page. What's needed is orphan/widow control and "keep with next" so that, for examples, related sections can be rendered on one page or the next but not split across pages.
In practice, though, I found I needed to aim for some sort of highest common factor across popular devices, keep test-viewing the results, and drop anything too clever.
It's resulted in a huge gain in productivity, in terms of both managing the content and the code samples and keeping everything nice and consistent. (That last item can become difficult, much quicker than I originally anticipated.)
It's wonderful to see more tools cropping up in this area; there's most definitely a need for them!
FWIW, Scrivener has limited markdown support that let me bring in the code blocks and terms that are formatted in the Scrivener editing window. But getting text formatted as code to compile properly to various versions (PDF, epub, mobi, etc.) took some work -- specfically I had to freeze the formatting for every block and term. It was a pain, but the final product turned out well.
The only other thing I would like to add is I wish there were a way to get the Scrivener manuscript back into markdown and Git, for future revisions. Anyone have ideas on how to handle that?
As for Leanpub:
1. Last time I checked, they didn't let me take the customer emails and use outside of Leanpub. I find it a very important limitation to the way I do the marketing - via my mailing list. In practice, my readers are more Leanpub customers, not mine. I want to build long-term relationship with my readers, to deliver more value to them, even after they bought my book. To be fair - Leanpub has their own tool for sending emails, I haven't tried that. I'm happy enough with MailChimp, not to see reasons to switch.
2. From the tools I researched, Leanpub is the best when it comes to PDF/mobi/epub generation. It takes a while to learn their process but it was worth it.
3. I'm really grateful that Leanpub allows the process I'm doing - generate the files using their tools, but selling on another site.
Overall, the tools you're choosing should fit your whole process of researching, writing, marketing, selling.
Feel free to contribute with Pull Requests ! (the beauty of being open)
That's impressive!
nice work. you went in with a clear head. congratulations.
i will watch your further development.
-bowerbird
http://i.imgur.com/mXfy7NR.jpg
Looks great on OSX etc, so as this is about beautiful books wanted to say. Hope that helps, and good luck with the idea - looks really interesting.
http://i.imgur.com/jWcyrz6.jpg
Normally comments like mine can be a bit pedantic, but in this case it's the front page of something that 'builds beautiful programming books', so I think relevant.
cheers
I needed some more fine-grained control over page layout so I did go down a completely different route for generating PDFs - I do manual pagination and render the PDF pages using PhantomJS - but generating ePubs is something I've been wanting to do for a while.
Hope you don't mind me looking through your code to see how you've handled ePubs.
For BookMD, I use Pandoc [1], which is the most versatile Markdown generator in existence. Pandoc has out-of-the-box support for ePub, so I just use that.
The part where more customization is needed is if you want page breaks. For PDF output, Pandoc lets you use Latex directives in your Markdown (\newpage, etc.), so that should work fine. For ePub, I'm not actually sure what you would do, or whether you would even want the same sort of pagination.
Looks neat, might be a good candidate for longer-form literature than jekyll pages.
But what then is the point of setting tabindex?
"Checkout" is a noun. "Check out" is a verb.
It's written by GitBook's co-author and teaches the basics of writing an OS in C++.
AFAICS, none of this is about github. It's about git, the protocol, the versioned object store and markdown, the markup layer.
Plus it's easy to host the HTML output of your books on GitHub thanks to their brilliantly simple gh-pages service.
So that's why GitBook is also about GitHub.
Nice choice on Markdown, and... three days? Nice work.q
I'm currently hacking up an epub export feature.
But you're totally correct, gitbook could and should be applied to many other kinds of writers. Markdown is a nice input format, and as soon as GitBook supports epub & pdf, other writers could use it for "production" quality books.
I will definitely use this for the CoderDojoNYC curriculum I'm building.
It hasn't seen movement lately though.
- The green "finished" bar on the last page should behave as a button. Take me back to the ToC.
- The section/chapter number should be displayed on every page.
- Not a fan of the green progress bar being animated. I think it makes the page loading seem slower than it is.
If I was the type to communicate clearly enough in writing to create an open textbook, I'd use it.
- why does your tweet button not mention you guys on twitter ? i'm like, hey I want to start the 'mention train'... but i don't know who to mention ? you could start by mentioning @railstutor ... just sayin !
