Usability

Plain Text Source Files and Simple Markup

In this tutorial, we’ll use Markdown as the markup language for the main source files. While Markdown, as originally described by John Gruber, has some limitations — such as ambiguities and a lack of advanced layout features — these are addressed by various extensions. For example, CommonMark and Pandoc's version of Markdown extend the original specification to fill in these gaps and offer additional functionality.

Despite its shortcomings, Markdown remains a strong choice for several reasons:

• It’s a human-readable plain text markup language.
• It’s relatively easy to learn and use.
• It’s widely adopted and supported.
• It’s the markup language I’m most familiar with .

For metadata, we’ll use YAML, which is a "human-friendly data serialization language" according to the official YAML web site. Although YAML can be a bit tricky at times, the aspects we’ll use are straightforward and simple.

If you're new to Markdown or YAML, investing a little time to learn the basics will be worthwhile. It’s probably quicker than navigating the complex menu structures of traditional word processors. Additionally, mastering these basics prepares you to handle Docs efficiently, with stable and consistent syntax compared to frequently changing word processor features. Here are some possible resources to get started:

• Markdown
  • Basic Syntax
  • Cheat Sheet
• YAML
  • YAML Syntax
  • Cheat Sheet

Fast and Easily Generated Previews

I’ll introduce Pandoc for rendering PDFs. The speed of rendering depends on the complexity of your Docs and your computer, but pandoc has consistently been quick enough for my needs.

For viewing the generated PDFs, I use Zathura, a document viewer that automatically updates when the PDF file changes. This allows for seamless viewing of updates without manually reloading the PDF.

Note

I use zathura on a linux machine. I'm not sure if it is available on other operating systems. Please find a good PDF viewer for your platform if zathura is not available.

Ok, let's set up our system and explore how to meet the layout requirements.