Beginner

Alias

If you use the Docker image (see System Setup) and you haven't set up the pandock alias yet, replace pandock with docker run --rm -it --user $(id -u):$(id -g) -v .:/data schuam/dac:v1.0.0 in the following commands. If you installed Pandoc directly on your system, replace pandock with just pandoc. For more information, refer to the System Setup page.

Note

All commands in this tutorial should be run from within the project directory (solution) that was mentioned on the Layout page. Make sure you're in the correct directory. If you put the solutions directory into your home directory, you can navigate to the solutions directory like so:

cd
cd solution

If you placed the solutions project somewhere else, use the appropriate cd command to navigate to that place.

In this Beginner section, we'll use a single Markdown source file along with the simplest form of the pandoc command to generate a PDF file. Even though this is the Beginner level, I won’t go into the details of Markdown syntax here. Plenty of online resources that cover it exist. Here are a few suggestions:

The original description of the syntax by John Gruber.
A very short description of the most basic syntax elements by the people from CommonMark.
The Basic Syntax description by Matt Cone which includes some tips on best practices.
Maybe most important when using Pandoc, the descriptions of Pandoc's Markdown Flavor.

Just some quick remarks:

Line breaks: In Pandoc, single new lines are treated as spaces, so feel free to split long lines for better readability. To start a new paragraph, leave an empty line.
Ordered lists: My recommendation, always use "1." for all items in ordered lists. Pandoc will automatically number them correctly in the output, making reordering simpler and preventing awkward numbering issues.
Syntax familiarity: Familiarize yourself with Markdown's syntax with one of the first three links from above and then read about Pandoc's Markdown flavor (last link in previous list). It will for example explain the syntax for the very first links you can see in the source file below: [Markdown][wikipedia_markdown].
Getting the basics down won't take you very long, I promise!

Here’s the complete source code for the Markdown file that we’ll use in all the levels. Feel free to browse through it. Don’t worry about the content itself — the purpose of the file is to demonstrate features rather than deliver meaningful content!

solution/src/md/solution.md

# Introduction

The goal of this document is to demonstrate how easy it is to generate
beautiful documents with just a little knowledge of
[Markdown][wikipedia_markdown] and a tool called [Pandoc][pandoc_homepage]. I
want to debunk the myth that **Docs as Code** (or **DaC** for short) is ...

- ... hard to learn.
- ... only used to document software projects.
- ... only suitable for programmers and/or engineers.
- ... would require you to learn a lot of [LaTeX][wikipedia_latex].


Always remember:

> Documents as Code is easy!

This document is not supposed to do so by itself. It is not some guide or
tutorial. The purpose of this document is to have something to work with to
demonstrate different aspects of the **DaC** approach to generate nice looking
documents. I set up a [website][schuam_dac] that explains everything and this
document will be used in the explanation.

It is also not a manual for Pandoc as this already exists
[online][pandoc_user_guide] or a Markdown guide, because there are already
plenty of resources available online that explain the Markdown syntax, e.g.
[this one][markdown_guide].

My plan is to set up a demonstration that is split into four levels (from
*beginner* to *pro*). The higher the level the better the generated document
will look. Nevertheless, only the highest two levels will require any
[LaTeX][wikipedia_latex] knowledge. But even at the second level, the document
will already look really professional and most likely way better than anything
you create with Word.

1. **Beginner**:

   Let's start simple. Just use a plain Markdown file and the simplest form of
   the `pandoc` command to build the output PDF file: no additional
   options/parameters, just the bare minimum.

   Assuming the source Markdown file is called `solution_beginner.md`, the
   following command renders the PDF output file `solution_beginner.pdf`:
   `pandoc -o solution_beginner.pdf solution_beginner.md`

1. **Intermediate**:

   Here we ...

    - add a first additional option to the `pandoc` command. This option
      enumerates the sections.
    - add some front matter with additional information about the document.
    - add some additional metadata to configure the styling of the output. This
      drastically improves the look of the output.

   The output are three consecutively better looking output files.

