DOCSEARCHbyAlgolia
Submit Docs

goldmark Documentation

repository·master·Indexed 24 days ago

https://github.com/yuin/goldmark

goldmark is a highly extensible, standards-compliant Markdown parser written in pure Go, designed to be CommonMark 0.31.2 compliant. It provides an AST-based structure that preserves source positions and supports various extensions including GFM (Tables, Strikethrough, Linkify, TaskList), Definition Lists, Footnotes, Typographer, and CJK support. The library allows for custom configuration of parsers, renderers, and extensions via functional options.

Tokens
17.6K
Snippets
45
Records
98
Agent score
89%

What's inside goldmark

  1. Markdown Parsing Strategy: Two-Phase Approach

    master

    CommonMark-compliant parsers (like goldmark) typically use a two-phase parsing strategy to convert Markdown into a document tree:

    Phase 1: Block Structure

    Lines of input are consumed to construct the document's block structure (e.g., paragraphs, block quotes, lists).

    • Process: The parser iterates through open blocks, checking if the current line satisfies the block's conditions (e.g., a > for block quotes).
    • Result: A tree of blocks is created. The last child of a block is usually 'open', allowing subsequent lines to be added to it (lazy continuation).

    Phase 2: Inline Structure

    Once the block structure is complete, the parser 'walks the tree' and parses the raw text within paragraphs and headings into inline elements (e.g., strings, code spans, links, emphasis).

    • Link Resolution: Link reference definitions parsed in Phase 1 are used to resolve links during this phase.

  2. Configure goldmark with custom Parser, Renderer, and Extensions

    master

    To use specific extensions (like GFM), custom parser options, or custom renderer options, use goldmark.New() to create a new instance of the parser.

    Note on Option Ordering:

    • goldmark.WithParser must be passed before goldmark.WithParserOptions and goldmark.WithExtensions.
    • goldmark.WithRenderer must be passed before goldmark.WithRendererOptions and goldmark.WithExtensions.
    import (
    "bytes"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark/renderer/html"
)

md := goldmark.New(
          goldmark.WithExtensions(extension.GFM),
          goldmark.WithParserOptions(
              parser.WithAutoHeadingID(),
          ),
          goldmark.WithRendererOptions(
              html.WithHardWraps(),
              html.WithXHTML(),
          ),
      )
var buf bytes.Buffer
if err := md.Convert(source, &buf); err != nil {
    panic(err)
}

  3. Create Thematic Breaks (Horizontal Rules)

    master

    A thematic break is created by a line consisting of 0-3 spaces of indentation, followed by a sequence of three or more matching -, _, or * characters. Each character can be optionally followed by any number of spaces or tabs.

    Rules for Thematic Breaks:

    • Valid Characters: Only -, _, or * are allowed. All non-whitespace characters in the line must be the same.
    • Indentation: 0-3 spaces of indentation are allowed. 4 or more spaces will result in a code block instead.
    • Character Count: Must have at least three characters.
    • Spacing: Spaces are allowed between the characters and at the end of the line.
    • Precedence: If a line of dashes could be interpreted as a setext heading, the heading takes precedence. If it could be a list item, the thematic break takes precedence.
    • Placement: They do not require blank lines before or after and can interrupt a paragraph.
    ***
---
___

  ***

 - - -

  4. Create list items starting with a blank line

    master

    A list item can start with a single blank line. If a sequence of lines starts with a blank line, the list marker is prepended to the first line, and subsequent lines are indented by the width of the marker plus one space.

    Note: A list item can begin with at most one blank line. If you use two blank lines, the subsequent text will not be part of the list item.

    Example of a list item starting with a blank line:

    - 
  foo

    Example of a list item that is empty:

    - foo
