3 ms·
This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> h
by dardeaup 11mo ago
This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?
- codybontecou 11mo agoWhat about markdown do you feel limits you in your writing process? The beauty of markdown is that it’s standardized. If you find your self midway through the book and feel a need to change formats, it’s easy enough to parse and reformat.
- macintux 11mo agoYou might look at DocBook. I haven't used it in ~25 years, and then only for short documents, and it is XML hence quite verbose. But it's explicitly targeted at technical documentation. If nothing else, searching for DocBook alternatives might give you some ideas.
- dardeaup 11mo agoThanks!
- WA 11mo agoYou need: - table of contents - automatic chapter and section numbering - cross references and automatic tracking of figures, tables etc. - different styles besides blockquotes such as info sections, warnings, tips Imho, cross-referencing chapters, pages, figures, tables and the lack thereof in Markdown is the first and most important thing to check how you would like this to be solved.
- ldng 11mo agoHow about markdown -> PDF (with Typst) -> epub/mobi ?
- dardeaup 11mo agoThanks! I'll look into that as an option.
- tedggh 11mo agoMy stack is Markdown-Pandora-MiKTeX-PDF with Eisvogel for technical documentation and it works great for my use case. Eisvogel has a “book” typeset.
- autogn0me 11mo agoAsciidoc
- deleted 11mo ago[deleted]
- meonkeys 11mo agoI wouldn't use Markdown for that. You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech. I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: https://adammonsen.com/post/2122/ https://adammonsen.com/post/2122/ Most of the formats came out satisfactory, but there were some gotchas. https://github.com/meonkeys/shb/#%EF%B8%8F-book-formats https://github.com/meonkeys/shb/#%EF%B8%8F-book-formats lists some, and https://github.com/meonkeys/shb/blob/main/issues.adoc https://github.com/meonkeys/shb/blob/main/issues.adoc has more. Translating from English to German went OK with asciidoc, but it might have been better with docbook and standard translation tools for working with .po files. Here are two examples where the author used Markdown and the result was beautiful and successful (although layout for printed editions were done with extra/other tooling): http://gameprogrammingpatterns.com http://gameprogrammingpatterns.com , http://www.craftinginterpreters.com http://www.craftinginterpreters.com . I'm curious if Bob would/will use Markdown for his next book. My process is different than Bob's... I didn't need literate code and I didn't want to do _any_ layout/pre/post-processing, even for print. Asciidoctor worked for this, although there were some compromises (see my links above). Print-ready layout is a lot of work, however you do it. Is this your first book? Do you have a publisher? Will it be printed on paper? Do you have a developmental editor / proofreader / etc? Do you have a plan for what you'll do after you publish e.g. talks/promos/tour? Contact me if you want to chat. I'm happy to share my war stories. And good luck!