@yozora/tokenizer-heading

github flavor markdown spec

An ATX heading consists of a string of characters, parsed as inline content, between an opening sequence of 1-6 unescaped # characters and an optional closing sequence of any number of unescaped # characters. The opening sequence of # characters must be followed by a space or by the end of line. The optional closing sequence of #s must be preceded by a space and may be followed by spaces only. The opening # character may be indented 0-3 spaces. The raw contents of the heading are stripped of leading and trailing spaces before being parsed as inline content. The heading level is equal to the number of # characters in the opening sequence.

• See github flavor markdown spec for details.
• See Live Examples for an intuitive impression.

Install

npm

npm install --save @yozora/tokenizer-heading

Yarn

yarn add @yozora/tokenizer-heading

pnpm

pnpm add @yozora/tokenizer-heading

Usage

tip

@yozora/tokenizer-heading has been integrated into @yozora/parser / @yozora/parser-gfm-ex / @yozora/parser-gfm, so you can use YozoraParser / GfmExParser / GfmParser directly.

Basic Usage

@yozora/tokenizer-heading cannot be used alone, it needs to be registered in Parser as a plugin-in before it can be used.

import { DefaultParser } from '@yozora/core-parser'
import ParagraphTokenizer from '@yozora/tokenizer-paragraph'
import TextTokenizer from '@yozora/tokenizer-text'
import HeadingTokenizer from '@yozora/tokenizer-heading'

const parser = new DefaultParser()
  .useFallbackTokenizer(new ParagraphTokenizer())
  .useFallbackTokenizer(new TextTokenizer())
  .useTokenizer(new HeadingTokenizer())

// parse source markdown content
parser.parse(`
# h1
## h2
### h3
#### h4
##### h5
###### h6
`)

YozoraParser

import YozoraParser from '@yozora/parser'

const parser = new YozoraParser()

// parse source markdown content
parser.parse(`
# h1
## h2
### h3
#### h4
##### h5
###### h6
`)

GfmParser

import GfmParser from '@yozora/parser-gfm'

const parser = new GfmParser()

// parse source markdown content
parser.parse(`
# h1
## h2
### h3
#### h4
##### h5
###### h6
`)

GfmExParser

import GfmExParser from '@yozora/parser-gfm-ex'

const parser = new GfmExParser()

// parse source markdown content
parser.parse(`
# h1
## h2
### h3
#### h4
##### h5
###### h6
`)

Options

Name	Type	Required	Default
name	string	false	"@yozora/tokenizer-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 the match-block stage, a high-priority tokenizer can interrupt the matching process of a low-priority tokenizer.

Types

@yozora/tokenizer-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

  #32

  yozora

    

  pretty-json

    

  # foo ## foo ### foo #### foo ##### foo ###### foo

  1
  2
  3
  4
  5
  6
  # foo
  ## foo
  ### foo
  #### foo
  ##### foo
  ###### foo

• More than six # characters is not a heading.

  #33

  yozora

    

  pretty-json

    

  ####### foo

  1
  ####### foo

• At least one space is required between the # characters and the heading’s contents, unless the heading is empty.

  #34

  yozora

    

  pretty-json

    

  #5 bolt #hashtag

  1
  2
  3
  #5 bolt
  
  #hashtag

• This is not a heading, because the first # is escaped.

  #35

  yozora

    

  pretty-json

    

  \## foo

  1
  \## foo

• Contents are parsed as inlines.

  #36

  yozora

    

  pretty-json

    

  # foo *bar* \*baz\*

  1
  # foo *bar* \*baz\*

• Leading and trailing whitespace is ignored in parsing inline content.

  #37

  yozora

    

  pretty-json

    

  # foo

  1
  #                  foo                     

• One to three spaces indentation are allowed.

  #38

  yozora

    

  pretty-json

    

  ### foo ## foo # foo

  1
  2
  3
   ### foo
    ## foo
     # foo

• Four spaces are too much.

  #39

  yozora

    

  pretty-json

    

  # foo

  1
      # foo

• A closing sequence of # characters is optional.

  #41

  yozora

    

  pretty-json

    

  ## foo ## ### bar ###

  1
  2
  ## foo ##
    ###   bar    ###

• It need not be the same length as the opening sequence.

  #42

  yozora

    

  pretty-json

    

  # foo ################################## ##### foo ##

  1
  2
  # foo ##################################
  ##### foo ##

• Spaces are allowed after the closing sequence.

  #43

  yozora

    

  pretty-json

    

  ### foo ###

  1
  ### foo ###     

• A sequence of # characters with anything but spaces following it is not a closing sequence, but counts as part of the contents of the heading.

  #44

  yozora

    

  pretty-json

    

  ### foo ### b

  1
  ### foo ### b

• The closing sequence must be preceded by a space.

  #45

  yozora

    

  pretty-json

    

  # foo#

  1
  # foo#

• Backslash-escaped # characters do not count as part of the closing sequence.

  #46

  yozora

    

  pretty-json

    

  ### foo \### ## foo #\## # foo \#

  1
  2
  3
  ### foo \###
  ## foo #\##
  # foo \#

• ATX headings need not be separated from surrounding content by blank lines, and they can interrupt paragraphs.

  #47

  yozora

    

  pretty-json

    

  **** ## foo ****

  1
  2
  3
  ****
  ## foo
  ****

• ATX headings can be empty.

  #49

  yozora

    

  pretty-json

    

  ## # ### ###

  1
  2
  3
  ## 
  #
  ### ###

Related

• @yozora/ast
• @yozora/parser
• @yozora/parser-gfm
• @yozora/parser-gfm-ex
• @yozora/tokenizer-setext-heading
• @yozora/react-heading
• @yozora/react-markdown
• Sourcecode
• Heading | Yozora AST
• ATX Heading | Github Flavor Markdown Spec
• Heading | Mdast