5 ms·

Write a Book with Markdown

33 points by vincent_s 3y ago

ggm 3y ago
Pandoc is really amazing. Sometimes, it makes me re-re-re-re learn how to drive latex/tex config to e.g. make a .sty file work, but aside from that I haven't had to worry HOW it made the PDF for almost everything I do. (I use arev.sty to get bitstream/mono fonts and make some things look a bit more microsoft-y) Haskell had a significant "win" for me there: real world code I depend on, written in an FP language. I do sometimes wish I could make tables which were less "TeX-y" -which is running a bit counter to the style/vibe but I do miss more boring tables a la TBL/Troff I currently live in org mode in emacs and use various org mode exports to get things which I like better through pandoc, but pandoc direct from org mode isn't bad. I haven't yet had to do indexing, or bib. indexing is really hard. Well.. there's simple but time consuming (multi pass) and there's hard (what you index) and there's re-indexing to suit the pagination of the form you render. I did Kindle direct print for a real author from word inputs and it was a journey. When you find yourself hunting for guides to GSM weights of paper to calculate your thickness to position the spine to define the ISBN region... Cut marks are another bugbear. It should be easier to just tell something (pdf stage?) to insert/intrude cross hairs at the cutmark points you want.
yawnxyz 3y ago
I'm having great luck using PagedJS taking Markdown > HTML > CSS-styled HTML > Printed formats. PagedJS is super easy to style (once you've figured it out...) and you can output all kinds of stuff. I use it to format and print hundreds of pages for abstract books.
rpigab 3y ago
I have a wierd urge to add Gitlab CI to this so that any tagged commit creates a release containing all assets (PDF, ePub, HTML), and a manual job on any commit does the same without a release (stored in Gitlab Generic Package Registry or job artifacts), and the HTML version is built and deployed to the repository's Gitlab Pages on all master pipelines. I know it's of little use since you usually install all dependencies on a dev machine and simply run fast scripts locally, but Gitlab CI is really a nice tool to use, and you've got some free build minutes you can use on the Saas instance. Then you can make edits on any machine using the Web IDE, and easily share the result hosed on Gitlab pages.
- Leo_Germond 3y ago
  I've been using pandoc + rst + beamer for producing very large (1000's) training slide decks, and pdf2latex is so slow that using a CI to generate the 10's of decks configurations in parallel makes for a very valid use case, so I implemented just that... I don't know what I'm getting at with this little story of mine, but if you actually scratch that urge at some point I'd be interested in seeing the result, especially regarding distribution, which I didn't set out to implement.
  - rpigab 3y ago
    Not sure I'll try that anytime soon, but here's what I would check out to start: https://gitlab.com/pandoc/pandoc-ci-example https://gitlab.com/pandoc/pandoc-ci-example
he1senberg 3y ago
[dead]
cryptos 3y ago
I can only recommend not to use Markdown for larger projects like books (at least not scientific or tech books). Markdown simply doesn't provide the structural elements you'd need. AsciiDoc is a much better fit.
- invalidname 3y ago
  100%. The major tech publishers (O'Reilly, Manning) use Asciidoc and for good reason. The tooling today is absolutely fantastic too. I'm writing my new book with IntelliJ IDEA and it's such a pleasant experience. My last two publishers required Word which was a nightmare. I maintain some docs in markdown which is OK but pretty limited when it comes to the advanced stuff.
- iainctduncan 3y ago
  How is asciidoc compared to sphinx? I've found sphinx really good so far.
  - invalidname 3y ago
    I'm not a Python guy so never worked with Sphinx and never really heard of anyone using it for something like a book. It looks like it suffers from the same problems that MD suffers from. Building a markup language is really easy. That's why we have so many and multiple independent implementations of markdown. The problem is that last mile to get production and mostly printing right. That's super hard and even asciidoctor doesn't get it perfectly. These Manning does use asciidoc for writing, it's great for that. But when you need to create a book they move it to docbook and then typeset using the traditional typesetting programs. Despite all the work it's 95% of the way for the sublime book experience. I'd say every other alternative is 90% of the way at best. To get a sense of what you need to do to create a professional book without that typesetting work check out this post https://medium.com/sketch-app-sources/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410 https://medium.com/sketch-app-sources/using-sketch-and-ascii...
  - MilStdJunkie 3y ago
    Asciidoc is a lightweight markup language, Sphinx is a document processor. I imagine what you're primarily asking is "how does Asciidoc compare to ReStructuredText?". ReStructuredText has a ton of functionality, but it slips behind Asciidoc in a few areas. On paper, we passed by RsT because leadership didn't like the Python-forward tooling and high setup workload . . but we had other reasons on the publications side of things: less XML interoperability, worse print options, worse tables, weirder directives, syntax inconsistencies, no established spec or working group (at the time). Being built on DocBook is a great insurance policy for Asciidoc, as DocBook has been around approximately forever and opens lots of doors to other XML specifications via XSL or something more sane.
IdiranVibe 3y ago
At this point surely LaTeX makes more sense for this kind of work...
ntnsndr 3y ago
I've written three books now with Markdown (in emacs), and I love it. The simplicity makes it very easy to focus on the content and export in diverse ways (which I find important for editing). My stack is: - Markdown mode in terminal emacs - Pandoc export with .emacs script or shell script for books with chapters in separate files - Zotero with BibLaTex to manage .bib file - Git for version control This has worked beautifully for three trade books and one academic one. The only sad part is when we shift from writing and revising to copyediting, when I have to edit the press's track changes in LibreOffice.
dibujaleojos 3y ago
Another great alternative is Quarto (https://quarto.org/ https://quarto.org/). The author mentions that BookDown requires you to install R, Quarto does not.

33 points by vincent_s 3y ago

ggm 3y ago

Pandoc is really amazing. Sometimes, it makes me re-re-re-re learn how to drive latex/tex config to e.g. make a .sty file work, but aside from that I haven't had to worry HOW it made the PDF for almost everything I do. (I use arev.sty to get bitstream/mono fonts and make some things look a bit more microsoft-y) Haskell had a significant "win" for me there: real world code I depend on, written in an FP language. I do sometimes wish I could make tables which were less "TeX-y" -which is running a bit counter to the style/vibe but I do miss more boring tables a la TBL/Troff I currently live in org mode in emacs and use various org mode exports to get things which I like better through pandoc, but pandoc direct from org mode isn't bad. I haven't yet had to do indexing, or bib. indexing is really hard. Well.. there's simple but time consuming (multi pass) and there's hard (what you index) and there's re-indexing to suit the pagination of the form you render. I did Kindle direct print for a real author from word inputs and it was a journey. When you find yourself hunting for guides to GSM weights of paper to calculate your thickness to position the spine to define the ISBN region... Cut marks are another bugbear. It should be easier to just tell something (pdf stage?) to insert/intrude cross hairs at the cutmark points you want.

yawnxyz 3y ago

I'm having great luck using PagedJS taking Markdown > HTML > CSS-styled HTML > Printed formats. PagedJS is super easy to style (once you've figured it out...) and you can output all kinds of stuff. I use it to format and print hundreds of pages for abstract books.

rpigab 3y ago

I have a wierd urge to add Gitlab CI to this so that any tagged commit creates a release containing all assets (PDF, ePub, HTML), and a manual job on any commit does the same without a release (stored in Gitlab Generic Package Registry or job artifacts), and the HTML version is built and deployed to the repository's Gitlab Pages on all master pipelines. I know it's of little use since you usually install all dependencies on a dev machine and simply run fast scripts locally, but Gitlab CI is really a nice tool to use, and you've got some free build minutes you can use on the Saas instance. Then you can make edits on any machine using the Web IDE, and easily share the result hosed on Gitlab pages.

Leo_Germond 3y ago
I've been using pandoc + rst + beamer for producing very large (1000's) training slide decks, and pdf2latex is so slow that using a CI to generate the 10's of decks configurations in parallel makes for a very valid use case, so I implemented just that... I don't know what I'm getting at with this little story of mine, but if you actually scratch that urge at some point I'd be interested in seeing the result, especially regarding distribution, which I didn't set out to implement.
- rpigab 3y ago
  Not sure I'll try that anytime soon, but here's what I would check out to start: https://gitlab.com/pandoc/pandoc-ci-example https://gitlab.com/pandoc/pandoc-ci-example

