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
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.
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
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
# 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
Launching the command
Launching the command
Editing the epub with calibre
Output of a code extract in a PDF produced with Pandoc from markdown file.
A picture inside the pdf with a legend
The front page for the epub
A code extract captured with Polacode from Visual Studio Code
- Example of makefile
- Markdown Basics
- Markdown – Basic writing and formatting syntax
- Another good example of makefile
- A simple Pandoc template to build documents and ebooks.
- A nice memoir bootstrap package for Pandoc
- Creating PDFs from Markdown with Pandoc and LaTeX
- Utils: Writing a book in Markdown
- A good example on how to structure a book and release it with Pandoc
- Mastering Markdown, things you need to know to perform in markdown.
- Installing pandoc
- LaTeX on Mac, the Easy Way
- Install LaTeX on Mac with Brew
- 22 Best Visual Studio Code Extensions for Web Development