4 ms·

Publishing Simple Books with Jekyll

75 points by bradley_taunt 7y ago

jtbayly 7y ago
While I would love to see a decent Jekyll workflow to work with books, this is not it. The output looks nice enough, but there aren't even links from the table of contents to the chapters. Neither in the HTML nor the PDF version. Nor does it say what page number to find the chapter on in the PDF. Additionally, as mentioned in the "cons" section of the article, "Chapters are spit out as one long, single page." This includes the PDF, where there aren't even page breaks at the start of new chapters. This is no way to publish a book. Even a simple one. Does anybody have a Jekyll theme or workflow that actually works well with books?
- chrisanthropic 7y ago
  I haven't touched the code in a couple of years, but I wrote something combining Jekyll, Pandoc, and custom LaTeX templates for publishing my wife's novels (ebook and print). Someone found it and posted about it here in 2017: https://news.ycombinator.com/item?id=14482828 https://news.ycombinator.com/item?id=14482828
- geraldbauer 7y ago
  Good points. I'm the author of the simple book theme. For more book theme alternatives see the https://github.com/bookdesigns https://github.com/bookdesigns repo that includes a jekyll copy of the "famous" (old/classic) gitbook style (see http://bookdesigns.github.io/book-git http://bookdesigns.github.io/book-git ). Another project I started a while ago is called octobook that lets you - surprise, surprise - use jekyll for (online) books, see https://github.com/octobook https://github.com/octobook and https://github.com/geraldb/talks/blob/master/octobook.md https://github.com/geraldb/talks/blob/master/octobook.md Anyways, you're right all book themes still a work-in-progress.
cosmic_quanta 7y ago
This is an interesting use of static site generators. If you are interested in the (Markdown content -> publishable format) pipeline, take a look at Pandoc. Ultimately this is more developer-oriented however.
- themodelplumber 7y ago
  I recently published a simple book using Markdown and Pandoc. It went OK but I think next time I'll try ASCIIDoc due to what I recall as "extra features which would have been nice."
  - asicsp 7y ago
    I use markdown to pdf flow with pandoc+xelatex. Found a few tex code on stackexchange sites and current setting is good enough for me, made a blog post too [1] There's also a latex template I've bookmarked [2] - I haven't tried yet, but sample on the repo looks nice [1] https://learnbyexample.github.io/tutorial/ebook-generation/customizing-pandoc/ https://learnbyexample.github.io/tutorial/ebook-generation/c... [2] https://github.com/Wandmalfarbe/pandoc-latex-template https://github.com/Wandmalfarbe/pandoc-latex-template
- Tarq0n 7y ago
  https://bookdown.org/ https://bookdown.org/ is an r implementation of this toolchain that's been used to make some great looking books.
  - amrrs 7y ago
    Bookdown is amazing. Makes it possible to publish a book. https://blog.datascienceheroes.com/how-to-self-publish-a-book/ https://blog.datascienceheroes.com/how-to-self-publish-a-boo...
  - suyash 7y ago
    I've been looking to write an interactive book - think of Apple Books but in HTML and this tool seems to do the job, only thing is that I don't know any R.
- eslaught 7y ago
  Pandoc is definitely the way to go in terms of ease of writing and the quality of the output. It's not super difficult to take Jekyll-ish input and generate books from it either, e.g. I built a tool to do this: https://bitbucket.org/elliottslaughter/bookmd https://bitbucket.org/elliottslaughter/bookmd Example of a book I published with this approach: https://www.amazon.com/dp/0692553916 https://www.amazon.com/dp/0692553916 (a fairly challenging type setting problem with lots of footnotes, foreign language, etc.) The main gotchas are that if you really want it to look good you have to dig into the Latex template, so ultimately it would take more effort to make it push-button for non-technical users.
miguelmota 7y ago
Gitbook is another good tool for generating e-book formats (PDF, epub, mobi) from markdown. I’ve used it for a guide book and it’s been good.
- deleted 7y ago
  [deleted]
sgallant 7y ago
Great article
jdsampayo 7y ago
One more "cons" can be hyphens, for a comfortable reading a book is normally justified text with hyphenation. Not sure if wkhtmltopdf will respect that
nurettin 7y ago
I tried something similar to this the first time I heard of wkhtmltopdf some seven or eight years ago using css to emulate an A4 size box. (it was meant as a replacement for mssql reporting server) First, 40 page reports experienced a few millimeters of sliding. It became more apparent at 60 pages. Second, I could not go above 75 dpi.
- dsr_ 7y ago
  pandoc is usually the solution.
philistine 7y ago
I have published two books so far using the most obscene of methods; I parse my own HTML into XeTeX using a mix of bash and Python. Parsing HTML is supposedly a big no-no but what’s the problem when it’s your own code? Anyway, it seems like most comment here are trying to reinvent the wheel when any variant of LaTeX is a great solution; there are never any compromises to be made with TeX.
readbeard 7y ago
You might also check out Pollen [0], a publishing system written in Racket. The creator of Pollen, Matthew Butterick, uses it to produce his own digital books—including the outstanding Practical Typography [1]. [0] https://docs.racket-lang.org/pollen/ https://docs.racket-lang.org/pollen/ [1] https://practicaltypography.com https://practicaltypography.com Edit: I see after a quick search that Pollen has already been featured on HN multiple times [2] [3], but I still think it might be helpful to reference it again here. [2] https://news.ycombinator.com/item?id=20027116 https://news.ycombinator.com/item?id=20027116 [3] https://news.ycombinator.com/item?id=15335010 https://news.ycombinator.com/item?id=15335010