1. **Advanced**:

   This is the first time, a little bit of [LaTeX][wikipedia_latex] syntax is
   used to further improve the look of the PDF file. But don't worry, it is
   very simple and everything is explained. After that you should be able to
   make changes in the given example to tweak the look further to your liking.

   Pandoc can be extended by the use of filters. I show how to use one of them
   as an example. This will for instance allow us to reference images (see the
   [Figures section](#figures) or the [Inline Image
   section](#sec:inline-images)). See [chapter @sec:inline-images].

   The **advanced** level is split into two steps (two output files).

1. **Pro**:

   For the **Pro** level I figured it is time to write a little LaTeX template
   for Pandoc to get the maximum out of it.


All right let's get started. The following chapters won't necessarily contain
meaningful content. Their main purpose is to demonstrate different
possibilities for formatting and other features.

[pandoc_latex_docker]: https://hub.docker.com/r/pandoc/latex
[markdown_guide]: https://www.markdownguide.org/
[pandoc_homepage]: https://pandoc.org
[pandoc_user_guide]: https://pandoc.org/MANUAL.html
[schuam_dac]: https://www.dac.schuam.de
[wikipedia_latex]: https://en.wikipedia.org/wiki/LaTeX
[wikipedia_markdown]: https://en.wikipedia.org/wiki/Markdown


# Images

Images can either be added as figures or inline. When added as a figure, a
caption will be added that include the current number of the figure which is
automatically increase with every figure. When added inline, all that is added
is an image, nothing else.


## Figures

Figures are *floating* objects in [LaTeX][wikipedia_latex]. Since
[Pandoc][pandoc_homepage] used LaTeX in the background, figures might not
appear where you expect them to appear. While this might be annoying in the
beginning, this is actually a feature. Also you should always refer to an
included figure somewhere in the text. If you don't do that, you might as well
just not add the figure.

[Figure @fig:example] shows a section on the way between Santiago de Chile and
Mendoza in Argentina.

![Sample Figure](img/image.jpg){#fig:example}


## Inline Images

With inline images, you can for example place two images next to each other:

![](img/image.jpg){width=50%} ![](img/image.jpg){width=50%}


# Math

Something that is often needed is math expressions/equations/formulas. Just
like images math can be inserted inline or as separate entities.

## Inline Math

One of the most famous equations of all time is probably $E =
mc^2$.[^footnote_mass_energy]


## Equations

Writing the equation from the previous section inline, like I did, doesn't
really do it justice. Therefore it is also possible to render it a little more
noticeable like this:

$$
E = mc^2
$$ {#eq:mass_energy}

[Equation @eq:mass_energy] looks way better than the inline version doesn't
it?[^footnote_confirmation]

If you want, you can use superscripts and subscripts in normal text as well.
Here are two examples: H~2~O and 2^10^.

By the way, Albert Einstein published a bunch of papers. One is called "Zur
Elektrodynamik bewegter Körper" [see @einstein1905electrodynamik, pp. 42].

[^footnote_mass_energy]: According to [Wikipedia][wikipedia_mass_energy]
    Einstein was the first one to propose the equivalence of mass and energy.
[^footnote_confirmation]: Of course it does. Who questioned it?

[wikipedia_mass_energy]:
    <https://en.wikipedia.org/wiki/Mass%E2%80%93energy_equivalence>


# Tables

Last but not least, let's add a table to the document. This can be done in
multiple ways. Please read [Pandoc's User Guide][pandoc_user_guide] for more
information. I will just add one table that uses the most complicated type. I
wanted to use that type to demonstrate that you can create pretty complicated
tables with cells that span multiple rows and/or columns. Admittedly the
Markdown code is a little bit cumbersome, but if you don't need all the
features shown here, there are simpler table types.

: Table Example {#tbl:example_table}

+---------------+---------------+------------+
| Fruit                         | Prize      |
+:==============+:=============:+===========:+
| Apple         |  green \      | 1.00       |
|               |  round \      |            |
|               +---------------+------------+
|               |  red \        | 1.25       |
|               |  round \      |            |
+---------------+---------------+------------+
| Bananas       |  yellow \     | 0.50       |
|               |  curved       |            |
+===============+===============+============+
| Total         |               | 2.75       |
+===============+===============+============+

To add [table @tbl:example_table], I had to add the following to the Markdown
source file:

```markdown {.numberLines}
: Table Example

+---------------+---------------+------------+
| Fruit                         | Prize      |
+:==============+:=============:+===========:+
| Apple         |  green \      | 1.00       |
|               |  round \      |            |
|               +---------------+------------+
|               |  red \        | 1.25       |
|               |  round \      |            |
+---------------+---------------+------------+
| Bananas       |  yellow \     | 0.50       |
|               |  curved       |            |
+===============+===============+============+
| Total         |               | 2.75       |
+===============+===============+============+
```


# ToDos

What is left to create this demonstration:

- [x] ~~Set up the solution markdown source file.~~
- [x] ~~Set up CMake to build the output PDF file.~~
- [ ] Write the accompanying tutorial.
- [ ] Actually put the website online.
- [ ] What else?


# Feedback

If you have any form of feedback about this document or the accompanying
website, don't hesitate to send me an email. The address is:
<contact@schuam.de>. Or visit my website at <https://www.schuam.de>.

Copy this source code into a file named solution.md inside the src/md directory. The file also references an example image. You can either download it, or use one of your own images, placing it in the img directory with the name image.jpg.

To generate the output PDF file, run the following command:

pandock -o build/solution_beginner_1.pdf src/md/solution.md

This is pretty much the simplest form of the pandoc command. All you do is:

specify the output file that you want to generate: -o build/solution_beginner_1.pdf
specify the input file to use as the source for the output file: src/md/solution.md

Once the command has run successfully, your project directory should look like this:

$ tree
.
├── build
│   └── solution_beginner_1.pdf
├── img
│   └── image.jpg
└── src
    ├── bib
    ├── md
    │   └── solution.md
    └── meta

Here is what the first page of the generated output PDF looks like:

First page of the generated output
PDF

If you'd prefer not to generate it yourself, you can download the complete PDF for inspection. The output already looks pretty polished, likely even better than what you’d achieve in Word .

Just like that, quite a bunch of the requirements have already been met. On the first page you can see headings, lists, inline code (in the description of the Beginner level), and links. However, the links could look better (we'll address that soon).

The third page features images, math equations, and footnotes:

Third page of the generated output
PDF

And on the fourth page, you’ll find an example of a table and the start of a code block:

Table Example Code Block Example

Although the output already looks great, there are still a few issues. For example:

Page 1: The links for "Markdown" and "Pandoc" in the first paragraph work, but they look like regular text.
Page 2: Near the bottom, you can find the following text: "[Figure @fig:example]".
Page 4: Just below the first equation, you can fine the following text: "{#eq:mass_energy}".

All these issues are due to the fact that not all needed features are enabled yet. We'll start fixing them in the Intermediate level. By the end of the Advanced level, all the issues will be resolved.

For now, the purpose of the Beginner level is simply to get you started.