14  Simple block elements

14.1 What is a block?

A traditional document consists of lines of text organized into blocks, e.g. paragraphs or headings. A markdown document is likewise organized into inline elements that are put together into block elements.

  • Inline elements
    • words and spaces,
    • a few words in italics,
    • a formula in the flow of the text, such as \(x+y=c\).
  • Block elements
    • paragraphs
    • section headings
    • images, figures, tables
    • footnotes
    • ‘Divs’, i.e. arbitrary divisions
    • …

Some blocks (‘Div’ blocks, tables, footnotes) contain other blocks.

Some mathematical formulas are blocks, others are inline. We deal with them separately in Chapter 26.

14.2 Paragraphs

New paragraphs are encoded by leaving an empty line. That is, an empty line separates two paragraphs.

In typography paragraphs are distinguished from each other in two ways: first-line indentation (common in books) or a vertical space (common on the web). Your journal template will automatically typeset those.

If your journal template uses the first-line indent way of separating paragraphs, it will mostly handle typographic conventions correctly. For instance, it will be set not to indent the first line of paragraphs right below a heading (English convention) or to indent it (common in French). However, there are a few cases where you will need to manually specify that a first-line indent is or is not desired. See below.

Sometimes (rarely) you need a line break that does not start a new paragraph. See Section 12.8.

Problem. Text that directly follows a list, quote, figure, table or other indented material (statement) may either be a continuation of the previous paragraph or the beginning of a new one. That is a matter of meaning (is the text finishing the previous idea, or beginning a new idea?) and may not be clear-cut in all cases. If your journal uses first-line indentation to separate paragraphs, continuations should not be typesetted with an indented first line, but new paragraphs should.

The engine makes default assumptions: normally text below a list, quotation or statement continues the paragraph above and text below a table is a new paragraph. When the default assumption is wrong, we need to manually specify that a paragraph’s indent is to be treated otherwise.

There are two ways to solve this.

Dialectica guidelines. Our template uses the first-line indentation style of separating paragraphs, and we use the first solution below. Sometimes it is unclear whether a paragraph continues the previous one or is a new one: the best is to ask the author, but you can also use your best judgment.

14.2.1 With the first-line-indent filter

Requires: the first-indent-line filter.

  • Add \indent at the beginning of a paragraph to force a first-line indentation.
  • Add \noindent at the beginning of a paragraph to prevent first-line indentation.

Example. In the text below, the quotation ends the paragraph: the text below the quotation isn’t a continuation of the previous paragraph but a new paragraph. This goes against the default assumption, so we need to add \indent. On the other hand, the paragraph under the table is a continuation of the previous one, which also goes against the default assumption. So we add a \indent.

In the final words of the wise man:

> It's unclear what is going on here.

\indent Now on another note, we can see from the table below:


Test group   Control group
----------- ----------------
.9            .9

\noindent That we don't observe any difference between the two groups.

Note: \indent and \noindent are LaTeX code, but the first-line-indent filter ensures they are formatted correctly in other output formats.

Note: you can follow this section’s advice even if your journal doesn’t currently use first-line indentation to separate paragraphs but vertical spaces instead. With the first-line-indent filter the added code won’t make a difference to the output, but it will allow you to switch to first-line indent later if needed.

See the first-line-indent filter’s page for more options and information.

14.2.2 Without the filter

If your journal does not use the first-line-indent filter, you can only control first-line indentation for the LaTeX/PDF output, not HTML.

Without the filter, text after any block element is treated as a new paragraph.

  • Add \noident at the beginning of paragraphs following quotations, statements, lists unless they are genuinely new paragraphs.

You may add \indent on paragraphs that need to be indented, but that’ll be the default.

Note: if your journal currently uses vertical spacing rather than first-line indentation to separate paragraphs, adding \noindent codes does no harm. But if you don’t use the first-line-indent filter, adding \indent codes will indent paragraphs even if the journal style uses vertical spacing. So either use the filter or don’t use indent codes unless your journal is set to use first-line indentation.

