© Thomas Mailund 2019
T. MailundIntroducing Markdown and Pandochttps://doi.org/10.1007/978-1-4842-5149-2_4

4. Pandoc Markdown Extensions

Thomas Mailund1 
(1)
Aarhus N, Denmark
 

Markdown is, unfortunately, not standardized. Different tools will support different markup syntax and process them differently. The Markdown described in the previous chapter will work in most, if not all, tools. The table syntax is usually less well supported, but the rest of the markup will ordinarily work.

Pandoc provides several extensions to the Markdown language described in the previous chapter. In this chapter, we will see some useful extensions for lists and tables. To get a complete list of Pandoc extensions to Markdown, you should consult the Pandoc documentation at https://​tinyurl.​com/​y87mstzf.

Lists

Generally, the numbers you use when you write an ordered list are ignored. They are used to indicate list items, but the actual numbering does not matter. This makes it easier to insert a new item in the middle of a list, which is a good thing, but sometimes you want to start a list at a different number than one, and in that case, basic Markdown can’t help you. With Pandoc, though, lists start with the number you give the first item in a list. So you can start a list at number three like this:
3. This lists start at number three.
5. Although we used "5." to start this
   item, it still gets the number 4.
The numbers in the following list items are still ignored. The result will look like this:

  • 3. This lists start at number three.

  • 4. Although we used “5.” to start this item, it still gets the number 4.

This is a good way to continue lists, but you will have to update the initial number when you have added or removed items in the previous list.

To automatically make a list continue at the next number, even when you changed a previous list, you can use the special symbol “@”. This works just as a number when you use it in a list, and it always counts from where you left off. So you can write something like this:
(@) Starting a list
(@) Continuing the list
Here is some text that doesn't
belong to the list.
(@) This continues the list,
    numbered from where we
    left off the list.
(@label) This item is labelled
    so that we can refer back
    to it. Like this: see item
    (@label).
The result will look like this:
  1. (1)

    Starting a list

     
  2. (2)

    Continuing the list

     
Here is some text that doesn’t belong to the list.
  1. (3)

    This continues the list, numbered from where we left off the list.

     
  2. (4)

    This item is labelled so that we can refer back to it. Like this: see item (4).

     

This can be very useful for lists of examples or such, but the “@” counter is global so you cannot restart the counter. Unfortunately, there is currently no support for both automatically numbered items and restarting counters.

In this example, we also saw another feature of Pandoc. We do not have to write a number followed by a dot. In the previous example, we put numbers—represented by @—in parentheses, and the result was a list that used parentheses. You can also use a single closing parenthesis:
1) This is a
2) list
3) it really is
It will give you this list:
  1. 1)

    This is a

     
  2. 2)

    list

     
  3. 3)

    it really is

     
If you make lists using a number and a period, you get the standard numbered lists, but you can also use letters or Roman numerals just by starting the list with such. If you want to use parenthesis instead of periods, you can also do this. You can, for example, create a list like this:
  1. a.

    This list uses letters instead of numbers.

     
  2. b.
    We can make a sublist with roman numerals:
    1. i.

      This sublist also uses parenthesis

       
    2. ii.

      Cool, isn’t it?

       
     
The source markup for that list looks like this:
  1. a.

    This list uses letters instead of numbers.

     
  2. b.
    We can make a sublist with a roman numerals:
    1. i.

      This sublist also uses parenthesis

       
    2. ii.

      Cool, isn’t it?

       
     

You can mix the different list notations so you have different list formats as sublists, but if you mix them at the same level, you will start a new list.

Lists are frequently used to define terms or concepts, and in Pandoc you can create definition lists by following a term with a colon and indenting the start of the definition with a tab or at least four spaces. So you can create definition lists like this:

Something we want to define. Definition of the thing

As long as we indent the following lines, they become part of the definition.

Here starts the next thing we define. Here we write the definition.

More of the definition

The syntax for creating this list is this:
Something we want to define.
:    Definition of the thing
        As long as we indent the following lines, they
        become part of the definition.
Here starts the next thing we define.
:    Here we write the definition.
    More of the definition
An alternative syntax uses tildes, “~”, instead of colons:
Term 1
  ~ Definition 1
Term 2
  ~ Definition 2a
  ~ Definition 2b

  • Term 1 Definition 1

  • Term 2 Definition 2a

    Definition 2b

Either syntax will do.

Tables

To add tables to a document, you can mark up the columns using dashes. You can write a table like this:
  Right    Left     Center    Default
-------    ------ ----------  -------
     12    12        12           12
    123    123       123         123
      1    1          1            1
The result will look like this:

Right

Left

Center

Default

12

12

12

12

123

123

123

123

1

1

  1

1

How you align the elements in the columns determine how you align the headers above the dashes. If the text is to the right, the column will be right-aligned. The same for left and center alignment, if the text is on the left or in the middle, the table column will be left-aligned or centered. If you start the header at the same position as the dashes, you get the default alignment, which is left alignment.

You can leave out the headers, but then you need to repeat the dashes at the end of the table as well.
-------    ------ ---------- -------
     12    12        12          12
    123    123       123        123
      1    1          1           1
-------    ------ ---------- -------

12

12

12

12

123

123

123

123

1

1

  1

1

