Numbering

The .numbering function sets the global numbering configuration of the document. The following elements can be numbered:

• Headings and table of contents entries
• Figures
• Tables
• Equations
• Code blocks
• Footnotes
• Custom elements (.numbered)

The configuration is represented by a Dictionary. The following snippet shows the full configuration schema, where all entries are optional:

.numbering
  - headings: <format>
  - figures: <format>
  - tables: <format>
  - equations: <format>
  - code: <format>
  - footnotes: <format>

Each format parameter accepts either none, or a string where each character represents either a counter or a fixed symbol:

• 1 for decimal (1, 2, 3, ...)
• a for lowercase latin alphabet (a, b, c, ...)
• A for uppercase latin alphabet (A, B, C, ...)
• i for lowercase roman numerals (i, ii, iii, ...)
• I for uppercase roman numerals (I, II, III, ...)
• Any other character is a fixed symbol.

Default formats

The default numbering format, if unspecified, is:

• For paged documents:

  • 1.1.1 for headings;
  • 1.1 for figures and tables;
  • (1) for equations;
  • 1 for footnotes.

• For plain documents:

  • (1) for equations;
  • 1 for footnotes.

• For slides documents:

  • 1 for footnotes.

Any active numbering configuration can be turned off via the .nonumbering function.

Merging configurations

By default, .numbering enhances the current numbering configuration by merging the new configuration with the existing one, meaning that only the specified entries are updated, while the rest remain unchanged.

To avoid merging, thus turning off numbering rules for unspecified entries, set the merge:{no} argument:

.numbering merge:{no}
  - figures: 1.1

 

Headings

.numbering
  - headings: 1.A.a

# Title    <!--   1   -->
## Title   <!--  1.A  -->
### Title  <!-- 1.A.a -->
### Title  <!-- 1.A.b -->
#### Title <!-- None  -->
## Title   <!--  1.B  -->
# Title    <!--   2   -->
## Title   <!--  2.A  -->

Decorative headings

To prevent a heading from being numbered, append a ! after the last # sign. For example #!, ##!, ###!, etc.

.center
    #! My document

# Introduction

.loremipsum

Decorative headings also don't appear in table of contents.

 

Figures

Figures are numbered only if they feature a caption, which may also be empty.

.numbering
  - headings: 1.A.a
  - figures: 1.1

# Title

![Logo](quarkdown-icon.svg "The Quarkdown icon")

## Title

![Logo](quarkdown-icon.svg "")

# Title

![Logo](quarkdown-icon.svg "")

 

When numbering elements, the amount of symbols in the format dictates the rules which cause the counters to reset.
The previous example, run with figures: 1, results in the following:

 

Tables

.numbering
  - headings: 1.A.a
  - tables: 1.1

# Title

|           | Age | Favorite food |
|-----------|-----|---------------|
| **Anne**  | 24  | Hamburger     |
| **Lucas** | 19  | Pizza         |
| **Joe**   | 32  | Sushi         |
"Study results."

## Title

|           | Age | Favorite food |
|-----------|-----|---------------|
| **Anne**  | 24  | Hamburger     |
| **Lucas** | 19  | Pizza         |
| **Joe**   | 32  | Sushi         |

# Title

|           | Age | Favorite food |
|-----------|-----|---------------|
| **Anne**  | 24  | Hamburger     |
| **Lucas** | 19  | Pizza         |
| **Joe**   | 32  | Sushi         |

 

Equations

Math blocks (equations) are numbered only if they feature a cross-reference ID.

.numbering
  - equations: (1)

$ E = mc^2 $ {#energy}

$ F = ma $ {#force}

Conventionally, if the equation is not cross-referenced anywhere in the document, but you still want it to be numbered, _ can be set as the ID:

$ E = mc^2 $ {#_}

$ F = ma $ {#_}

 

Code blocks

.numbering
  - code: 1

```python
def hello():
    print("Hello, world!")
```

```kotlin
fun main() {
    println("Hello, world!")
}
```

 

Footnotes

The numbering format of footnotes is flat, meaning it only considers the leftmost symbol, and the rest is ignored.

If not specified, footnotes format defaults to 1 (decimal).

.numbering
  - footnotes: i

Here is a footnote reference[^: First], and another one[^: Second].

 

Custom numbered elements

Along with built-in numerable elements we just discussed, Quarkdown additionally allows any element to be numbered if wrapped in a .numbered block.

The function accepts two arguments:

1. A key string. The number of the element is counted across previous occurrences with the same key;
2. A lambda block which takes the number as an argument, formatted according to the active numbering format.

.numbered {greetings}
  number:
  **Hello!** This block has the number **.number**

Executing the previous block will render an empty string in place of number. That's because we need to specify the numbering format for greetings in the .numbering call:

.numbering
  ...
  - greetings: 1.a

A numbered block can also be cross-referenced. See Cross-references for details.

Full example:

.numbering
    - headings: 1.1
    - greetings: 1.a

# Title 1

.numbered {greetings}
    number:
    **Hello!** This block has the number **.number**

.numbered {greetings}
    number:
    **Hey!** This has instead the number **.number**

# Title 2

.numbered {greetings}
    number:
    **Hi!** Here we have the number **.number**

 

Localization

The localized name of the labeled element appear in captions if .doclang is set and the locale is supported.
For instance Figure and Table for the English locale, Figura and Tabella for Italian.

 

Themes

Layout themes affect the way numbers are displayed:

minimal theme