# Extended Markdown
This chapter covers advanced formatting features that enhance document
structure and presentation. These features help create professional documents
with rich content organization, proper cross-referencing, and typographic
excellence.
## Fenced divs
Fenced divs are transformed into XHTML `div` elements. They allow semantic
organization and styling beyond standard Markdown.
### Basic syntax
A fenced div starts with at least three colons (`:::`), followed by one or more
spaces, and then any word. Content follows immediately on the next line.
Fences must be terminated with at least three colons alone on a line. For
example:
The output resembles:
### Extended syntax
Fenced divs have an extended syntax for more influence over the presentation.
The syntax allows for a unique identifier (marked with a hash, `#`), multiple
classes (each starting with a period, `.`), and key-value pairs (of the form
`name=value`):
This produces:
While this syntax is not standard Markdown (i.e., CommonMark), it is supported
by many tools, including pandoc.
### Nested syntax
Fenced blocks may be nested to create hierarchical document structures:
This produces nested `div` elements:
Such nesting can help with complex presentation logic.
## Code blocks
In technical documentation, source code snippets help explain algorithms. An
example snippet syntax is given in the following quintessential BASIC program:
``` basic
10 print "hi"
20 goto 10
```
The word `basic` suggests that the presentation layer colourise the syntax
according to the rules of the BASIC programming language. Code blocks are also
used to draw diagrams using text-based syntaxes. See [@sec:text-diagrams] for
details.
## Inline classes
Inline classes can be assigned to words or phrases. This allows presentation
logic to stylize words based on their classification. The general form of
inline classes follows:
For example:
The given example outputs the following XHTML:
Note the semantic `warning` class instead of a direct colour class such
as `red`. This allows the colour to be changed at the presentation layer
without the class name becoming stale.
## Captions and cross-references
Captions provide context and descriptions for tables, figures, equations, and
so forth. Cross-references allow linking to captioned items throughout the
document.
### Caption syntax
A caption *must* start with a double colon (`::`) and *must* be separated by a
blank line from the item it describes.
For images:
For tables:
For equations:
Note that this syntax is not supported by any other Markdown tool.
### Cross-references
Cross-references use anchor type names and unique identifiers such as:
- `{#type-name:id}` -- defines an anchor name
- `[@type-name:id]` -- references the anchor
Example image with cross-reference:
Anchors can include any type name and identifier, such as:
### Predefined type names
To simplify writing captions and references, predefined type names correspond
to labels commonly used in documents. [@tbl:type-names] lists predefined
cross-reference type names along with their associated labels. Labels are
inserted into the document automatically.
| Type name | Label |
|----------------------------------|--------------|
| algorithm, alg | Algorithm |
| equation, eqn, eq | Equation |
| figure, fig | Figure |
| formula | Formula |
| listing, list, lst, source, src | Listing |
| lyric | Lyrics |
| music, score | Score |
| table, tbl, tab | Table |
:: Cross-reference types and labels {#tbl:type-names}
You may add your own labels as follows:
1. Edit `xml-references.tex` in the `xhtml` theme subdirectory.
1. Insert a new line within the `ReferenceLabels` data set:
1. Ensure there's a trailing comma (`,`).
1. Save the file.
## Quotation marks
{{app.title}} integrates KeenQuotes, a library for curling straight quotes in
both British and American English, with a high degree of
accuracy. To achieve this, all straight quotes are examined throughout the
document and, based on context, emitted as a particular entity encoding.
Understanding quotation mark encoding helps ensure proper typography in both
digital and print formats. Different encoding options provide flexibility for
various output requirements. [@tbl:quote-encoding] lists available encoding
choices.
| Option | Encoding | Description |
|----------|------------|---------------------------------------------|
| regular | | Do not encode |
| apos | `'` | Curled when typeset to PDF |
| aposhex | `'` | Apostrophe's numeric value |
| quote | `’` | Right single quotation mark |
| quotehex | `’` | Right single quotation mark's numeric value |
| modifier | `ʼ` | The modifier letter apostrophe |
:: Single straight quote encoding options {#tbl:quote-encoding}
When typesetting to PDF, only the semantically correct `'` value will be
curled. Authors may enter quotation marks by hand (`“”`), which will typeset as
expected.
### History
The origins of quotation marks trace back to scholarly annotation practices in
Ancient Greece. Greek scribes used marginal symbols like the diplé (`⟩`) to
highlight notable passages. A variant, the diplé periestigmene (`⸖`)—a diplé
accompanied by dots—was used by scholars to indicate disagreement with earlier
interpretations. These marks laid the groundwork for distinguishing quoted
text.
By the seventeenth century, quotation marks appeared regularly in printed
texts. Western European typographers in the nineteenth century adopted the
convention of turning quotation mark pairs outward, creating the familiar
"double curved" style.
Early mechanical typewriters lacked many punctuation marks. Straight single and
double quotes served multiple roles: quotation marks, apostrophes, feet and
inches, and mathematical primes. Computer character sets later codified
straight quotes (such as ASCII character 34, `"`), creating ongoing
typographical challenges.
Modern standards recommend using the right single quotation mark (`’`) for
apostrophes, though this creates semantic ambiguity since the same character
also closes dialogue. Consider the sentence:
> Ambiguity lurks in \"\'cause the horses\'\".
The meaning of `'cause` (*because* vs. *induce*) determines whether to use an
opening quote or apostrophe; historical decisions still impact modern
typography.
## Summary
[@tbl:markdown-extended-syntax] summarizes the syntaxes described in this
chapter.
| Syntax | Meaning | Marks |
|------------------------|---------------------------------------------------|
| `::: name` ¶ `:::` | Fenced div | Triple colons |
| ` ``` name` ¶ ` ``` ` | Code block | Triple backticks |
| `[word]{.class}` | Inline class | Brackets and braces |
| `{#type:id}` | Cross-reference definition | Braces and hash |
| `[@type:id]` | Cross-reference anchor link | Brackets and at |
:: Extended syntax {#tbl:markdown-extended-syntax}
Note that the pilcrow (`¶`) means that the opener is separated from its closer
by one or more blank lines (i.e., paragraphs).