If you do not provide a header, the alignment is determined by the first line in the table. In the preceding example, in the last column, the reason it isn’t right-aligned is that there is a space after the first number in the column before the end of the dashes that specify the column. Move the first number one position to the right, and that column would also be right-aligned.

Tables are the Markdown markups with the least consistent support in different tools. The table syntax described often frequently works, but in the two editors I use for writing my books, they are not supported. In all the Markdown viewers I am familiar with, though, they display correctly.

In Pandoc, there is excellent support for tables, and Pandoc provides some extensions to table markup beyond the preceding notation.

For figures, you can add captions using the link syntax. For tables, you have no similar syntax. You can, however, add a caption to a table using “Table: Caption” following the table. So you can create a table with a caption like this:
-------     ------ ---------- -------
     12     12        12         12
    123     123       123       123
      1     1          1          1
-------     ------ ---------- -------
Table: This is a caption

The result looks like this :

Table 4-3. This is a caption

12

12

12

12

123

123

123

123

1

1

  1

1

You can leave out the “Table” part if you want; just having the colon will give you a caption.

If you want table cells to span multiple lines, you can do this as well. For multi-line tables, you must put a row of dashes before the header (unless you don’t have a header), you must end the table with a row of dashes and then a blank line, and you must separate rows by a blank line. This example, from the Pandoc manual, shows how this works:
-----------------------------------------------------
  Centred   Default      Right Left
   Header   Aligned    Aligned Aligned
----------- ------- ---------- ----------------------
    First   row           12.0 Example of a row that
                               spans multiple lines.
   Second   row            5.0 Here's another one.
                               Note the blank line
                               between rows.
----------- ------- ---------- ----------------------
The result will look like this :

Centred Header

Default Aligned

Right Aligned

Left Aligned

First

row

12.0

Example of a row that spans multiple lines.

Second

row

5.0

Here’s another one. Note the blank line between rows.

You can leave out the header, but then you must repeat the dashes that define the columns after the table, followed by a blank line.
----------- ------- ---------- ----------------------
   First    row           12.0 Example of a row that
                               spans multiple lines.
  Second    row            5.0 Here's another one.
                               Note the blank line
                               between rows.
----------- ------- ---------- ----------------------
Result:

First

row

12.0

Example of a row that spans multiple lines.

Second

row

5.0

Here’s another one. Note the blank line between rows.

An alternative syntax for tables uses plain text grids to separate columns . An example, with a header, looks like this:
+---------------+---------------+--------------------+
| Right         | Left          | Centered           |
+==============:+:==============+:==================:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+
Result:

Right

Left

Centered

Right

Left

Centered

Without headers, it looks like this:
+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+
Result:

Right

Left

Centered

For these types of headers, the colons determine the alignment. Put a colon at the end of the “=” or “-” of the cell-border to get right-aligned columns, at the left to get left-aligned columns, and at both ends to get centered columns, and leave them out for the default alignment.

You can also use pipes, “|”, to specify the columns. Then, the syntax will look like this :
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
Result:

Right

Left

Default

Center

12

12

12

12

123

123

123

123

1

1

1

1

Smart Punctuation

Proper text typography uses different types of dashes—hyphens in words, en-dashes for numeric intervals, and em-dashes for parenthetical sentences and emphasis. Quotes are usually different at the beginning and end of a text in quotation marks. Three dots are different from ellipses. Many word editors will automatically substitute some dashes and translate straight quotes into the correct form, but not all. Since you are writing Markdown in plain text, and since most keyboards do not give you access to all typographic symbols, Pandoc can help you out with getting these symbols. To enable this, you need to call Pandoc with the option --smart (we see how to invoke Pandoc in Chapter 5).

If you turn on smart punctuation , quotes will be handled correctly, three dots will be translated into ellipses, a single “-” will be a hyphen, two dashes will give you an en-dash, and three dashes will give you an em-dash.

Footnotes

You can insert footnotes in your text using a syntax resembling links and images. For footnotes, you need to add a caret, (ˆ). To put the footnote inside the text paragraph you are writing, you add a caret and then the footnote text in square brackets.
Footnote inside a paragraph.^[This is the footnote.]
Since footnotes tend to interfere with the main text, you can give them a label and add the text elsewhere. When you do this, you name the footnote and put the name in the main text.
Reference to a footnote.[^footnotelabel]

When you add a footnote this way, the caret has to go inside the brackets. If it goes before the brackets, you are adding the footnote inside the text.

Somewhere the text you must define what a footnote label refers to. The syntax is the same as the one for defining links you can refer to inside the text, except that for defining footnotes the name must start with a caret .
[^footnotelabel]: This is footnote two.
    If you want it to cover multiple lines, you
    have to indent the following footnote lines.
    by at least four spaces.

The output of the two approaches should look like this: Footnote inside a paragraph.1

Reference to a footnote.2

Exercises

Lists

Write a list with five items. Between two and three, add a paragraph of text, but make sure that the numbers continue with four.

Add a label to item three and refer to it in item five. Create a list of definitions as well. Make them multi-line.

Tables

Make a table with three columns where you left-justify the first column, center the second column, and right-justify the third.

Write a table with a caption. Until we format the Markdown with Pandoc in the next chapter, you will not see the result but keep the text so you can test it there

Footnotes

Write a text with a footnote. Use both notations for footnotes.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset