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

Question

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.

jjice · Accepted Answer

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.

sylvain_kerkour · Answer

Hey,I've wrote a few books (https://kerkour.com/books) with only markdown, https://excalidraw.com and https://figma.comI've detailed my complete setup and shared the Dockerfile that I use to convert the markdown into ebooks (EPUB, PDF and Kindle) on my blog: https://kerkour.com/book-self-publishing-pandoc

ThePhysicist · Answer

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/

softwaredoug · Answer

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.

crimsoncastle · Answer

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.

tizio13 · Answer

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

condwanaland · Answer

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.

lurn_mor · Answer

If you're coming from MD to HTML/CSS version, I'd recommend reviewing my CSS snippets for print from web tips, and it'll help with formatting and (more importantly) page breaks in your final PDF: http://www.undr.com/understatement/2020/the_one_where_we_beg...

mark_l_watson · Answer

I like leanpub.com, I have written several books on the platform.

juliangmp · Answer

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.

billconan · Answer

I'm currently doing it using pandochttps://komsciguy.com/misc/write-a-programming-book-with-mar...

beezoo · Answer

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.

Symbiote · Answer

Asciidoc (using Asciidoctor) has several book-like things built in compared to Markdown.https://asciidoctor.org/

deadcoder0904 · Answer

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.

chewz · Answer

Typora.. https://typora.io/And keep each chapter as separate file&hellip;

thangalin · Answer

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

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

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.

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

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.

If you're coming from MD to HTML/CSS version, I'd recommend reviewing my CSS snippets for print from web tips, and it'll help with formatting and (more importantly) page breaks in your final PDF: http://www.undr.com/understatement/2020/the_one_where_we_beg...

I like leanpub.com, I have written several books on the platform.

I'm currently doing it using pandoc
https://komsciguy.com/misc/write-a-programming-book-with-mar...

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.

Asciidoc (using Asciidoctor) has several book-like things built in compared to Markdown.
https://asciidoctor.org/

Typora.. https://typora.io/
And keep each chapter as separate file…

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

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.

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

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.

If you're coming from MD to HTML/CSS version, I'd recommend reviewing my CSS snippets for print from web tips, and it'll help with formatting and (more importantly) page breaks in your final PDF: http://www.undr.com/understatement/2020/the_one_where_we_beg...

I like leanpub.com, I have written several books on the platform.

I'm currently doing it using pandochttps://komsciguy.com/misc/write-a-programming-book-with-mar...

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.

Asciidoc (using Asciidoctor) has several book-like things built in compared to Markdown.https://asciidoctor.org/

Typora.. https://typora.io/And keep each chapter as separate file…

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.

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

I'm currently doing it using pandoc
https://komsciguy.com/misc/write-a-programming-book-with-mar...

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.

Asciidoc (using Asciidoctor) has several book-like things built in compared to Markdown.
https://asciidoctor.org/

Typora.. https://typora.io/
And keep each chapter as separate file…