14.3 Headings

Headings of different levels (section, subsection, subsubsection) are encoded as a line starting with #, ##, ### followed by the title.

I want I type
1. Section heading # Section title
1.2 Subsection heading ## Subsection title
1.2.1 Subsubsection title
 ### Subsection title
lower titles ####, #####, ######

In Dialectica headings are numbered up to the subsection (#, ##, ###). Headings of level four (####) are used for un-numbered smaller units.

We have also two “inline” headings styles, where the heading title is displayed at the beginning of the following paragraph rather than on its separate line. They are level 5 (#####) and level 6 (#######).

We discourage authors from using headings below the subsection (##) in articles though, though we can use them if they improve readability.

Do not manually add numbers to section headings. They are automatically added by the house template.

BAD GOOD
# 1 Methods # Methods
# 1 #

If the heading has no title, you should simply enter # (or the relevant level) with no title.

  • If an article starts with an introduction section, that section should not have a heading. So do not start articles with:
# Introduction

14.4 Footnotes and endnotes

You can encode notes. Markdown doesn’t distinguish footnotes and endnotes: there’s only one kind of note, and your journal template decides where they’re printed out.

There are two ways to enter notes called inline and by reference link. In the inline method, the note is weaved within the text itself, as follows:

This is the main text.^[In the footnote, I distract you with an irrelevant point.]
  This continues the main text.

In the reference link method, we only put a reference to the note in the text, and the note text is given separately—typically below the paragraph in question or at the end of the manuscript:

This is the main text.[^fn1] This continues the main text.

[^fn1]: In the footnote, I distract you with an irrelevant point.

Both methods produce the very same output:

This is the main text.1 This continues the main text.

The inline method is best suited for short notes. The reference-link method is better suited for longer notes and is required when a footnote spans multiple paragraphs.

Warning for international keyboard users. If you’re using the International US Keyboard (and perhaps other), entering ^[ will probably result in a small circumflex accent instead of a big one: compare ˆ and ^. To get the big one, press Shift+6 (the key for ^) then the space key.

14.4.1 Inline method

In the inline method, you place ^[...] where you want the note number to appear, and you place the text of the footnote between the brackets. Note that the ^ character is outside the brackets.

This is the main text.^[In the footnote, I distract you with an irrelevant point.]
  This continues the main text.

The note text may contain markdown codes, except blocks. It’ll be a single block (paragraph) in the output.

14.4.3 Multi-paragraph notes

Using the reference-link method, you can enter long notes consisting of multiple paragraphs. You simply need to indent the paragraphs:

This is the paragraph where the note appears.[^fn2] The paragraph
continues for a bit and then ends.

[^fn2]: This is the footnote text. I've placed it below the paragraph
    where the footnote appears, though I could have placed it at
    the very end of the document, or anywhere else for that matter.

    This is still part of the footnote---it's a second paragraph of
    the footnote. Note how it's indented two spaces like the first
    paragraph. If it wasn't, it would be considered part of the
    main text.

This is the following paragraph of the main text. It's not indented,
so it's not part of the footnote.

Result:

This is the paragraph where the note appears.2 The paragraph continues for a bit and then ends.

This is the following paragraph of the main text. It’s not indented, therefore it’s not part of the footnote.

Four spaces indentation on each paragraph should work.3 If you encounter trouble, see “Troubleshooting” at the end of this section.

Notes can contain other kind of blocks other than notes themselves: quotations, images, Divs (see below), etc.

This is the main text.[^3] This continues the main text.

[^3]: This note takes more space.

    It contains several paragraphs.
                 
    > It even includes a quotation.
                 
    And it ends here.

Result:

This is the main text.4 This continues the main text.

Troubleshooting. Too much or not enough indentation on the paragraphs may ‘break’ the note; in output, the broken text appears where you’ve placed the footnote text—below the original paragraph or at the end of the document. If it appears as normal text, check the paragraphs are aligned first, and if they are, try more indentation. If it appears as code text (monospace font), you have too much indentation (more than 4 spaces), reduce it.

14.4.4 Fusing multiple markdown documents

Unless your journal template’s guidelines specify otherwise, it’s fine to use the same identifier, e.g. 1, in different articles.

14.4.5 Cross-referencing footnotes

Cross-reference to footnotes has to be done manually. Don’t enter them before you know that the footnote numbers in the output are final. See Section 23.3.

14.5 Divs

Divs are general-purpose blocks that we use to typeset advanced elements like statements or to mark out sections of a document for special treatment, e.g. ‘imagifying’ all the LaTeX formulas it contains. This section explains how to encode them.

A Div is an arbitrary document division, usually invisible to the reader. It contains one or more blocks—which can be paragraphs, quotations, etc. or even other Divs. It also has attributes, and that is what makes it useful: for we use the attributes to tell our typesetting engine that the Div’s content is to receive special treatment. In the case of statements, we use a Div with the special statement attribute to tell the engine that its contents are a statement—hence, that they must be indented.

In markdown, Divs are created using a pair of “fences”, which are single lines consisting of one or more colons:


This paragraph is in the document's main flow.

:::

This paragraph is inside a Div.

This paragraph is also inside the same Div

:::

The first ::: fence opens the Div, the second one closes it. We can include a Div within a Div by using a greater number of colons for the enclosed one:


This paragraph is in the document's main flow.

:::

This paragraph is inside a Div.

:::::

This paragraph is inside a new Div that's inside the first Div.

:::::

This paragraph is inside the first Div.

:::

It’s good practice, though not technically necessary, to use the same number of colons for the opening fence and the closing fence of the same Div.

The Divs in the examples above are completely invisible in PDF or HTML outputs. Divs become interesting when you give them attributes. Attributes are added to the opening fence of a Div, between curly braces, separated by spaces:


::: {.statement #myprinciple color=red}

Everything comes in due time.

:::

This illustrates the three kinds of attributes a Div may have:

  1. one or more classes indicated with a dot, e.g. .statement. A class indicates that the Div is of a certain kind. Several Div can be of the same class (kind), and a single Div can have several kinds.
  2. an unique identifier aka ID: indicated with a hash, e.g. #myprinciple. This uniquely identifies a Div, to cross-reference it for instance. A Div can only have one ID, and a Div’s ID should not be assigned to any other Div nor even to any other element (such as a heading, figure, etc.).
  3. Key-value pairs, indicated by the equal sign, e.g. color=red. These are used to state that a certain aspect of the Div (e.g., the text color) has a certain value. If the value contains space or special symbols it’s enclosed in quotation marks.

For statements only classes and IDs are relevant.

When a Div’s attributes consist of a single class, and nothing else, it can be encoded without curly braces and dots. Thus the following:


::: {.statement}

Everything comes in due time.

:::

can be abbreviated:


::: statement

Everything comes in due time.

:::

Some prefer more visible fences. You can use full lines of colons. If there are attributes, you may add colons after the attributes too. For instance, the earlier attributes example can just as well be encoded as:


::: { .statement #myprinciple color=red } :::::::::::::::::::::::::

Everything comes in due time.

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

That is wholly up to you: using full-width fences or shorter ones makes no difference to the result.

  1. In footnote, I distract you with an irrelevant point.↩︎

  2. This is the footnote text. I’ve placed it below the paragraph where the footnote appears, though I could have placed it at the very end of the document, or anywhere else for that matter.

    This is still part of the footnote—it’s a second paragraph of the footnote. Note how it’s indented to align with the first paragraph. If it wasn’t, it would be considered part of the main text.↩︎

  3. The markdown manuals for Pandoc and Quarto don’t give a precise indentation size.↩︎

  4. This note takes more space.

    It contains several paragraphs.

    It even includes a quotation.

    And it ends here.↩︎