Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I wrote a couple of books in asciidoc. MD might work for a web comment but if you want to write something sophisticated like a book you need more. E.g.

TIP: my tip

Super helpful when you're writing a book. My blog provider uses MD and I no longer have these handy popups or cool sidebars. I won't even get into tables etc.

Include is a bit problematic but having a way to have 1 chapter = 1 file is wonderful. You can then package the whole book with a file that lists the includes. Very convenient.



I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say. Here is the output (in pdf, epub, html) for you to judge [2]

[1] https://github.com/alessandrocucci/book-template

[2] https://turnoverbook.com/


How did you do code callouts? Admonitions etc.?

From my experience you need to use custom syntax for those which means tooling doesn't work well. (grammar, spelling, style etc.).

O'Reilly and Manning standardized on asciidoc.


For extending markdown capabilities, there are many plugins/filters. Example [1].

I remember using extensions/filters for citations, etc.

Ultimately it is just some custom tooling around pandoc; so whatever you can do in pandoc, you can get done in the book.

[1] - https://github.com/chdemko/pandoc-latex-admonition

[2] - https://pandoc.org/




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: