Like many other Open Source projects, the Icinga team uses GitHub as its hosting service. Over 25 different repositories contain our monitoring software Icinga 2, the web interface Icinga Web 2, Docker containers and Vagrant boxes, various modules, etc. Some of the repositories offer simple installation instructions and configuration examples (README.md), others contain a subdirectory called doc with more detailed instructions and several files.
To create a handbook for offline viewing, you don’t need to copy & paste the content of all the files into your favourite text editor or word processor and start from scratch. All of the guides are written in Markdown, a lightweight markup language with plain text formatting syntax, and it is quite easy to convert them to other formats like plain or rich text, HTML, HTML5, Wiki markup (MediaWiki), LaTeX, PDF, ODT, or EPUB. All you need is a little commandline tool called Pandoc .
Pandoc is part of most Linux distributions and you can install it with the package manager. If the version in the repositories is too old or if you’re running OS X or Windows, have a look at the Pandoc website and follow the download links.
Next, you can download the documentation from our GitHub repository. An easy way to obtain the latest copy is using the git command, e.g.:
$ git clone https://github.com/Icinga/icinga2 Icinga2 [...] $ git clone https://github.com/Icinga/icingaweb2 IcingaWeb2 [...] $ ls Icinga2/doc/ 10-monitoring-remote-systems.md 23-appendix.md 11-icinga2-client.md 2-getting-started.md 12-agent-based-checks.md 3-monitoring-basics.md 13-distributed-monitoring-ha.md 4-configuring-icinga-2.md [...] $ ls IcingaWeb2/doc/ 01-About.md 04-Resources.md 07-Preferences.md phpdoc.xml 02-Installation.md 05-Authentication.md 99-Vagrant.md res 03-Configuration.md 06-Security.md accessibility
As you can see, you now have a local copy, including the doc directory where you can find various .md files. Subdirectories with images are also included. You’re now ready to use the pandoc command to convert the files and create the document of your choice.
To convert all Markdown files into the HTML format and write a single file, you can concatenate the input files, define the format of the input and output, and then determine the output file name:
$ pandoc 1-about.md 2-getting-started.md 3-monitoring-basics.md [...] -f markdown -t html -o icinga2-doc.html
Since converting from Markdown (-f markdown) to HTML (-t html) is the default behaviour, the two options are not really necessary in this case. Supported input and output formats are listed in the manpage. If either of those formats is not defined explicitly, Pandoc will try to guess from the file extension.
The Icinga 2 documentation consists of more than 20 Markdown files. If you don’t want to type all the names, *.md won’t help you in this case and creates a list that starts with chapter 10. Number 1 (1-about.md) would end up between chapters 19 and 20. Use the -v option with ls to get filenames sorted into a natural numerical order, even when the numbers are not at the start of the names:
pandoc `ls -v *.md` -o icinga2-doc.html
You can now open the new file icinga2-doc.html in your web browser and check out the result. When you have a look at the source code you will notice that the HTML header and footer are missing: -s will see to that. Also, if you want to add a table of contents at the beginning, try –toc in combination with -N to create numbered sections:
pandoc `ls -v *.md` -s --toc -N -o icinga2-doc.html
It’s possible to include CSS stylesheets to create a custom look for your HTML handbook. Either use -H file.css to include the content of the file at the end of the header, or link to a stylesheet by defining the URL (-c URL).
LaTeX and PDF
To create a LaTeX document, you only need to adjust the output name in the command:
pandoc `ls -v *.md` -s --toc -N -o icinga2-doc.tex
Again, the -s option tells Pandoc to produce a header, in this case a preamble for the LaTeX file. It defines the document type, the paper and font size, additional packages, etc. Pandoc produces typographically correct output and adjusts quotation marks, dashes, non-breaking spaces and so on.
In the next step you can create a PDF document. Make sure to install LaTeX first, e.g. the texlive packages (Linux), MacTeX (OS X), or MiKTeX (Windows). Note: To compile the Icinga documentation, choose the xelatex typesetting engine instead of latex or pdlatex. It supports Unicode and is part of the standard LaTeX installation. Also keep in mind that the document needs to be compiled twice if you’re including a table of contents.
If your goal is to create a PDF document, you can skip one step – you don’t need to generate a LaTeX file and compile it yourself, unless you want to apply some changes first. Just define the correct output format (-o file.pdf) and let Pandoc do its magic. Use the option –latex-engine=xelatex to include UTF-8 support:
pandoc `ls -v *.md` -s --toc -N --latex-engine=xelatex -o icinga2-doc.pdf
Open Document Format
Pandoc can convert the Icinga 2 documentation into the Open Document Format. Use the following command to generate an ODT document:
pandoc `ls -v *.md` -o icinga2-doc.odt
The option –toc is missing, since it has no effect in this case – Pandoc won’t create a table of contents for this output format. It does apply the predefined heading paragraph styles, though, so it is no problem to create the table of contents in LibreOffice or Apache OpenOffice.
Another cool feature is that you can define OTT files as templates for the new book. Download an existing template or create your own, and then use –reference-odt=template.ott to assign it. Pandoc ignores the contents and uses merely the stylesheets for the output.
Starting with version 1.6, Pandoc can convert Markdown documents into the EPUB format, so it’s very easy to build an electronic book that you can upload to your e-reader or tablet. Pandoc looks after the table of contents, so the –toc option is not needed, but if you would like to add numbers to the sections, be sure to include -N:
pandoc `ls -v *.md` -N -o icinga2-doc.epub
That’s it – you can now upload the EPUB file to your reader. Alternatively, you can open it in Calibre, a program that manages your your e-book collection, offers an internal reader, changes the metadata of books and converts them into other e-book formats.
Pandoc itself is able to apply an external CSS stylesheet during the conversion. So, if you’re not happy with the default look, create your own or do a web search for other EPUB CSS files. To specify the stylesheet, use –epub-stylesheet=file.css. You can even add a cover image (–epub-cover-image=image.png) or take an influence on the metadata (–epub-metadata=file).
Any comments or suggestions? Let us know in the comments below. Happy hacking. 🙂