{"id":11283,"date":"2019-07-14T10:23:57","date_gmt":"2019-07-14T08:23:57","guid":{"rendered":"http:\/\/flaven.fr\/?p=11283"},"modified":"2019-07-17T06:54:01","modified_gmt":"2019-07-17T04:54:01","slug":"using-pandoc-to-generate-documentation-manuals-in-pdf-docx-html-from-markdown-documents","status":"publish","type":"post","link":"https:\/\/flaven.fr\/2019\/07\/using-pandoc-to-generate-documentation-manuals-in-pdf-docx-html-from-markdown-documents\/","title":{"rendered":"Using Pandoc to generate documentation, manuals in pdf, docx, html from markdown documents"},"content":{"rendered":"

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.<\/p>\n

You can find the files on GitHub at
\nhttps:\/\/github.com\/bflaven\/BlogArticlesExamples\/tree\/master\/using_pandoc<\/a><\/b><\/p>\n

To solve these common issues, I headed to video tutorials as it is the best way to share as no one is reading anymore \ud83d\ude42 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.<\/p>\n

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! <\/p>\n

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.<\/p>\n

Using Pandoc<\/h3>\n

If you need to install Pandoc on a Mac, Homebrew remains the best way to do it!<\/b><\/p>\n

\r\n  #install pandoc\r\n  brew update && brew install pandoc\r\n  #update pandoc\r\n  brew update && brew upgrade pandoc\r\n<\/pre>\n
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.<\/p>\n
\r\n#go to the dir\r\ncd [path-to-your-dir]\/using_pandoc\/\r\n\r\n\r\n#OK for PDF\r\npandoc --toc --latex-engine=xelatex chapters\/*.md -o readme_to_pdf_all.pdf\r\n\r\n#OK for epub with no cover\r\npandoc --toc --latex-engine=xelatex --table-of-contents --toc-depth=3 --epub-chapter-level=3 --webtex chapters\/*.md -o readme_to_pdf_all.epub\r\n\r\n#OK for epub with cover\r\npandoc --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\r\n<\/pre>\n
Using a Makefile<\/code><\/h3>\n
To ease the creation, let’s create a Makefile<\/code> to automate the delivery. You can find it in the github account. <\/p>\n
All the files will be created in a directory named output<\/code><\/b><\/p>\n
\r\n# Run \"make\" (or \"make all\") to convert to all other formats\r\n# Run \"make epub\" to convert file in .epub\r\n# Run \"make pdf\" to convert file in .pdf\r\n# Run \"make docx\" to convert file in .docx\r\n# Run \"make html\" to convert file in .html\r\n# Run \"make delete\" to remove to all files and directories\r\n<\/pre>\n
Conclusion<\/H3>
\nI 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.<\/b><\/p>\n
Launching the command make<\/code><\/b>
\n\"Using<\/p>\n
Launching the command make delete<\/code><\/b>
\n\"Using<\/p>\n
Editing the epub with calibre<\/b>
\n\"Using<\/p>\n
Output of a code extract in a PDF produced with Pandoc from markdown file.<\/b>
\n\"Using<\/p>\n
A picture inside the pdf with a legend<\/b>
\n\"Using<\/p>\n
The front page for the epub<\/b>
\n\"Using<\/p>\n
A code extract captured with Polacode from Visual Studio Code<\/b>
\n\"Using<\/p>\n
Read more<\/h2>\n