Headers

This is a Heading h1

This is a Heading h2

This is a Heading h3

Formatting

This text will be italic. This text will be bold. You can combine them

Blockquotes

Markdown is a lightweight markup language with plain-text-formatting syntax, created in 2004 by John Gruber with Aaron Swartz.

Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.

Blocks of code

let message = "Hello world";
alert(message);

Inline code

This web site is using markedjs/marked.

Lists

Unordered

• Item 1
• Item 2
• Item 2a
• Item 2b
  • Item 3a
  • Item 3b

Ordered

1. Item 1
2. Item 2
3. Item 3
   1. Item 3a
   2. Item 3b

Checklist

• Task 1
• Task 2

Figures

Subfigures

Reference the whole group with Figure. 2. Reference the children with Figure. 2a and Figure. 2b. This also demonstrates clickable labels.

Equations

Display math can be labeled with a following attribute paragraph, or by embedding a LaTeX \label{...} in the math itself.

Equation labeled after the block:

Reference: Equation. 1.

Equation labeled inside the math:

Reference: Equation. 2.

Another explicit equation for grouped references:

Reference: Equation. 3.

Auto equation labels

Because this page enables autoEqnLabels: true, an unlabeled display equation still gets numbered.

Tables

Tables use a caption paragraph of the form : Caption {#tbl:label}.

See Table. 1.

Compare Table. 1 and Table. 2.

Embedded CSV

Here is the data from example.csv:

Reference: Table. 3.

Sections

Sections can use explicit labels or rely on autoSectionLabels.

• Explicit section labels: Section. 8, Section. 8.2.
• Auto-generated section labels work too when headings omit {#sec:...}.

Auto-labeled subsection

This subsection has no explicit label. With autoSectionLabels: true, it still receives a section id and can be referenced as ??sec:auto-labeled-subsection.

Depth-aware numbering

This page enables numberSections: true and sectionsDepth: -1, so all heading levels are numbered hierarchically. Edit these parameters in the frontmatter.

Code Listings

Listings can be declared three different ways, plus a pandoc-style wrapping div.

Caption attribute on the fence

print("Hello, World!")

Reference: Listing. 1.

Table-style caption before the block

def fib(n):
    if n <= 1:
        return n
    return fib(n - 1) + fib(n - 2)

Reference: Listing. 2.

Table-style caption after the block

const greet = (name) => `Hello, ${name}!`;

Reference: Listing. 3.

Wrapping div syntax

console.log(1)

Reference: Listing. 4.

Cross-Reference Syntax

Single references

Single references use the full label as the link on this page because nameInLink: true is enabled.

• Figure: ??fig:placeholder
• Equation: Equation. 1
• Table: Table. 1
• Listing: Listing. 1
• Section: ??sec:figures

Capitalized references

• ??Fig:placeholder is a placeholder figure.
• Equation. 1 is Einstein’s equation.
• Table. 1 lists elements.
• Section. 10 covers cross-references.

Prefix suppression

Use [-@...] to remove the default prefix.

• Figure ??fig:placeholder is the first figure in this section.
• Equation 1 is the first equation here.

Grouped references and ranges

• Figures: ??fig:placeholder??fig:width-only
• Equations: Equations. 1–3
• Tables: Tables. 1, 2

Three consecutive equation numbers collapse into a range in Equations. 1–3.

Unknown references are preserved visibly

Undefined labels render as ??..., for example: ??fig:does-not-exist.

Custom Labels And Manual Numbering

You can override an item’s displayed number with label="...", or force the numeric counter with number=.

Reference: Figure. A uses the custom label A.

Those two figures demonstrate chapter-aware number= overrides: the local counter is forced to 7, so the rendered references become Figure. 7 and Figure. 8 in this chapter.

Visibility And List Filtering

Items with truthy hidden values are omitted from list-of-X output. Section-level hidden also propagates to nested items until a subsection overrides it.

Hidden items by attribute

console.log("hidden")

These items render in the document, but should not appear in the list of figures or list of listings.

Hidden sections with visible overrides

Hidden parent section

console.log("hidden by section")

Visible child subsection

console.log("visible again")

Only Figure. 11 and Listing. 7 should appear in the generated lists below.

List Of Figures / Tables / Listings

Use \listoffigures, \listoftables, and \listoflistings to render ordered lists of the currently registered visible items.

List of Figures

1. 1. Caption
2. 2. Two animals shown as subfigures
3. 3. A 2-row subfigure grid with explicit widths on the first row
4. A. A figure with a custom label
5. 7. Manual numbering start
6. 8. Manual numbering continuation
7. 11. Figure visible again

List of Tables

1. 1. Periodic table excerpt
2. 2. Programming languages
3. 3. Example CSV data

List of Listings

1. 1. Hello World in Python
2. 2. Fibonacci function
3. 3. Greeting function
4. 4. Wrapped caption
5. 7. Visible by override

Chapter-Aware Numbering

Because this page enables chapters: true and chaptersDepth: 1, top- level sections act like chapters. Figure, table, equation, and listing numbers reset when a new top-level section begins.

You can see this in the numbering of ??fig:placeholder, Table. 1, Equation. 1, and Listing. 1: each object number is prefixed by the current top-level section number.

Putting It Together

This section cross-references the whole page:

1. ??Fig:placeholder shows basic figure labeling with image sizing. 2. Figure. 2 groups subfigures like Figure. 2a and Figure. 2b. 3. Equation. 1, Equation. 2, and Equation. 3 demonstrate equation labeling, inline \label, and grouped references. 4. Table. 1 and Table. 2 demonstrate numbered tables. 5. Listing. 1, Listing. 2, Listing. 3, and Listing. 4 demonstrate the supported listing syntaxes. 6. Figure. A, Figure. 7, and Figure. 8 demonstrate custom labels and manual counter overrides. 7. Section. 12 and Section. 13 show hidden-item filtering and the generated list-of-X commands.

Configuration Reference

The following YAML keys are currently supported by the plugin and match the current DEFAULTS in src/plugins/crossref-syntax.mjs.

# Titles
figureTitle: "Figure"
tableTitle: "Table"
listingTitle: "Listing"
titleDelim: ":"

# Prefixes (singular, plural)
figPrefix: ["Figure.", "Figures."]
eqnPrefix: ["Equation.", "Equations."]
tblPrefix: ["Table.", "Tables."]
lstPrefix: ["Listing.", "Listings."]
secPrefix: ["Section.", "Sections."]

# Delimiters
rangeDelim: "–"
pairDelim: ", "
lastDelim: ", "
refDelim: ", "

# Numbering schemes
figLabels: "arabic"
subfigLabels: "alpha a"
eqLabels: "arabic"
tblLabels: "arabic"
lstLabels: "arabic"
secLabels: "arabic"
secLevelLabels: null

# Booleans / numbering controls
autoEqnLabels: false
autoSectionLabels: false
chapters: false
chaptersDepth: 1
codeBlockCaptions: true
linkReferences: true
nameInLink: true
numberSections: false
sectionsDepth: -1

# List-of titles
lofTitle: "## List of Figures"
lotTitle: "## List of Tables"
lolTitle: "## List of Listings"

Notes:

• hidden, label, number, width, and height are item-level attributes, not frontmatter config keys.
• \listoffigures, \listoftables, and \listoflistings use the corresponding lo*Title value to generate real section headings with ids and numbering.

True vs false behavior

These four options are easiest to understand by comparing what happens when they are enabled versus disabled.

autoSectionLabels

• true: a heading without {#sec:...} still gets an automatic section id, so this page’s ## Auto-labeled subsection is referenceable as ??sec:auto-labeled-subsection.
• false: only headings with an explicit {#sec:...} label can be referenced; unlabeled headings stay plain headings.

Example:

## My Heading

• with autoSectionLabels: true -> behaves like ## My Heading {#sec:my-heading}
• with autoSectionLabels: false -> no sec: label is created

autoEqnLabels

• true: an unlabeled display equation is still numbered automatically. The unlabeled equation in the Auto equation labels section above is the live example.
• false: display equations are only crossref-numbered when they have a following {#eq:...} block or an inline \label{eq:...}.

Example:

$$
a^2 + b^2 = c^2
$$

• with autoEqnLabels: true -> gets an equation number
• with autoEqnLabels: false -> stays unlabeled for crossref purposes

codeBlockCaptions

• true: listing captions written before or after a fence are parsed as crossref listings. This page demonstrates both forms in Section. 9.2 and Section. 9.3.
• false: only fenced code blocks with explicit fence attributes such as {#lst:hello caption="..."} are treated as listings.

Examples:

Listing: Fibonacci function {#lst:fib}

```python
print("hello")
```

```javascript
const x = 1;
```

: Greeting function {#lst:greet}

• with codeBlockCaptions: true -> both become numbered listings
• with codeBlockCaptions: false -> both stay ordinary code blocks

nameInLink

• true: the whole single reference text becomes the link. This is now the default behavior, so ??fig:placeholder is one clickable unit unless you override it.
• false: only the number is linked, so the rendered output is visually like Figure. <a>1</a> instead of <a>Figure. 1</a>.

Example:

See @fig:placeholder.

• with nameInLink: true -> Figure. 1 is all inside the link
• with nameInLink: false -> only 1 is inside the link

Parity Status

• Supported: figures, subfigures, equations, tables, sections, listings, grouped references, prefix suppression, capitalized references, dotted labels, chapter-aware numbering, chaptersDepth, sectionsDepth, secLevelLabels, manual number= overrides, list-of-X commands, nameInLink, truthy/falsy hidden, hidden inheritance from sections, and wrapping-div listings.
• Partial: some of pandoc-crossref’s more advanced numbering semantics.
• Missing: pandoc’s template system, metadata list injection, and the richer equation formatting options.

Citations

Standard citation: Nash (1950)

In-text citation: (Doe, 2020)

Multiple citations: (Doe, 2020; Nash, 1950)

References