Using Pandoc to generate documentation, manuals in pdf, docx, html from markdown documents

Since few months, as I am working on new back-office made with Symfony, I tried to explore the best way to share information with the minimum of repeatedly work. The documentation is gathered mostly for user support. It should be available for any kind of users from end-users to training people through developers and in especially in any format (pdf, html…) without depreciations.

You can find the files on GitHub at
https://github.com/bflaven/BlogArticlesExamples/tree/master/using_pandoc

To solve these common issues, I headed to video tutorials as it is the best way to share as no one is reading anymore 🙂 but I still had a lot stuff written and unexploited! To make it shareable at least, I have converted them into markdown format as it seems the format commonly accepted by developers. This format, I discovered it through an intensive usage of GitHub.

Still, making a documentation is an hassle, in particular if you want to release in the end a manual in pdf for instance. At the very beginning, with the markdown, I had low expectations in term of design and appearance. Even though I was making progress in markdown coding, the more my document’s markdown structure becoming complex the less the output in pdf for instance was satisfying!

For the conversion from readme to pdf, I discovered and used Pandoc, a great tool however if you want to make a true layout for a pdf for instance, better used a desktop publishing software like Scrivener or even InDesign for instance.

Using Pandoc

If you need to install Pandoc on a Mac, Homebrew remains the best way to do it!

  #install pandoc
  brew update && brew install pandoc
  #update pandoc
  brew update && brew upgrade pandoc

When Pandoc is installed, you can try to enter few commands to generate whether a PDF or an EPUB, converting on fly your markdown files. Below you can find some command that can be passed in the console to generate whether an .pdf file or an .epub file.

#go to the dir
cd [path-to-your-dir]/using_pandoc/
 
 
#OK for PDF
pandoc --toc --latex-engine=xelatex chapters/*.md -o readme_to_pdf_all.pdf
 
#OK for epub with no cover
pandoc --toc --latex-engine=xelatex --table-of-contents --toc-depth=3 --epub-chapter-level=3 --webtex chapters/*.md -o readme_to_pdf_all.epub
 
#OK for epub with cover
pandoc --toc --latex-engine=xelatex --epub-cover-image=images/cover_1563x2500.jpg --table-of-contents --toc-depth=3 --epub-chapter-level=3 --webtex chapters/*.md -o readme_to_pdf_all.epub

Using a `Makefile`

To ease the creation, let’s create a Makefile to automate the delivery. You can find it in the github account.

All the files will be created in a directory named output

# Run "make" (or "make all") to convert to all other formats
# Run "make epub" to convert file in .epub
# Run "make pdf" to convert file in .pdf
# Run "make docx" to convert file in .docx
# Run "make html" to convert file in .html
# Run "make delete" to remove to all files and directories

Conclusion

I must admit Pandoc is pretty powerful to generate all kind of document on fly with the help of a makefile. For instance, if you are quoting code in your book e.g ruby, javascript, php… The rendering is almost as good for syntax highlight as a text editor like Sublime or Visual Code or even Polacode for Visual Studio Code. Yes, it is definitely essential for documentation, it is easy and quick but for layout a real book, I ‘d rather use another software like Scrivener.

Launching the command make