Plugins Numbering

cite and cross-reference @mdsvex/plugin-numbering@0.1.0-next.1

Numbering

Numbering, numbered figures, tables, equations and sections, and :ref[fig:x] references that read as the number

Install

pnpm add -D @mdsvex/plugin-numbering@next @mdsvex/plugin-figures@next

Turn it on

import { figures } from '@mdsvex/plugin-figures';
import { numbering } from '@mdsvex/plugin-numbering';

mdsvex({ heading_ids: true, plugins: [figures(), numbering()] });

What it reads

:ref[sec:id]

owns ref, table · acts on code blocks, headings · reads figure from another plugin · reads the whole document

An example

You write
:::figure[Sales by month](id=fig:sales)
A chart.
:::

Sales rose in March, as :ref[fig:sales] shows.

You get

A chart.

Figure 1: Sales by month

Sales rose in March, as Figure 1 shows.

Build-time preview.

Numbers figures, tables, equations and sections, and turns :ref[id] into a link that reads as the number, in the way of pandoc-crossref. The prefix of an id says what it is:

## Results

:::figure[Sales by month](id=fig:sales)
![A bar chart of sales by month](./sales.png)
:::

:::table[What each plan costs](id=tbl:plans)
| plan | price |
| --- | --- |
| free | 0 |
:::

```math id=eq:energy
E = mc^2
```

Sales rose in March (:ref[fig:sales]), the plans are in :ref[tbl:plans], :ref[eq:energy] gives the energy and :ref[sec:results] has the rest.
<figure id="tbl:plans" class="table">
	<figcaption><span class="table-number">Table 1</span>: What each plan costs</figcaption>
	<table>...</table>
</figure>
<p>
	Sales rose in March (<span class="ref"><a href="#fig:sales">Figure 1</a></span>), the plans are in
	<span class="ref"><a href="#tbl:plans">Table 1</a></span>, <span class="ref"><a href="#eq:energy">Equation 1</a></span>
	gives the energy and <span class="ref"><a href="#results">Section 1</a></span> has the rest.
</p>
numbering({
	prefixes: { fig: ['Figure', 'Figures'], tbl, eq, sec }, // the word for one and for several, by kind
	and: 'and', // what joins the last two numbers
	number_sections: boolean = false, // the number in front of each heading
	section_depth: number = 2 // the depth of the headings numbered 1, 2, 3
});
  • fig: is the :::figure[Caption](id=fig:x) of @mdsvex/plugin-figures, tbl: is :::table[Caption](id=tbl:x) around a table, eq: is a math fence with id=eq:x in its meta and sec: is a heading, sec: and its id. Each kind counts on its own, in document order.
  • A figure or table is numbered when it has an id with its prefix, with a caption or without. The figures plugin owns the figure and renders its number, this plugin observes it.
  • An equation gets its number as \tag{n}, which the math renderer shows beside it, inside a <div class="equation"> with its id.
  • :ref[fig:a, fig:b] reads "Figures 1 and 2", the plural word, each number a link. A reference to an id that is not there is a warning and reads "Figure ?".
  • prefix replaces the word: :ref[fig:sales](prefix=Chart) reads "Chart 1" and prefix="Bar chart" "Bar chart 1", the word as written, so a reference to several ids takes the plural. Only the literal prefix=false leaves the word out, "1" or "1 and 2". A capital for the start of a sentence is a word too, prefix=Fig. beside prefixes: { fig: ['fig.', 'figs.'] }.
  • Ids of different kinds in one reference are a warning. It reads each kind with its own word, "Figure 1 and Table 1", and ignores a written prefix.
  • In a streaming view a number is known when its target closes, and never changes. A reference to a target that has not arrived reads "Figure ?" until it does. Components read the numbers from plugin data, plugin_data.numbering['target:' + id], through Svelte context.

A reference component of your own can read the same way the plugin's does with ref_parts from @mdsvex/plugin-numbering. It takes the ids, the words, and a function that finds a target, and returns the pieces of the text, each { text, href? }:

import { AND, PREFIXES, ref_parts } from '@mdsvex/plugin-numbering';

ref_parts(['fig:a', 'fig:b'], { prefixes: PREFIXES, and: AND }, (id) => numbering['target:' + id]);
// [{ text: 'Figures ' }, { text: '1', href: '#fig:a' }, { text: ' and ' }, { text: '2', href: '#fig:b' }]

prefix in the words is the prefix arg, a word, false or undefined.

Options, from its types 4

prefixes?: Partial<Prefixes>
The word in front of the numbers of each kind, for one and for several, a reference with a prefix arg uses that word in its place
and?: string = 'and'
What joins the last two numbers of a reference
number_sections?: boolean
Puts the number of each heading in front of it, 1, 1.1, 1.2, off by default, references to sections read the number either way
section_depth?: number = 2
The depth of the headings numbered 1, 2, 3, deeper ones are 1.1 and so on, shallower ones are not numbered

mdsvex, markdown with Svelte in it. MIT licence.