markdown-it-auto-parnum
v2.0.0
Published
A markdown-it plugin for automatic paragraph numbering.
Downloads
5
Readme
Paragraph numbering for Markdown
This markdown-it plugin numbers paragraphs automatically.
Installation
yarn add markdown-it-auto-parnum
Usage
const md = require('markdown-it')()
.use(require('markdown-it-auto-parnum'))
md.render('This is a paragraph.')
Options
This library has several options, most of which should not be needed under normal circumstances. These are (with their default values):
- sign ('¶'): The sign used in Markdown files for manual numbering of paragraphs, and rendered as html attributes in the resulting html. Changing this setting will break cross-compatibility for Markdown documents.
- delimiter ('.'): The character that will separate multi-level numbering schemes when none is explicitly provided in the Markdown.
- addLinks (true): Whether the anchors for paragraphs should be rendered as links.
- headingLevels (1): The maximum number of headings to include in multi-level paragraph numbers, unless explicitly specified in a document.
- headingSign (''): A symbol or text that should be placed in the html id attribute given to numbered headings. For example, if this is set to "sec", the headers will be rendered with
id="sec1"
. - numberedElements ('p'): A comma-separated list of HTML elements or markdown-it token types which should receive paragraph numbers. Only block-level elements can receive paragraph numbers. To give each fenced code block a paragraph number, one could set this to
'p,fence'
, wherep
is the HTML tag andfence
is the markdown-it token type. - skippedElements ('footnote_block'): A comma-separted list of markdown-it token types only inside which any paragraphs should not be numbered. Only block-level elements with nesting can be skipped. To number blockquotes but not the paragraphs inside them, one could set the options
{ numberedElements: 'paragraph,blockquote', skippedElements: 'blockquote' }
.
Multi-level numbering
If no numbering scheme is explicitly set within a document, this library will try to determine the best numbering scheme based on its headings. The algorithm for this is to number:
- ...the lowest-level heading, i.e. h1, then h2, etc.
- ...which occurs more than once in the document
- ...up to the headingLevels setting.
So, by default a document with a single h1
and multiple h2
and h3
elements will receive paragraph numbers like 1.1
, where the first number is incremented with each h2
element.
Explicit numbering within a document
Within a markdown document, numbering for a given paragraph or heading may be explicitly specified by adding the html attribute "¶". Using the markdown-it-attrs plugin, this would look like {¶=123}
at the end of a block of text. For multi-level numbering, any non-numeric characters in a specified paragraph number will set the scheme for subsequent paragraph numbering; for example, if the first paragraph is numbered as {¶=1:1}
then the next paragraph will automatically be numbered 1:2
, and the next numbered heading will be 2
, and the following paragraph 2:1
, etc.
There are also a few control words for altering the automated paragraph numbering:
¶=manual
: For subsequent paragraphs, number only the ones that are explicitly specified in the Markdown.¶=auto
or¶=start
or¶=on
: Number subsequent paragraphs automatically.¶=stop
or¶=off
: Do not number subsequent paragraphs until numbering is turned on with an explicit number orauto
,start
, oron
.¶=skip
or¶=none
: Skip numbering for the specified paragraph only.