he1senberg 3y ago

[dead]

cryptos 3y ago

I can only recommend not to use Markdown for larger projects like books (at least not scientific or tech books). Markdown simply doesn't provide the structural elements you'd need. AsciiDoc is a much better fit.

invalidname 3y ago
100%. The major tech publishers (O'Reilly, Manning) use Asciidoc and for good reason. The tooling today is absolutely fantastic too. I'm writing my new book with IntelliJ IDEA and it's such a pleasant experience. My last two publishers required Word which was a nightmare. I maintain some docs in markdown which is OK but pretty limited when it comes to the advanced stuff.
iainctduncan 3y ago
How is asciidoc compared to sphinx? I've found sphinx really good so far.
- invalidname 3y ago
  I'm not a Python guy so never worked with Sphinx and never really heard of anyone using it for something like a book. It looks like it suffers from the same problems that MD suffers from. Building a markup language is really easy. That's why we have so many and multiple independent implementations of markdown. The problem is that last mile to get production and mostly printing right. That's super hard and even asciidoctor doesn't get it perfectly. These Manning does use asciidoc for writing, it's great for that. But when you need to create a book they move it to docbook and then typeset using the traditional typesetting programs. Despite all the work it's 95% of the way for the sublime book experience. I'd say every other alternative is 90% of the way at best. To get a sense of what you need to do to create a professional book without that typesetting work check out this post https://medium.com/sketch-app-sources/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410 https://medium.com/sketch-app-sources/using-sketch-and-ascii...
- MilStdJunkie 3y ago
  Asciidoc is a lightweight markup language, Sphinx is a document processor. I imagine what you're primarily asking is "how does Asciidoc compare to ReStructuredText?". ReStructuredText has a ton of functionality, but it slips behind Asciidoc in a few areas. On paper, we passed by RsT because leadership didn't like the Python-forward tooling and high setup workload . . but we had other reasons on the publications side of things: less XML interoperability, worse print options, worse tables, weirder directives, syntax inconsistencies, no established spec or working group (at the time). Being built on DocBook is a great insurance policy for Asciidoc, as DocBook has been around approximately forever and opens lots of doors to other XML specifications via XSL or something more sane.

IdiranVibe 3y ago

At this point surely LaTeX makes more sense for this kind of work...

ntnsndr 3y ago

I've written three books now with Markdown (in emacs), and I love it. The simplicity makes it very easy to focus on the content and export in diverse ways (which I find important for editing). My stack is: - Markdown mode in terminal emacs - Pandoc export with .emacs script or shell script for books with chapters in separate files - Zotero with BibLaTex to manage .bib file - Git for version control This has worked beautifully for three trade books and one academic one. The only sad part is when we shift from writing and revising to copyediting, when I have to edit the press's track changes in LibreOffice.

dibujaleojos 3y ago

Another great alternative is Quarto (https://quarto.org/ https://quarto.org/). The author mentions that BookDown requires you to install R, Quarto does not.