
Show HN: GitBook – Build beautiful programming books using GitHub and Markdown - AaronO
http://www.gitbook.io/
======
andrzejkrzywda
As someone who has just recently started writing programming books [1] I'm
really excited to see more such tools!

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/](http://rails-refactoring.com/)

[2]
[http://literatureandlatte.com/scrivener.php](http://literatureandlatte.com/scrivener.php)

[3] [http://getdpd.com/](http://getdpd.com/)

~~~
jamesbritt
I also stated off writing a book using Markdown in Vim and was pretty happy at
first. One of my goals was to have a Web site that mirrored the book content
([http://osc.justthebestparts.com](http://osc.justthebestparts.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.

~~~
bowerbird
pagination and breaks can be problematic in e-books, especially in conjunction
with illustrations/captions.

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

~~~
jamesbritt
_but one shouldn 't need to move stuff to indesign, as most e-book viewer-apps
support css "page-break" now._

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.

~~~
bowerbird
jamesbritt said:

> getting the PDF just right was important to me.

i respect that. how were you generating the .pdf?

*

> Since the user can set the font and text size

> the idea of page size goes pretty much out the window.

what pagesize did your .pdf have? that's what i meant.

if you put each section on its own e-book screen, and make the sections small
enough to fit on one _screen,_ or two, or three, they'll also fit on one/two
_pages._

*

> Using CSS page-break doesn't quite help,

> since it presumes what has come before

> and how it fit on the page.

i'm not sure i understand.

so -- for the sake of others reading this thread -- let me explain further.
when you create the e-book, if you segment the book into small-enough
sections, it'll generally work, across almost all situations, no matter how
the person has configured the fontsize. so there, a "screen-break" comes
before each section, and before-and-after images you want to fill a screen.

conversely, for the .pdf, you _know_ the pagesize, and the fontsize as well,
so you know where pagebreaks are, and you add/delete/change until you get what
you want.

*

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

it would be nice if the programs had enough smarts to do this automatically;
until then, you do it manually.

but you don't need indesign to do it; you really don't.

i'd be happy to show you how i'd do your book, if you'd be interested in
seeing it, if you send me a copy of it.

*

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

that is the approach that is needed these days, yes.

-bowerbird

~~~
jamesbritt
I don't recall now just how I originally did the PDF, but it was some CLI tool
that read either the markdown or HTML.

 _let me explain further. when you create the e-book, if you segment the book
into small-enough sections, it 'll generally work, across almost all
situations, no matter how the person has configured the fontsize._

That's probably true enough for ebook readers (and I got good results for just
epub using my CLI tools) but once I went to InDesign for the PDF layout using
it for epub generation was no big deal and that was where I was making final
changes to the text.

 _i 'd be happy to show you how i'd do your book, if you'd be interested in
seeing it, if you send me a copy of it._

Thank you. If you (or anyone else following this thread) wants to grab it I
put up links at
[http://osc.justthebestparts.com/grab/](http://osc.justthebestparts.com/grab/)

(If you need the actual markdown files I'd have to see about packing those up.
I was writing the book as a Webby-generated site using a combination of
Markdown and ERB. I had some scripts that would then use that same generated
HTML to package it up as epub. )

It would be great if I could use command-line tools to generate the PDF while
not sacrificing the precise look and layout I want but I'm deeply skeptical
this can be done without a visual tool and manual adjustments to adjust things
for aesthetic reasons. (Or without learning LateX. :))

~~~
bowerbird
ok, that didn't take long. can't open your .epub file. it doesn't validate,
and i wonder if anyone can open it. so that's a major problem that you will
need to solve...

unzipped it to find out why, and discovered it was made with calibre. e-book
developers hate that program because it does a rewrite of the underlying .html
and .css files, creating an unholy mess that's very difficult to decipher.
personally, i won't touch a calibre file; life is too short.

aside from the .epub, the .mobi and the .pdf do just fine in getting the
content across, so even though i would likely have done them slightly
differently, what you have is fine.

still, if you really want more feedback, i can give it. but the original
markdown files would be best, concatenated so they're just one big file, with
the text running linearly.

(a book really works best with the whole thing in one file, because that
usually minimizes editorial inconsistencies while you're writing, and makes it
easier to check later. it also dampens file-clutter considerably, which is
good.)

-bowerbird

~~~
jamesbritt
_ok, that didn 't take long. can't open your .epub file. it doesn't validate,
and i wonder if anyone can open it. so that's a major problem that you will
need to solve..._

Weird. It was generated using InDesign (though I've now learned that opening
the .epub in Calibre's ebook-reader will insert a bookmarks file into the
zip).

I then used Kindlegen to turn that epub into mobi for sale on Amazon, and
Calibre to create the mobi I offer elsewhere. No one has told me they had any
trouble opening files and I've viewed them using assorted programs.

 _(a book really works best with the whole thing in one file, because that
usually minimizes editorial inconsistencies while you 're writing, and makes
it easier to check later. it also dampens file-clutter considerably, which is
good.)_

I find it easier to break things out into chapter files. Turning the chapters
into a Web site even if only hosted locally) makes it easy to navigate through
the whole thing. It works for me.

------
AaronO
Here's a cool book using GitBook : [http://samypesse.github.io/How-to-Make-a-
Computer-Operating-...](http://samypesse.github.io/How-to-Make-a-Computer-
Operating-System/)

It's written by GitBook's co-author and teaches the basics of writing an OS in
C++.

~~~
aktau
The article title is why I came, the book you mention is why I stayed. Very
interesting read, I wish more was available!

------
abengoam
Looks interesting. A little bit of feedback: \- I didn't like that the table
of contents disappeared on me when I clicked on a page. \- Related to this, it
would be great for the progress widget to show the actual name of each
page/chapter, if not all the time, at least when you hover with the mouse. \-
In the table on contents: mark in some way the links that are going to take
you away from the book and into a github view. \- The Next button feels too
big in pc. Takes away the attention from the content itself. Thank you for
your hard work!

~~~
AaronO
Thanks for the feedback. We'll look into fixing this. Keep in mind we built
GitBook in our spare time over the past 3 days.

Feel free to contribute with Pull Requests ! (the beauty of being open)

~~~
carlsednaoui
"Keep in mind we built GitBook in our spare time over the past 3 days."

That's impressive!

------
aray
Quick feedback: When I get to a "next" page, the focus must be on something
other than the core content, because spacebar doesn't scroll the page.
Clicking anywhere in the main content box makes spacebar traversal work :)

Looks neat, might be a good candidate for longer-form literature than jekyll
pages.

~~~
SamyPesse
Done
[https://github.com/GitbookIO/gitbook/commit/55d9bfbf1833376d...](https://github.com/GitbookIO/gitbook/commit/55d9bfbf1833376d4e79f436eaaf64ed6886ebc8)

~~~
gavinpc
Yeah, I wish you could do that without the focus call:
[http://stackoverflow.com/q/22046683/4525](http://stackoverflow.com/q/22046683/4525)

But what then is the point of setting tabindex?

------
terminus
Not to be pedantic or anything, but git != github.

AFAICS, none of this is about github. It's about git, the protocol, the
versioned object store and markdown, the markup layer.

~~~
AaronO
A big part of that is true. It's mostly about Git. But it is also about
GitHub, GitBook integrates well with GitHub repos, it links up your book to
the issue tracker, watchers & stars as well.

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.

------
emehrkay
Export to epub and replace the textbook industry

~~~
BHSPitMonkey
Sphinx already does ePub, PDF, and HTML. (Pair with ReadTheDocs.org for
automatic builds and hosting from a git repository).

~~~
emehrkay
I had no idea. Thanks for the info.

------
jahewson
Yet another web-based ebook viewer which _disables zoom_ on the iPad and then
has _no way to change the font size_. Sigh.

~~~
SamyPesse
Add an issue on Github
([https://github.com/GitbookIO/gitbook/issues](https://github.com/GitbookIO/gitbook/issues))
;)

------
carlsednaoui
This is incredible! Here is the repo if anyone wants to star it:
[https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook)

I will definitely use this for the CoderDojoNYC curriculum I'm building.

------
sspiff
The front page and demo's seem to be all about interactive on-screen books.
Does GitBook also do things like pretty PDF export? (Converting the HTML to
PDF does NOT count!)

------
eslaught
Cool. I built a somewhat-similar tool [1], which doesn't handle any of the
interactive examples, but generates physical books (PDFs) and ePub, etc. I'm
getting close to publishing my first "real" book with it, which should be cool
to see.

[1]:
[https://bitbucket.org/elliottslaughter/bookmd](https://bitbucket.org/elliottslaughter/bookmd)

~~~
andrey-p
This looks pretty good. It's very similar to something I built [1] to scratch
my own itch for some illustrated short stories I've been self-publishing.

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.

[1]: [https://github.com/andrey-p/apocalism-
js](https://github.com/andrey-p/apocalism-js)

~~~
eslaught
Go for it. That's why it's open source. :-)

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.

[1]: [http://johnmacfarlane.net/pandoc/](http://johnmacfarlane.net/pandoc/)

~~~
andrey-p
Hmm, that's not quite what I want in that case - I've used Pandoc before but I
want pretty strict control over the way things are converted since I use my
project to build books where layout is almost as important as the content.
That's why I went for manual pagination and page-by-page conversion with
PhantomJS rather than using Pandoc.

~~~
eslaught
Sure, and with PDFs that makes sense. But with ePub, you're going to lose a
lot of control anyway, so it's not obvious to me to what extent you can
achieve the effect you want, even with a custom tool.

------
daviding
Just as a heads-up, the font 'appNormal' looks like this on Windows / Chrome
33:

[http://i.imgur.com/mXfy7NR.jpg](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.

~~~
sqrt17
AFAIK, Chrome/Windows does not do font antialiasing/smoothing, which it does
do on Linux and OSX.

~~~
mjgoeke
More important than "smoothing" \- the font baseline is all over the place

~~~
daviding
Yep, it's the baseline. It looks even worse in IE11

[http://i.imgur.com/jWcyrz6.jpg](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.

------
raju
Not as nice as this but there is Github's git-scribe that uses AsciiDoc for
writing - [https://github.com/schacon/git-
scribe](https://github.com/schacon/git-scribe)

It hasn't seen movement lately though.

------
reiz
Cool! Good Job. I really like it. Many times the documentation for programming
projects look like grab. This project is a big help. Many Thanks1

------
bryanbraun
This kind of stuff is really cool. I've been working on something similar,
execept it's integrated with Github pages. More info here if anybody's
interested: [http://www.bryanbraun.com/2014/04/02/publishing-books-to-
git...](http://www.bryanbraun.com/2014/04/02/publishing-books-to-github-pages-
with-bitbooks)

------
munaf
This is really cool. Could be used as an interactive documentation platform
for libraries and frameworks as well.

------
pubby
Looks nice. Here's a few suggestions:

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

------
rhgraysonii
Similar concepts are found with Penflip
([http://www.penflip.com](http://www.penflip.com)) that go outside programming
but offer similar functionality, depending on the breadth of what you may want
to write on.

~~~
reillyse
I'm a big fan of penflip. Create for collaboration and got some neat features
for editing your books.

------
xpop2027
Interesting to see what @mhartl thinks about this since he recently launched
softcover.io

~~~
err4nt
Have been trying to google what this was ALL week after finding out about it
here on HN a while ago! Thanks for the mention so I can properly bookmark it
this time <3

------
JeremyMorgan
Very cool. I was just planning on writing something like this for my website,
but instead I'll devote the time to hacking this up. You may see a few pull
requests from me in the coming days!

Nice choice on Markdown, and... three days? Nice work.q

~~~
AaronO
Sure! Pull Requests are more than welcome.

I'm currently hacking up an epub export feature.

------
tnorthcutt
s/checkout/check\ out

"Checkout" is a noun. "Check out" is a verb.

~~~
hnriot
In svn "checkout" is a verb.

------
opendais
This is an awesome first implementation of a good idea. :)

If I was the type to communicate clearly enough in writing to create an open
textbook, I'd use it.

------
AbhishekBiswal
Can also be used to create documentations. Cool!

------
yong
Yeah! this is something I've always wanted. Now I can convert any github doc
to a codecademy like learning experience !

------
hhandoko
What good timing! I had just started on a tutorial project, and was thinking
of achieving the same using Jekyll + plugins.

------
jcdavison
i don't frequently get excited about randomy stuff, but when I do, its about
stuff like this.

\- 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 !

------
Smirnoff
I like "Intro to JS" book. Is it open source and available for local usage
(download)?

------
alexchamberlain
Looks great. It would be cool if the left and right keys changed the pages.

~~~
ievans
This, absolutely. I kept pressing space and the right arrow key expecting the
page to change.

------
roozbeh18
Very nice :D README.md link to gitbook.io refers to github.io :D

~~~
SamyPesse
Fixed!

------
justplay
This is one of the best thing came out this days.

------
elwell
Font is messed up on Chrome/Windows

------
desduvauchelle
Really Cool!

------
ing33k
its good.

------
teemo_cute
The title says it is intended primarily for programming books. But what if
some fiction writers discovered it and got creative? Who knows, the resulting
novel might become a work art.

~~~
AaronO
It's primarily targeted programmers. Because they are already familiar with
Git/GitHub & Markdown and we have some "unique" features for programming
tutorials/courses, such as interactive tutorials.

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.

