pandoc-crossref Parity Test Page:

This page is a live demo of the pandoc-crossref-style features currently implemented by remark-crossref. It also calls out the current plugin defaults so the examples can be read against the behavior you get without extra configuration.

The defaults shown later in Configuration Reference reflect the current values in src/plugins/crossref-syntax.mjs.

Quick checks:

Single references link the whole label text, for example Figure. 1.
Figures, tables, equations, listings, and sections all participate in the same reference system.
Top-level sections act as chapters, so objects reset per major section.

Figures

A figure is an image by itself in a paragraph with a trailing attribute block such as {#fig:label}.

Basic figure:

**Figure 1:** A placeholder figure used to demonstrate figure labeling

Reference it with Figure. 1.

Width and height attributes:

See Figure. 2, Figure. 3, and Figure. 4.

Subfigures

Wrap several labeled images in a <div id="fig:...">. The last paragraph becomes the parent caption, and each labeled image receives a subfigure letter.

Reference the whole group with Figure. 5. Reference the children with Figure. 5a and Figure. 5b.

Rows and width-driven grids

Each paragraph inside the wrapper becomes a row. Width attributes on the images in a row become grid-template-columns values.

This also demonstrates dotted labels: Figure. 6a and Figure. 6d.

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:

E = m c^{2} (1)

Reference: Equation. 1.

Equation labeled inside the math:

\nabla \times E = - \frac{\partial B}{\partial t} (2)

Reference: Equation. 2.

Another explicit equation for grouped references:

\int_{- \infty}^{\infty} e^{- x^{2}} d x = π (3)

Reference: Equation. 3.

Auto equation labels

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

a^{2} + b^{2} = c^{2}

Tables

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

Element	Symbol	Number
Hydrogen	H	1
Helium	He	2
Lithium	Li	3

Table 1: Periodic table excerpt

See Table. 1.

Language	Year	Creator
C	1972	Dennis Ritchie
Python	1991	Guido van Rossum
JavaScript	1995	Brendan Eich

Table 2: Programming languages

Compare Table. 1 and Table. 2.

Sections

Sections can use explicit labels or rely on autoSectionLabels.

Explicit section labels: Section. 1, Section. 2, Section. 3.
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.

Code Listings

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

Caption attribute on the fence

Listing 1: Hello World in Python

print("Hello, World!")

Reference: Listing. 1.

Table-style caption before the block

Listing 2: Fibonacci function

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

Reference: Listing. 2.

Table-style caption after the block

Listing 3: Greeting function

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

Reference: Listing. 3.

Wrapping div syntax

Listing 4: Wrapped caption

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: Figure. 1
Equation: Equation. 1
Table: Table. 1
Listing: Listing. 1
Section: Section. 1

Capitalized references

Figure. 1 is a placeholder figure.
Equation. 1 is Einstein’s equation.
Table. 1 lists elements.
Section. 7 covers cross-references.

Prefix suppression

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

Figure 1 is the first figure in this section.
Equation 1 is the first equation here.

Grouped references and ranges

Figures: Figures. 1, 2
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=.

**Figure A:** A figure with a custom label

Reference: Figure. A uses the custom label A.

**Figure 8:** Manual numbering continuation

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

Listing 5: Hidden listing

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

Listing 6: Hidden by section

console.log("hidden by section")

Visible child subsection

Listing 7: Visible by override

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. A placeholder figure used to demonstrate figure labeling
2. Width only
3. Height only
4. Width and height together
5. Two animals shown as subfigures
6. A 2-row subfigure grid with explicit widths on the first row
A. A figure with a custom label
7. Manual numbering start
8. Manual numbering continuation
11. Figure visible again

List of Listings

1. Hello World in Python
2. Fibonacci function
3. Greeting function
4. Wrapped caption
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 Figure. 1, 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:

Figure. 1 shows basic figure labeling with image sizing. 2. Figure. 5 groups subfigures like Figure. 5a and Figure. 5b. 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. 9 and Section. 10 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. 6.2 and Section. 6.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 Figure. 1 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.