
GitBook: A modern publishing toolchain - lobo_tuerto
https://www.gitbook.com/
======
aidanhs
This is pretty interesting. For the book I'm co-authoring at the moment[0] I
ended up putting together my own toolchain, including:

1\. A dead-simple web IDE for asciidoc with live preview[1]

2\. A script for checking for common AsciiDoc mistakes (e.g. an unterminated
table will mess up all text following it).

3\. A script which enforces the house style.

4\. A makefile which runs docker (of course) to build the book with Manning
styling.

5\. A buildbot configuration on my server to run 2, 3 and 4 above on `git
push` and move the generated pdf and docx into a directory served by nginx.

Though it may seem like a lot, this investment has been totally worth it - the
ability to push a change and be viewing the updated pdf in ~1 minute is very
liberating. I can't imagine what it'd be like to not have this kind of thing
in place. I can share some more of the above if there's interest.

If you're ever thinking of writing a book yourself, I'd highly recommend
making the investment into a process like the above (or a tool like GitBook,
though I've never tried it and it seems to be more than just a build tool) so
you can get the boring stuff out of the way and focus on what you want to be
doing - writing.

[0] [http://docker-in-practice.github.io/](http://docker-in-
practice.github.io/) [1]
[https://github.com/aidanhs/AsciiDocIde](https://github.com/aidanhs/AsciiDocIde)

~~~
bambax
Very interesting, thanks for sharing. Can this toolchain produce epubs/kindles
too?

~~~
aidanhs
At present it uses asciidoctor[1] to go from asciidoc to docbook, then to
.docx via pandoc[2] and .pdf via a Manning-provided tool (for styling
reasons).

pandoc is pretty incredible. As you can see from its page, it can produce
epubs and many other things - it's likely that with pandoc and a docbook file
you can build a pipeline to take you wherever you need. For your purposes,
you'd probably go from EPUB to kindle with KindleGen.

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

------
AaronO
Hi I'm Aaron, one of the GitBook co-founders checking in.

You are giving great feedback and I'm more than happy to answer any questions
you have.

BTW, in case some of you missed it, we're a big believer in open-source, in
fact our book format and toolchain is open:
[https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook)

This allows us to build better publishing tools together, no vendor lock-in
and developers can build plugins to extend GitBook's features, here's a few:
[http://plugins.gitbook.com/](http://plugins.gitbook.com/).

------
captn3m0
I'm using gitbook to write a book currently (so I'm biased), but its an
excellent platform for writers (especially those familiar with git). My best
bits:

\- Most of the product is open-source, which means I can tinker with their
publishing platform.

\- Version control

\- Markdown support

\- Mailing lists for readers (so you can send email updates)

\- Support for donations and selling (I'm not using it, though)

\- A traffic email sent every week

\- Builds are pretty fast

\- They even offer an educational discount on the pro plans if you ask nicely.

A few issues I've faced:

\- The traffic stats are not realistic. It counts page loads, which are down
by a factor of 2-3 as per my google analytics. Also, the country demographics
are very clearly wrong (unless there is a readership of my book in Philippines
that I don't know of)

\- Landing page customization. They do have a few options, but I'd like more
options

If there is someone who has tried both softcover.io (by Michael Hartl) and
gitbook, I'd like to hear their thoughts.

------
bkanber
Really interesting idea. I think this has the potential to grow into a real
publishing platform, but also think that their name might hurt them. "GitBook"
is very techie, and the name and the git-geared UX might be a hurdle towards
moving past early adopters.

~~~
patcon
Also, my experience with Gittip when I was working with them, was that when
listening to technical people explain it to non-techies people, having "Git"
in the name works against you -- your best early proselytizers, the geeks,
misunderstand the project's scope and goals due to the git-based reference
point, and so explain it to new people as if it's a tech-centric thing. ie. It
misinforms the same technical people who you're hoping will be spreading the
word first, and they spread that misinformation to non-technical people,
possibly discouraging them from investigating "that technical platform for
geeks"

~~~
Zuider
From the perspective of a non technical person the name 'GitBook' has even
worse implications.

'Git' is a common insult in British English (being short for 'whore's get',
i.e. an illegitimate child born to a prostitute). This may possibly reflect
some private humor on Linus Torvald's part, since Git is putatively the 'son
of a Bit[ch]keeper'. The term is used to indicate someone foolish and
obnoxious. A non programmer unfamiliar with version control would hear
something like 'AssholeBook'.

------
netheril96
Does this support inlined math formulas? This feature is very important,
especially for a lot of technical writers. If it is present, then advertise it
on the front page.

~~~
AaronO
Yes, it supports inlined math formulas, through Mathjax (and KaTeX). It the
upcoming 2.0.0 release, we actually render mathjax formulas to SVGs & PNGs so
that they are visible in PDFs/EPUBs/Mobi.

Here's a very math intensive book for example:
[https://www.gitbook.com/book/jandeleeuw/bras/details](https://www.gitbook.com/book/jandeleeuw/bras/details)

~~~
avaku
FYI: Citations \cite{} don't work in this example book

------
transfire
Pricing model doesn't make a lot of sense to me. Just charge royalties for
books sold. Why charge per month at all? If worried about many people starting
books and never publishing then a small annual free should be enough to weed
those out.

~~~
tjradcliffe
> Just charge royalties for books sold. Why charge per month at all?

Because almost all independently published books sells almost no copies, so
there would be no revenue stream. The lack of sales is not a knock at indie
publishing: there are plenty of reasons to publish a book other than making
money. But it makes it difficult for services to make money off of them unless
their incremental costs are negligible.

From an author's perspective, the monthly charge seems problematic. Why pay
someone a per-month charge for a book that you wrote last year? Much simpler
and cheaper in the long run to generate an e-book using Sigil or similar, and
put it up on Amazon for free.

I'm a lousy judge of business models but the intersection of people who would
use a service called <em>git</em>-anything and people who aren't tech savvy
enough to generate their own e-books or PDFs seems very small. Sigil in
particular makes e-book creation trivial.

Comments here suggest people are using the service and pleased with it, but it
seems very expensive for a relatively small increment in convenience.

------
jklinger410
>A modern, publishing toolchain, simply taking you from ideas to finished,
polished books.

This commas here don't work in my opinion. Bad start for a book site.

"A modern publishing toolchain. Simply taking you from ideas to finished,
polished books."

"A modern publishing toolchain that simply takes you from ideas, to finished,
polished books."

"A modern publishing toolchain simply taking you from ideas, to finished,
polished books."

Any of those would be better.

~~~
danellis
Also, the example they chose for their front page is full of errors: "Setup
the development environment" and "How boot works?" as headings.

------
primitivesuave
I've been using GitBook since the early days, and it has improved
significantly in a relatively short amount of time. The web-based book editor
is phenomenal, and it is perfect for creating documentation and lesson plans
for students. I've been pointing every teacher I meet toward organizing and
sharing their written material with markdown on GitBook.

------
tempodox
Nice idea, but I'm getting so sick of seeing just-another-signup-form again
and again and again...

Instead of offering the next useless service I would be better off performing
myself, someone really should fix sign-ups (i.e. making them obsolete). That
would really be progress for a change.

As for authoring, you could also use a decent SCM instead of git for
versioning your texts. After all, the workflow model of git is hand-optimized
for open-source software development which has nothing to do with book
authoring. You would be better off with a centralized repository in typical
cases. But git is all the rage now, no matter whether it's actually the right
tool. Maybe someone ought to remind the kids that SCM is larger than git,
regardless of what fashion dictates.

------
axx
I think they should add two things:

\- Add "Reader" Accounts, so people can add Books to their collection etc.

\- Add "Download All Formats" Link for public Books. Many People have
different Devices and it might be handy to download all Formats at once.

------
georgecalm
I really like the the simplicity of the plugin system. Adding (Ka)TeX support,
for example, was just a matter of few clicks. Creating plugins looks straight-
forward too; you can extend the site or filter / decorate text. This makes me
want to use GitBook. If they don't support an idea I know I'd be able to write
a plugin for it. And with time and their steady growth I probably wouldn't
even have to. Sure, it's very new and has bugs, but I think this has a lot of
potential.

------
srinivasupadhya
GoCD moved its user & developer docs to GitBook. user docs:
[http://www.go.cd/documentation/user/current/](http://www.go.cd/documentation/user/current/)
dev docs:
[http://www.go.cd/documentation/developer/](http://www.go.cd/documentation/developer/)
and its been great so far!

The best feature by far is fast & accurate search.

------
geerlingguy
I'm surprised there hasn't been much mention of LeanPub here; in addition to
GitBook, it has what I would consider a decent modern publishing toolchain
that gets out of the way for most types of writing.

I've been writing/publishing Ansible for DevOps over the past year now, and
LeanPub is the ideal platform for me to both write/author the book (though I
just edit Markdown in Sublime and sync through Dropbox—you can use GitHub if
you'd like as well) and to publish and sell the book.

I've used GitBook a little bit, but not enough to give a really good
comparison to LeanPub. But both are so much better than the old 'build your
own bespoke system' or Microsoft Word-based workflow!

------
emehrkay
You ever have an idea, play it out in your head, plan it a little, build a
little towards it, and just not get anywhere with it and then someone release
gitbook.com? Great stuff, after Apple released ibooks author a few years ago
the gears started to turn in my head about a simplified publishing platform. I
guess I didn't move faster/further with the idea because it eventually just
felt like a blog or website authoring tool.

Was the editor pictured on this site available to download a few months back?
I feel like I played with it, or something similar.

~~~
AaronO
Hi, Aaron from GitBook here.

Thanks for the kind words! Yep, you might have seen the editor:
[https://www.gitbook.com/editor](https://www.gitbook.com/editor) (the older
version is on GitHub:
[https://github.com/GitbookIO/editor](https://github.com/GitbookIO/editor))

I think the publishing/documentation/writing industries have yet to see the
benefits of automation and better tooling. Writing should be simple and
accessible.

What we're trying to do is automate all the painful/boring parts so that
writers can focus on what they do best: writing.

I'm not surprised you had the same idea :) If you want to share your thoughts
or talk, you can email me at: aaron AT gitbook DOT com

And if you want to contribute to GitBook, our book format and toolchain is
open source:
[https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook)

------
kriro
This is indeed interesting and something I thought about recently on the
train. I dabble in fiction writing and was thinking about trying a kickstarter
of sorts at the end of the year. One of the key things I wanted to offer was
making the writing process as transparent as possible. My initial thought
didn't go much beyound..."well github repo would be a start". This seems like
just the thing I could use. Bookmarked and added to my Trello card for the
project :)

------
avaku
20% royalty is really large

~~~
rdsnsca
Then tell us the name of a publisher that takes less.

Bet there isn't one, the next would be a tie between Apple and Amazon at 30 %.

~~~
sufflo2
If they publish to those places, then I think this is 20% on top of the
publisher's 30% though? So that's 50% of your revenue.

Please correct me if I'm missing something.

------
mrmondo
This looks really lovely - I've recently been editing / providing feedback on
Gene Kim's upcoming book and we've been using a combination of O' Reilys new
platform 'chimera' and a GitHub private repo - but this looks to be better
suited to the process.

------
alphaBetaGamma
Would this be a good fit for a book with lots of pictures, where the design,
placement of pictures, and flow of text around them is important?

I just started writing a short book like that with Scribus.

------
atmosx
Anyone tried to write a non-english book using gitbook?

~~~
AaronO
GitBook co-founder here. We have a lot of non-english books actually:
[https://www.gitbook.com/explore](https://www.gitbook.com/explore), over a
thousand in chinese alone.

In the upcoming 2.0.0 release, we've further improved internationalisation:
[https://github.com/GitbookIO/gitbook/tree/master/theme/i18n](https://github.com/GitbookIO/gitbook/tree/master/theme/i18n)
We automatically detect your book's language (or you can specify itself) and
so then the build chain can automatically use translations for menu entries
etc ... if available in your language.

~~~
progman
Will Hebrew also be supported? With vowel points?

I could simulate such letters with icons but I wonder if they look acceptable
on different devices (iOS, kindle etc.)

------
taivare
I have a short book < under 50 pages , files are currently OpenOffice,full-
justified ,doc files.. is it possible to import these into gitbook ?

------
bambax
> _Books on GitBook are written using a beautiful editor and publish using Git
> or GitHub._

=> publishED?

------
treve
This makes me want to write a book!

------
Centreal
We have a serious problem for research and development at scale is at hostage
of centralized publishers.

Gitchain
([https://news.ycombinator.com/item?id=7758608](https://news.ycombinator.com/item?id=7758608))
is the first and only proof system that can establish reliable intellectual
property management and history logs.

Literacy reading and writing through Github, Authorea, Penflip, Gitbook all
share the same liability without clear federation.

------
picks_at_nits
> You guys are giving great feedback

My feedback is, "Avoid making needless assumptions about gender.”

:-)

p.s. Thank you!

~~~
Jun8
Many people use _you guys_ not as a plural of _guy_ , i.e. a male person, but
closer to the sense of the Southern _y 'all_, an all inclusive mode of
address. Wikipedia lists is under you cognates as "Used regardless of the
genders of those referred to"
([http://en.wikipedia.org/wiki/You](http://en.wikipedia.org/wiki/You)). In
Britain it seems _you lot_ has similar usage. The gender neutrality seems to
be well-established in common usage, e.g. see the top answer answer to this
ESE questions and the comments
([http://english.stackexchange.com/questions/11816/is-guy-
gend...](http://english.stackexchange.com/questions/11816/is-guy-gender-
neutral)).

We should understand that languages change, certain idioms and usages which
were a bit objectionable in the past may change in meaning and vice versa. I
think _you guys_ represent the former.

It may hurt gender-based sensibilities of some but many languages have build
in defaults that use the masculine form, a well-known example is French where
(from [http://en.wikipedia.org/wiki/Gender-specific_and_gender-
neut...](http://en.wikipedia.org/wiki/Gender-specific_and_gender-
neutral_pronouns)):

In French: Vos amis sont arrivés — ils étaient en avance ("Your friends have
arrived – they were early"). Here the masculine plural pronoun ils is used
rather than the feminine elles, unless it is known that all the friends in
question are female (in which case the noun would also change to amies and the
past participle would change to arrivées).

I am always a bit surprised by the emphasis put on gender neutral language,
esp. in the US, it is usually pointed that this is sexist and may lead to many
of the gender imbalances. Yet other languages where this is is even more
prevalent does not seem to place that much emphasis, e.g. French
([http://french.stackexchange.com/questions/836/given-the-
lack...](http://french.stackexchange.com/questions/836/given-the-lack-of-a-
gender-neutral-pronoun-in-french-how-should-one-refer-to-so)). I do not speak
French, my question to native speakers is: are there similar efforts in French
to rid the language of sexism? According to Wikipedia L’Académie française
does not quite support such movements
([http://en.wikipedia.org/wiki/Gender_neutrality_in_languages_...](http://en.wikipedia.org/wiki/Gender_neutrality_in_languages_with_grammatical_gender#French)).

~~~
picks_at_nits
I used to feel the way you do, that “guys” is gender-neutral. However, I have
encountered a large number of women who appear to be unaware that they are
included when people say “you guys,” and they feel dismissed.

I could lecture them about how wrong they are, but I could also use phrases
that are not subject to misunderstanding.

Things like this remind me of code. If I write something that is compiler-
correct, but subject to misunderstanding, I could demand that people who find
it confusing go read a few more books. Or I could write it to be read by my
audience.

With code, we’ve nearly universally decided that we write to be understood,
and that the audience for our code is more important than whether we are
“compiler correct.”

JM2C, but that’s how I feel about the word “guys” being gender-neutral. It is
dictionary-correct, but not audience-correct.

~~~
tomjen3
That is probably the best argument for it, but what alternative is there for a
audience-correct gender neutral guys? Do we really have to borrow yeall?

~~~
cstross
What's wrong with "people"?

As in, "you people"?

(Grammatically correct, non-colloquial, non-regional, and gender neutral.)

~~~
Jun8
The phrase _you people_ is generally understood to have racial tones, e.g.
[http://mashable.com/2012/07/19/ann-romney-you-
people/](http://mashable.com/2012/07/19/ann-romney-you-people/) or
[http://www.huffingtonpost.com/derek-penwell/why-you-may-
be-a...](http://www.huffingtonpost.com/derek-penwell/why-you-may-be-a-racist-
e_b_6280776.html).

~~~
cstross
Planet Earth calling: if that's so, it's a specifically regional -- i.e.
American -- thing. (I'm in Scotland, where it definitely doesn't.)

