Skip to main content
Version: 3.x.x 🚧

@yozora/tokenizer-link-reference

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

github flavor markdown spec

There are three kinds of reference links: full, collapsed, and shortcut.

A full reference link consists of a link text immediately followed by a link label that matches a link reference definition elsewhere in the document.

A link label begins with a left bracket ([) and ends with the first right bracket (]) that is not backslash-escaped. Between these brackets there must be at least one non-whitespace character. Unescaped square bracket characters are not allowed inside the opening and closing square brackets of link labels. A link label can have at most 999999 characters inside the square brackets.

One label matches another just in case their normalized forms are equal. To normalize a label, strip off the opening and closing brackets, perform the Unicode case fold, strip leading and trailing whitespace and collapse consecutive internal whitespace to a single space. If there are multiple matching reference link definitions, the one that comes first in the document is used. (It is desirable in such cases to emit a warning.)

The link’s URI and title are provided by the matching link reference definition.

A collapsed reference link consists of a link label that matches a link reference definition elsewhere in the document, followed by the string []. The contents of the first link label are parsed as inlines, which are used as the link’s text. The link’s URI and title are provided by the matching reference link definition. Thus, [foo][] is equivalent to [foo][foo].

A shortcut reference link consists of a link label that matches a link reference definition elsewhere in the document and is not followed by [] or a link label. The contents of the first link label are parsed as inlines, which are used as the link’s text. The link’s URI and title are provided by the matching [link reference definition][gfm-link-definiiton]. Thus, [foo] is equivalent to [foo][].

Install

npm install --save @yozora/tokenizer-link-reference

Usage

tip

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

[bar]: /url "title"
`)

Options

NameTypeRequiredDefault
namestringfalse"@yozora/tokenizer-link-reference"
prioritynumberfalseTokenizerPriority.LINKS
  • 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.

    Exception: Delimiters of type full are always processed before other type delimiters.

Types

@yozora/tokenizer-link-reference produce LinkReference type nodes. See @yozora/ast for full base types.

import type {
Association,
Parent,
Reference,
} from '@yozora/ast'

export const LinkReferenceType = 'linkReference'
export type LinkReferenceType = typeof LinkReferenceType

/**
* LinkReference represents a hyperlink through association, or its original
* source if there is no association.
* @see https://github.com/syntax-tree/mdast#linkreference
* @see https://github.github.com/gfm/#reference-link
*/
export interface LinkReference extends
Parent<LinkReferenceType>,
Association,
Reference {}

Live Examples

  • Basic.

    #535
      
      
  • The link text may contain balanced brackets, but not unbalanced ones, unless they are escaped.

      
      
  • The link text may contain inline content.

      
      
  • However, links may not contain other links, at any level of nesting.

      
      
  • The following cases illustrate the precedence of link text grouping over emphasis grouping.

      
      
  • These cases illustrate the precedence of HTML tags, code spans, and autolinks over link grouping.

      
      
  • Matching is case-insensitive.

    #547
      
      
  • Unicode case fold is used.

    #548
      
      
  • Consecutive internal whitespace is treated as one space for purposes of determining matching.

    #549
      
      
  • No whitespace is allowed between the link text and the link label.

      
      
  • When there are multiple matching link reference definitions, the first is used.

    #552
      
      
  • Note that matching is performed on normalized strings, not parsed inline content. So the following does not match, even though the labels define equivalent inline content.

    #553
      
      
  • Link labels cannot contain brackets, unless they are backslash-escaped.

      
      
  • Note that in this example ] is not backslash-escaped.

    #558
      
      
  • A link label must contain at least one non-whitespace character.

      
      
  • Basic.

      
      
  • The link labels are case-insensitive.

    #563
      
      
  • As with full reference links, whitespace is not allowed between the two sets of brackets.

    #564
      
      
  • Basic.

      
      
  • The link labels are case-insensitive.

    #569
      
      
  • A space after the link text should be preserved.

    #570
      
      
  • If you just want bracketed text, you can backslash-escape the opening bracket to avoid links.

    #571
      
      
  • Note that this is a link, because a link label ends with the first following closing bracket.

    #572
      
      
  • Full and compact references take precedence over shortcut references.

      
      
  • Inline links also take precedence.

      
      
  • In the following case [bar][baz] is parsed as a reference, [foo] as normal text.

    #577
      
      
  • Here, though, [foo][bar] is parsed as a reference, since [bar] is defined.

    #578
      
      
  • Here [foo] is not parsed as a shortcut reference, because it is followed by a link label (even though [bar] is not defined).

    #579