Photo by Edgar Chaparro on Unsplash
Laying out documents with Markdown and Pandoc
In Shape
Text editing programs such as Microsoft Word, Apple Pages, and the open source LibreOffice suite can be used to create documentation and instructions. All of these programs mix different elements of a document together. For example, good documentation or a good manual does not consist of just plain text; it also contains images, graphics, tables, lists, and other elements. Conversely, this means that when writing, attention must be paid not only to the content of the document but also to coordinating the individual elements neatly in terms of the layout.
Unsurprisingly, this what-you-see-is-what-you-get (WYSIWYG) principle is very popular. Another type of tool maintains a division between the content of a document and the layout (e.g., in web development). No one would think of mixing the layout of a web page with the page content. Instead, a style sheet is used for the layout, typically available as a CSS (cascading style sheet) file [1]. To create a layout for the web page, you only need to modify the CSS, without having to change any of the page content.
TeX, LaTeX, and Markdown
If you prefer a logical division between content and layout, you can always use text typesetting systems such as TeX [2] or LaTeX [3]. However, these tools are complex, with syntax that is not necessarily intuitive, and require a certain period of familiarization. LaTeX is, strictly speaking, only a collection of macros that are intended to simplify the use of TeX.
Markdown [4] is far easier to use. This simple markup language can be learned, and therefore also used, by anyone in a short amount of time. Another advantage is that you can write a Markdown document in any text editor – you do
...
Buy this article as PDF
(incl. VAT)
Buy ADMIN Magazine
US / Canada
UK / Australia
Related content
-
Five free wiki platforms reviewed
If you want to operate a wiki in your data center as a document and knowledge database for workgroups, you will find a large selection of open source applications. We tested five free wiki platforms for different use cases on the local network. -
Moving from Atlassian Confluence to BlueSpice
With Atlassian's announcement that they are moving to a cloud-only solution, many organizations will be looking for an alternative that lets them keep their collaboration data local. BlueSpice is a worthy open source alternative with easy-to-use migration tools. -
Incident response with Velociraptor
The software incarnation of the feared predator in the Jurassic Park movies has been on the hunt for clues to cyberattacks and indicators of compromise. We show you how to tame the beast and use it for your own purposes. -
A DIY HTML Engine
Jekyll is a lightweight, fast, HTML engine that renders websites with ease, with the added benefits of low cost, high speed, security, and free hosting with GitHub Pages. -
Collaborative online office solutions
People say many cooks spoil the broth, but collaborative editing of documents does not necessarily have to end up in chaos. The collaborative functions in these free online office solutions can help users with teamwork.