@yozora/tokenizer-setext-heading
A setext heading consists of one or more lines of text, each containing at least one non-whitespace character, with no more than spaces indentation, followed by a setext heading underline. The lines of text must be such that, were they not followed by the setext heading underline, they would be interpreted as a paragraph: they cannot be interpretable as a code fence, ATX heading, block quote, thematic break, list item, or HTML block.
A setext heading underline is a sequence of =
characters or a sequence of -
characters, with no more than spaces
indentation and any number of trailing spaces. If a line containing a single -
can be interpreted as an empty list items, it should be
interpreted this way and not as a setext heading underline.
The heading is a level heading if =
characters are used in the
setext heading underline, and a level
heading if -
characters are used. The contents of the heading are the result
of parsing the preceding lines of text as CommonMark inline content.
In general, a setext heading need not be preceded or followed by a blank line. However, it cannot interrupt a paragraph, so when a setext heading comes after a paragraph, a blank line is needed between them.
- See github flavor markdown spec for details.
- See Live Examples for an intuitive impression.
Install
- npm
- Yarn
- pnpm
npm install --save @yozora/tokenizer-setext-heading
yarn add @yozora/tokenizer-setext-heading
pnpm add @yozora/tokenizer-setext-heading
Usage
@yozora/tokenizer-setext-heading has been integrated into @yozora/parser / @yozora/parser-gfm-ex / @yozora/parser-gfm,
so you can use YozoraParser
/ GfmExParser
/ GfmParser
directly.
- Basic Usage
- YozoraParser
- GfmParser
- GfmExParser
@yozora/tokenizer-setext-heading cannot be used alone, it needs to be registered in YastParser as a plugin-in before it can be used.
import { DefaultYastParser } from '@yozora/core-parser'
import ParagraphTokenizer from '@yozora/tokenizer-paragraph'
import TextTokenizer from '@yozora/tokenizer-text'
import SetextHeadingTokenizer from '@yozora/tokenizer-setext-heading'
const parser = new DefaultYastParser()
.useBlockFallbackTokenizer(new ParagraphTokenizer())
.useInlineFallbackTokenizer(new TextTokenizer())
.useTokenizer(new SetextHeadingTokenizer())
// parse source markdown content
parser.parse(`
Foo *bar*
=========
Foo *bar*
---------
`)
import YozoraParser from '@yozora/parser'
const parser = new YozoraParser()
// parse source markdown content
parser.parse(`
Foo *bar*
=========
Foo *bar*
---------
`)
import GfmParser from '@yozora/parser-gfm'
const parser = new GfmParser()
// parse source markdown content
parser.parse(`
Foo *bar*
=========
Foo *bar*
---------
`)
import GfmExParser from '@yozora/parser-gfm-ex'
const parser = new GfmExParser()
// parse source markdown content
parser.parse(`
Foo *bar*
=========
Foo *bar*
---------
`)
Options
Name | Type | Required | Default |
---|---|---|---|
name | string | false | "@yozora/tokenizer-setext-heading" |
priority | number | false | TokenizerPriority.ATOMIC |
-
name
: The unique name of the tokenizer, used to bind the token it generates, to determine the tokenizer that should be called in each life cycle of the token in the entire matching / parsing phase. -
priority
: Priority of the tokenizer, determine the order of processing, high priority priority execution. interruptable. In addition, in thematch-block
stage, a high-priority tokenizer can interrupt the matching process of a low-priority tokenizer.
Types
@yozora/tokenizer-setext-heading produce Heading type nodes. See @yozora/ast for full base types.
import type { YastParent } from '@yozora/ast'
export const HeadingType = 'heading'
export type HeadingType = typeof HeadingType
/**
* Heading represents a heading of a section.
* @see https://github.com/syntax-tree/mdast#heading
* @see https://github.github.com/gfm/#atx-heading
*/
export interface Heading extends YastParent<HeadingType> {
/**
* HTML anchor identifier.
*/
identifier?: string
/**
* level of heading
*/
depth: 1 | 2 | 3 | 4 | 5 | 6
}
Live Examples
-
Basic.
-
The content of the header may span more than one line.
-
The contents are the result of parsing the headings’s raw content as inlines. The heading’s raw content is formed by concatenating the lines and removing initial and final whitespace.
-
The underlining can be any length
-
The heading content can be indented up to three spaces, and need not line up with the underlining.
-
Four spaces indent is too much
-
The setext heading underline can be indented up to three spaces, and may have trailing spaces.
-
The setext heading underline cannot contain internal spaces.
-
Trailing spaces in the content line do not cause a line break.
-
Nor does a backslash at the end.
-
Since indicators of block structure take precedence over indicators of inline structure, the following are setext headings.
-
The setext heading underline cannot be a lazy continuation line in a list item or block quote.
-
A blank line is needed between a paragraph and a following setext heading, since otherwise the paragraph becomes part of the heading’s content.
-
But in general a blank line is not required before or after setext headings.
-
Setext headings cannot be empty.
-
Setext heading text lines must not be interpretable as block constructs other than paragraphs. So, the line of dashes in these examples gets interpreted as a thematic break.
-
If you want a heading with > foo as its literal text, you can use backslash escapes.
-
Authors who want interpretation 2 can put blank lines around the thematic break or use a thematic break that cannot count as a setext heading underline.
-
Authors who want interpretation 3 can use backslash escapes.