HN Explorer

Ask HN: What's the best way to write a book in Markdown?

27 points by JSLegendDev ↗ HN
What are the best available tools to use if I want to write a book in markdown and export it as a pdf primarly?

It needs to handle displaying code well as I want to write a technical book.

25 comments

[ 2.7 ms ] story [ 66.9 ms ] thread
mark_l_watson
I like leanpub.com, I have written several books on the platform.
mooreds
I would vote for leanpub too because it has additional features that are important for any successful book.

* you can easily charge money

* they have support for marketing your book (mostly buying spots in their newsletter)

* you can change what you charge over time (so you can charge less when starting, and gauge interest in your book)

* you can collect email addresses of people who have bought your book and notify them of new chapters

Sure, they take some money, but it's a great platform not just for writing a book, but marketing and selling one.

tizio13
Obsidian for sure. You can export the pdf with the same styling you see on screen.

You can also use it to make your book a knowledge base.

Check out their docs for an example of what can be achieved.

https://docs.obsidian.md/Home

joshxyz
up for this. i use this quite often.
Slow_Hand
I like Obsidian and use it everyday, but I wouldn't consider it the best option for writing something as large and complicated as a book.

Books are huge undertakings that require a lot of data management and formatting specifications. I don't think Obsidian is particularly well suited to this task, based on what I've experienced.

First, Obsidian's .pdf export/formatting features are nearly non-existent. I struggle to print 4 page documents that are enjoyable to read. Formatting their book as a .pdf will get very tedious very quickly if anything other than the most basic, raw, formatting is needed.

While I love typing in Markdown for notes, Obsidian has almost no native features to help you format long form work. Perhaps there are plugins that grant these features, but I'm not aware of them.

jjice
Sorry for the SO like answer, but id recommend not thinking very hard about PDF compilation of you're writing in markdown, for now.

I've done something similar but I burnt so much time on configuring Pandoc, citations, formulas, and a compilation process, instead of writing the actual book. If you're writing in Markdown, most of this process for you can be done at the end too.

With that said, Pandoc has been great. Gotta dive into some configuration to get things how you want for the finalized PDF, but it's great.

schwartzworld
Seems like it would be easy enough to generate html and then "print to PDF" from a web browser.
jjice
It is! I don't think it comes out looking as good as one would want and I think going directly to PDF or EPub would look better, but it's definitely an option.
condwanaland
I use Quarto with .qmd files. I use the plugin for VS Code but you can also do the rendering straight through the command line. Absolutely love it, didn't need to configure much, it just worked out of the box.
crimsoncastle
I was using Typora, but now I use Zettlr. It's free for every desktop platform and open source. You can even search multiple files in your directory from a sidebar while you type, it provides writing stats, has file tagging, exports to anything Pandoc supported, and it also has code highlighting. Zettlr is so good. I'm pretty sure it's what you are looking for.
throwaway154
Seconding Zettlr. It also handles citations smoothly with a linked .bib file. The sidebar (a sidebar, there's more than one) also does directory tree structure like your favourite code editor too.
juliangmp
I like writing markdown docs with mdbook, though I've never used it for something to be printed physically so I dont know how good/bad PDFs or epubs would come out.

What I like about it is that its easily extendable. You can write preprocessors to give yourself new features or an entire backend/renderer to render the book differently. I've written a very simple one myself.

ThePhysicist
I use Weasyprint [1] to generate a PDF from HTML, and I use a self-written static site generator based on Python & Jinja2 to convert Markdown to HTML first [2] (note: that code is undocumented and only used by me). Weasyprint can handle code highlighting e.g. using Pygments or another static framework, the only downside is it can't execute JS so if you e.g. want to dynamically generate content to render like SVGs you need to first pass your HTML through a headless browser, which is also possible though. There's also paged.js [3] which is similar but runs in the browser, so it supports JS-generated content out of the box. And as others have mentioned Pandoc [4] is the Swiss army knife of converting between document formats.

1: https://weasyprint.org/ 2: https://github.com/adewes/beam-up 3: https://pagedjs.org/ 4: https://pandoc.org/

deadcoder0904
it is extremely complicated when it shouldn't be. maybe someday someone will make a saas to solve this problem once & forever.

i've wrote custom code for it that i'll share maybe 1 day but not yet.

what i did was use markdown with node.js & wrote a script that all chapters are read from it.

it looks like this:

_book/ chapter1/ pic1.jpg index.md chapter2/ . . . chapter100/

and then it uses princexml with 100 loc of css to output a beautiful pdf.

this should definitely be a saas though. it has massive potential.

beezoo
I wrote my thesis using Bookdown, an RMarkdown package. It might be useful if you require e.g. Latex notation rendering.

My pipeline went via a custom latex template which unlocks all the formatting power of latex without having to deal with it for the content.

softwaredoug
I have found that for the needs of typesetting, citations, and other typically more "advanced" needs Markdown is not quite enough.

I recently contributed several chapters to a book. Years ago I wrote a book in MS Word. But this time around we used AsciiDoc. RestructuredText is another option.

I used MS Code's AsciiDoc support, and it worked generally great.

thangalin
My Typesetting Markdown series[1] describes crafting shell scripts to cobble together pandoc, knitr, math, ConTeXt, and YAML-based interpolated variables to produce PDF files.

For my sci-fi novel, my character sheet was inside of a spreadsheet. It dawned on me that the character sheet could be replaced with a YAML file and integrated with a Markdown editor. I developed KeenWrite[2] to replace the scripts while allowing me to use interpolated variables and R inside of the prose.

My novel has two separate timelines and I wanted to make sure that dates lined up correctly without having to do the date math manually. I implemented a number date functions in R[3] based around an "anchor" date. As long as all my other dates are relative (in days) to the anchor date, all the math checks out. Possessives and pronouns are also handled in R (meaning I can change a character's gender by changing a single variable, provided I haven't referenced any sex-specific body parts or characteristics).

Also, I wanted a nice-looking PDF file to send to alpha readers (still looking, see profile). For that, I crafted KeenWrite Themes[4] along with a video tutorial series showing how all the software components work together.

On the technical side, Markdown lacks a standard syntax for citations and cross-references. I've written about this at length.[6] If flexmark-java were to get support, then it would help resolve a long-standing issue with KeenWrite.[7]

[1]: https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow...

[2]: https://keenwrite.com/

[3]: https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/R/conver...

[4]: https://gitlab.com/DaveJarvis/keenwrite-themes/

[5]: https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9...

[6]: https://talk.commonmark.org/t/cross-references-and-citations...

[7]: https://gitlab.com/DaveJarvis/KeenWrite/-/issues/145