- 
- bar

  5. Understand HTML block behavior in Markdown

    master

    Markdown supports several types of HTML blocks. The behavior of these blocks depends on how the tags are formatted:

    • Type 1-6 Blocks: These typically end at the first blank line or the end of the document. They can interrupt a paragraph and do not require a preceding blank line.
    • Type 1 (Literal Content): Tags like <pre>, <script>, and <style> are treated differently. They end at the first line containing a corresponding end tag, meaning they can contain blank lines.
    • Type 2 (Comments): <!-- comment --> blocks.
    • Type 3 (Processing Instructions): <?php ... ?> blocks.
    • Type 4 (Declarations): <!DOCTYPE html> blocks.
    • Type 5 (CDATA): <![CDATA[ ... ]]> blocks.
    • Type 7 Blocks: These use any tag name (e.g., <Warning>) and cannot interrupt a paragraph.

    Key Rules for HTML Blocks:

    • To include Markdown content inside an HTML block, separate the Markdown from the HTML using blank lines.
    • An opening tag can be indented by 1-3 spaces, but not 4 (4 spaces will trigger an indented code block).
    • If a Type 1 block (like <script>) has no matching end tag, it ends at the end of the document, the enclosing block quote, or the enclosing list item.

  6. Create code spans with backticks

    master

    A code span is created using a "backtick string" (one or more ` characters) that is neither preceded nor followed by a backtick.

    Normalization Rules:

    1. Line Endings: All line endings within the span are converted to spaces.
    2. Space Stripping: If the resulting string begins and ends with a space character (and is not entirely spaces), a single space is removed from both the front and the back. This allows you to wrap code containing backticks by separating them from the delimiters with whitespace.
    3. Literal Backslashes: Backslash escapes do not work in code spans; all backslashes are treated literally.

    CSS Recommendation: To ensure consecutive spaces are rendered correctly in browsers, use: code { white-space: pre-wrap; }

  7. Indented code blocks within list items

    master

    When the first block in a list item is an indented code block, the contents must be indented exactly one space after the list marker. If you add an additional space of indentation, that extra space will be interpreted as part of the code block content itself.

    Correct indentation (one space after marker):

    1.     indented code

paragraph

more code

    Incorrect indentation (extra space becomes part of code):

    1.      indented code

paragraph

more code

  8. Rules for reference links

    master

    Reference links consist of a link label (e.g., [foo]) that matches a link reference definition elsewhere in the document (e.g., [foo]: /url).

    • Matching: Matching is case-insensitive. To normalize a label, strip brackets, perform Unicode case folding, strip leading/trailing whitespace, and collapse internal whitespace to a single space.
    • Nesting: Links may not contain other links at any level of nesting.
    • Precedence: Link text grouping takes precedence over emphasis grouping. However, HTML tags, code spans, and autolinks take precedence over link grouping.
    // Full reference link
[foo][bar]

[bar]: /url "title"

// Case-insensitive matching
[foo][BaR]

[bar]: /url

  9. Indenting sublists within list items

    master

    To create a sublist, the sublist marker must be indented by the same number of spaces a paragraph would need to be included in the parent list item.

    • For standard bullet lists, this is typically 2 spaces.
    • If the parent list marker is wider (e.g., 10)), the sublist must be indented further to match that width plus the required paragraph indentation.

  10. Use Full Reference Links

    master

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

    • Syntax: [link text][label]
    • Definition: [label]: destination "title"
    • Matching: Matching is case-insensitive. To match, the label's normalized form (stripping brackets, performing Unicode case fold, stripping leading/trailing whitespace, and collapsing internal whitespace) must be equal to the reference definition's label.
    • Link Text Rules: The rules for link text in reference links are identical to inline links (allowing balanced brackets and inline content, but forbidding nested links).
    [foo][bar]

[bar]: /url "title"

  11. Create ATX Headings

    master

    ATX headings use # characters to denote heading levels (1-6).

    Syntax Rules:

    • Opening Sequence: 1-6 unescaped # characters. This must be followed by a space or the end of the line. The opening # can be indented by 0-3 spaces.
    • Closing Sequence (Optional): An optional sequence of # characters at the end of the line. This must be preceded by a space and may be followed by spaces only.
    • Heading Level: Determined by the number of # characters in the opening sequence.
    • Content: The text between the # sequences is parsed as inline content. Leading and trailing whitespace in the heading content is ignored.
    • Escaping: Use a backslash \# to prevent # from being parsed as a heading.
    • Empty Headings: ATX headings can be empty (e.g., # or ###).

    Note: More than six # characters will not be parsed as a heading; it will be treated as a paragraph.

  12. Include Raw HTML

    master

    Text between < and > that resembles an HTML tag is parsed as raw HTML and rendered without escaping. This supports:

    • Open Tags: <tagname>, <tagname /> (empty elements), and tags with attributes <tagname attr="val">.
    • Closing Tags: </tagname>.
    • Comments: <!-- comment text --> (must not contain -- inside).
    • Processing Instructions: <?php ... ?>.
    • Declarations: <!ELEMENT ...>.
    • CDATA Sections: <![CDATA[ ... ]]>.

    Constraints:

    • Tag names must start with an ASCII letter followed by letters, digits, or hyphens.
    • Attribute names must start with an ASCII letter, _, or :.
    • Backslash escapes do not work inside HTML attributes.
    • Illegal tag names (e.g., <33>) or malformed attributes will not be parsed as HTML and will be escaped.
    Foo <responsive-image src="foo.jpg" />
.
<p>Foo <responsive-image src="foo.jpg" /></p>
    foo <!-- this is a
comment - with hyphen -->
.
<p>foo <!-- this is a
comment - with hyphen --></p>