75 points by bradley_taunt 7y ago

While I would love to see a decent Jekyll workflow to work with books, this is not it. The output looks nice enough, but there aren't even links from the table of contents to the chapters. Neither in the HTML nor the PDF version. Nor does it say what page number to find the chapter on in the PDF. Additionally, as mentioned in the "cons" section of the article, "Chapters are spit out as one long, single page." This includes the PDF, where there aren't even page breaks at the start of new chapters. This is no way to publish a book. Even a simple one. Does anybody have a Jekyll theme or workflow that actually works well with books?

chrisanthropic 7y ago
I haven't touched the code in a couple of years, but I wrote something combining Jekyll, Pandoc, and custom LaTeX templates for publishing my wife's novels (ebook and print). Someone found it and posted about it here in 2017: https://news.ycombinator.com/item?id=14482828 https://news.ycombinator.com/item?id=14482828
geraldbauer 7y ago
Good points. I'm the author of the simple book theme. For more book theme alternatives see the https://github.com/bookdesigns https://github.com/bookdesigns repo that includes a jekyll copy of the "famous" (old/classic) gitbook style (see http://bookdesigns.github.io/book-git http://bookdesigns.github.io/book-git ). Another project I started a while ago is called octobook that lets you - surprise, surprise - use jekyll for (online) books, see https://github.com/octobook https://github.com/octobook and https://github.com/geraldb/talks/blob/master/octobook.md https://github.com/geraldb/talks/blob/master/octobook.md Anyways, you're right all book themes still a work-in-progress.

cosmic_quanta 7y ago

This is an interesting use of static site generators. If you are interested in the (Markdown content -> publishable format) pipeline, take a look at Pandoc. Ultimately this is more developer-oriented however.

themodelplumber 7y ago
I recently published a simple book using Markdown and Pandoc. It went OK but I think next time I'll try ASCIIDoc due to what I recall as "extra features which would have been nice."
- asicsp 7y ago
  I use markdown to pdf flow with pandoc+xelatex. Found a few tex code on stackexchange sites and current setting is good enough for me, made a blog post too [1] There's also a latex template I've bookmarked [2] - I haven't tried yet, but sample on the repo looks nice [1] https://learnbyexample.github.io/tutorial/ebook-generation/customizing-pandoc/ https://learnbyexample.github.io/tutorial/ebook-generation/c... [2] https://github.com/Wandmalfarbe/pandoc-latex-template https://github.com/Wandmalfarbe/pandoc-latex-template
Tarq0n 7y ago
https://bookdown.org/ https://bookdown.org/ is an r implementation of this toolchain that's been used to make some great looking books.
- amrrs 7y ago
  Bookdown is amazing. Makes it possible to publish a book. https://blog.datascienceheroes.com/how-to-self-publish-a-book/ https://blog.datascienceheroes.com/how-to-self-publish-a-boo...
- suyash 7y ago
  I've been looking to write an interactive book - think of Apple Books but in HTML and this tool seems to do the job, only thing is that I don't know any R.
eslaught 7y ago
Pandoc is definitely the way to go in terms of ease of writing and the quality of the output. It's not super difficult to take Jekyll-ish input and generate books from it either, e.g. I built a tool to do this: https://bitbucket.org/elliottslaughter/bookmd https://bitbucket.org/elliottslaughter/bookmd Example of a book I published with this approach: https://www.amazon.com/dp/0692553916 https://www.amazon.com/dp/0692553916 (a fairly challenging type setting problem with lots of footnotes, foreign language, etc.) The main gotchas are that if you really want it to look good you have to dig into the Latex template, so ultimately it would take more effort to make it push-button for non-technical users.

miguelmota 7y ago

Gitbook is another good tool for generating e-book formats (PDF, epub, mobi) from markdown. I’ve used it for a guide book and it’s been good.

deleted 7y ago
[deleted]

sgallant 7y ago

Great article

jdsampayo 7y ago

One more "cons" can be hyphens, for a comfortable reading a book is normally justified text with hyphenation. Not sure if wkhtmltopdf will respect that

nurettin 7y ago

I tried something similar to this the first time I heard of wkhtmltopdf some seven or eight years ago using css to emulate an A4 size box. (it was meant as a replacement for mssql reporting server) First, 40 page reports experienced a few millimeters of sliding. It became more apparent at 60 pages. Second, I could not go above 75 dpi.

dsr_ 7y ago
pandoc is usually the solution.

philistine 7y ago

I have published two books so far using the most obscene of methods; I parse my own HTML into XeTeX using a mix of bash and Python. Parsing HTML is supposedly a big no-no but what’s the problem when it’s your own code? Anyway, it seems like most comment here are trying to reinvent the wheel when any variant of LaTeX is a great solution; there are never any compromises to be made with TeX.

readbeard 7y ago

You might also check out Pollen [0], a publishing system written in Racket. The creator of Pollen, Matthew Butterick, uses it to produce his own digital books—including the outstanding Practical Typography [1]. [0] https://docs.racket-lang.org/pollen/ https://docs.racket-lang.org/pollen/ [1] https://practicaltypography.com https://practicaltypography.com Edit: I see after a quick search that Pollen has already been featured on HN multiple times [2] [3], but I still think it might be helpful to reference it again here. [2] https://news.ycombinator.com/item?id=20027116 https://news.ycombinator.com/item?id=20027116 [3] https://news.ycombinator.com/item?id=15335010 https://news.ycombinator.com/item?id=15335010