Skip to main content
Version: 2.x.x

@yozora/tokenizer-setext-heading

Npm VersionNpm DownloadNpm LicenseModule formats: cjs, esmNode.js VersionTested with JestCode Style: prettier

github flavor markdown spec

A setext heading consists of one or more lines of text, each containing at least one non-whitespace character, with no more than 33 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 33 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 11 heading if = characters are used in the setext heading underline, and a level 22 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.

Install

npm install --save @yozora/tokenizer-setext-heading

Usage

tip

@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.

import YozoraParser from '@yozora/parser'

const parser = new YozoraParser()

// parse source markdown content
parser.parse(`
Foo *bar*
=========

Foo *bar*
---------
`)

Options

NameTypeRequiredDefault
namestringfalse"@yozora/tokenizer-setext-heading"
prioritynumberfalseTokenizerPriority.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 the match-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 { Parent } 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 Parent<HeadingType> {
/**
* HTML anchor identifier.
*/
identifier?: string
/**
* level of heading
*/
depth: 1 | 2 | 3 | 4 | 5 | 6
}

Live Examples

  • Basic.

    #50
      
      
  • The content of the header may span more than one line.

    #51
      
      
  • 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.

    #52
      
      
  • The underlining can be any length

    #53
      
      
  • The heading content can be indented up to three spaces, and need not line up with the underlining.

    #54
      
      
  • Four spaces indent is too much

      
      
  • The setext heading underline can be indented up to three spaces, and may have trailing spaces.

    #56
      
      
  • The setext heading underline cannot contain internal spaces.

    #58
      
      
  • Trailing spaces in the content line do not cause a line break.

    #59
      
      
  • Nor does a backslash at the end.

    #60
      
      
  • Since indicators of block structure take precedence over indicators of inline structure, the following are setext headings.

    #61
      
      
  • 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.

    #65
      
      
  • But in general a blank line is not required before or after setext headings.

    #66
      
      
  • Setext headings cannot be empty.

    #67
      
      
  • 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.

    #72
      
      
  • 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.

    #76