marked.js 的自定义拓展 (Custom Extensions : extensions)

  1. 1. 作用
  2. 2. 自定义拓展 : extensions
  • Custom Extensions : extensions
    1. 1. Heading

  • 官方文档:https://marked.js.org/using_pro#extensions

    作用

    用于自定义解析标签Markdown的标签,简单对官方文档进行翻译,我使用的是vue3 + ts ,简单写了一个适配

    自定义拓展 : extensions

    您可以为选项对象提供一个扩展数组。 该数组可以包含任意数量的扩展对象,使用以下属性:

    • name
      用于标识将由此扩展处理的令牌的字符串。
      如果该名称与现有扩展名称或上面列出的分词器/渲染器方法中的现有方法相匹配,它们将覆盖先前分配的行为,并优先考虑最后分配的扩展。 扩展可以返回 false 以回退到以前的行为。

    • level
      一个字符串,用于确定何时运行扩展分词器, 值: ‘block’ 或 ‘inline’.
      块级扩展将在上面列出的任何块级分词器方法之前处理,并且通常由“容器类型”文本(段落、表格、块引用等)组成。
      内联级扩展将在每个块级标记内处理,在上面列出的任何内联级分词器方法之前。 这些通常由“样式类型”文本(斜体、粗体等)组成。

    • start(string src)
      返回自定义标记的下一个可能开始的索引的函数。
      索引可以是 src.match().index 的结果,甚至是简单的 src.index()。 Marked 将使用此函数来确保它不会跳过任何应该属于自定义标记的文本。

    • tokenizer(string src, array tokens)
      读取 Markdown 文本字符串并返回生成的标记的函数。 令牌模式应该在 src 字符串的开头找到。 因此,如果使用正则表达式检测标记,则应将其锚定到字符串开头 (^)。 tokens 参数包含到那时由词法分析器生成的令牌数组,例如,可用于访问先前的令牌。
      返回值应该是具有以下参数的对象:

      • type
        与上面的name相同
      • raw
        一个字符串,包含此标记从源中使用的所有文本。
      • tokens [optional]
        默认情况下将由 walkTokens 函数遍历的子令牌数组。

      返回的令牌还可以包含您选择的自定义渲染器可能需要访问的任何其他自定义参数。
      tokenizer 函数可以访问 this 对象中的词法分析器,如果需要进一步解析字符串的任何内部部分,例如处理块标记中文本的任何内联语法,则可以使用它。 可能有用的关键功能包括:

      • this.lexer.blockTokens(string text, array tokens)
        这将在提供的文本上运行块分词器函数(包括任何块级扩展),并将任何生成的标记附加到标记数组中。 令牌数组也由函数返回。 例如,如果您的扩展程序创建了一个“容器”类型的标记(例如块引用),并且可能在其中包含其他块级标记,您可能会使用它。
      • this.lexer.inline(string text, array tokens)
        仅在生成所有块级令牌后才会解析内联级令牌。 此函数将文本和标记添加到队列中,以便在后面的步骤中使用内联级分词器(包括任何内联级扩展)进行处理。 将使用提供的文本生成令牌,并且任何生成的令牌都将附加到令牌数组。 请注意,此函数确实返回任何内容,因为在块级处理完成之前内联处理不会发生。
        -this.lexer.inlineTokens(string text, array tokens)
        有时,内联级别标记包含更多嵌套的内联标记(例如**strong**)
        一个里面的令牌### Heading
        这将在提供的文本上运行内联分词器函数(包括任何内联级扩展),并将任何生成的标记附加到标记数组中。 令牌数组也由函数返回。
    • renderer(object token)
      读取标记并返回生成的 HTML 输出字符串的函数。
      渲染器函数可以访问 this 对象中的解析器,如果令牌的任何部分需要进一步解析,例如任何子令牌,都可以使用它。 可能有用的关键功能包括:

      • this.parser.parse(array tokens)
        在提供的标记数组上运行块渲染器函数(包括任何扩展),并返回生成的 HTML 字符串输出。 这用于从任何子块级令牌生成 HTML,例如,如果您的扩展是一个“容器”类型的令牌(例如块引用),它可能在其中包含其他块级令牌。
      • this.parser.parseInline(array tokens)
        在提供的标记数组上运行内联渲染器函数(包括任何扩展),并返回生成的 HTML 字符串输出。 这用于从任何子内联级标记生成 HTML。
    • childTokens [optional]
      一个字符串数组,匹配 walkTokens 函数应遍历的任何令牌参数的名称。 例如,如果您想要使用第二个自定义参数来包含除令牌之外的子令牌,则可以在此处列出。 如果提供了 childTokens,则默认不会遍历 tokens 数组,除非它也包含在 childTokens 数组中。


    原文

    Custom Extensions : extensions

    You may supply an array to the object. This array can contain any number of objects, using the following properties:extensionsoptionsextension

    name
    A string used to identify the token that will be handled by this extension.
    If the name matches an existing extension name, or an existing method in the tokenizer/renderer methods listed above, they will override the previously assigned behavior, with priority on the extension that was assigned last. An extension can return to fall back to the previous behavior.false

    level
    A string to determine when to run the extension tokenizer. Must be equal to ‘block’ or ‘inline’.
    A block-level extension will be handled before any of the block-level tokenizer methods listed above, and generally consists of ‘container-type’ text (paragraphs, tables, blockquotes, etc.).

    An inline-level extension will be handled inside each block-level token, before any of the inline-level tokenizer methods listed above. These generally consist of ‘style-type’ text (italics, bold, etc.).

    start(string src)
    A function that returns the index of the next potential start of the custom token.
    The index can be the result of a , or even a simple . Marked will use this function to ensure that it does not skip over any text that should be part of the custom token.src.match().indexsrc.index()

    tokenizer(string src, array tokens)
    A function that reads string of Markdown text and returns a generated token. The token pattern should be found at the beginning of the string. Accordingly, if using a Regular Expression to detect a token, it should be anchored to the string start (^). The parameter contains the array of tokens that have been generated by the lexer up to that point, and can be used to access the previous token, for instance. srctokens
    The return value should be an object with the following parameters:

    type
    A string that matches the parameter of the extension.name
    raw
    A string containing all of the text that this token consumes from the source.
    tokens [optional]
    An array of child tokens that will be traversed by the function by default.walkTokens
    The returned token can also contain any other custom parameters of your choice that your custom might need to access.renderer

    The tokenizer function has access to the lexer in the object, which can be used if any internal section of the string needs to be parsed further, such as in handling any inline syntax on the text within a block token. The key functions that may be useful include:this

    this.lexer.blockTokens(string text, array tokens)
    This runs the block tokenizer functions (including any block-level extensions) on the provided text, and appends any resulting tokens onto the array. The array is also returned by the function. You might use this, for example, if your extension creates a “container”-type token (such as a blockquote) that can potentially include other block-level tokens inside.tokenstokens
    this.lexer.inline(string text, array tokens)
    Parsing of inline-level tokens only occurs after all block-level tokens have been generated. This function adds and to a queue to be processed using inline-level tokenizers (including any inline-level extensions) at that later step. Tokens will be generated using the provided , and any resulting tokens will be appended to the array. Note that this function does NOT return anything since the inline processing cannot happen until the block-level processing is complete.texttokenstexttokens
    this.lexer.inlineTokens(string text, array tokens)
    Sometimes an inline-level token contains further nested inline tokens (such as a token inside of a ). This runs the inline tokenizer functions (including any inline-level extensions) on the provided text, and appends any resulting tokens onto the array. The array is also returned by the function.
    strong
    Click to Copy

    Heading

    Click to Copy
    tokenstokens
    renderer(object token)
    A function that reads a token and returns the generated HTML output string.
    The renderer function has access to the parser in the object, which can be used if any part of the token needs needs to be parsed further, such as any child tokens. The key functions that may be useful include:this

    this.parser.parse(array tokens)
    Runs the block renderer functions (including any extensions) on the provided array of tokens, and returns the resulting HTML string output. This is used to generate the HTML from any child block-level tokens, for example if your extension is a “container”-type token (such as a blockquote) that can potentially include other block-level tokens inside.
    this.parser.parseInline(array tokens)
    Runs the inline renderer functions (including any extensions) on the provided array of tokens, and returns the resulting HTML string output. This is used to generate the HTML from any child inline-level tokens.
    childTokens [optional]
    An array of strings that match the names of any token parameters that should be traversed by the functions. For instance, if you want to use a second custom parameter to contain child tokens in addition to , it could be listed here. If is provided, the array will not be walked by default unless it is also included in the array.walkTokenstokenschildTokenstokenschildTokens
    Example: Add a custom syntax to generate description lists.