Goldmark

https://github.com/yuin/goldmark
Admin
Goldmark is a Markdown parser written in Go that is easy to extend, standards-compliant, and...
Tokens:90,342
Snippets:1,396
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install goldmark

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Use the go get command to add the goldmark package to your project.

```bash
$ go get github.com/yuin/goldmark/v2
```

--------------------------------

### Heading Attribute Syntax Examples

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Examples of applying IDs, classes, and attributes to ATX and Setext style headings.

```markdown
## heading ## {#id .className attrName=attrValue class="class1 class2"}

## heading {#id .className attrName=attrValue class="class1 class2"}
```

```markdown
heading {#id .className attrName=attrValue}
============
```

--------------------------------

### Markdown Input Example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A four-line Markdown example used to demonstrate the block structure generation process.

```markdown
> Lorem ipsum dolor
sit amet.
> - Qui *quodsi iracundia*
> - aliquando id
```

--------------------------------

### BlockParser Open Implementation Example

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Example implementation of the Open method for a custom block parser, demonstrating how to inspect the reader and append source text.

```go
func (b *myBlockParser) Open(parent ast.Node, reader text.Reader, pc parser.Context) (ast.Node, parser.State) {
    line, segment := reader.PeekLine()
    if !bytes.HasPrefix(line, []byte(">>> ")) {
        return nil, parser.NoChildren
    }
    node := NewMyBlock()
    node.SetPos(segment.Start)
    reader.Advance(4) // consume ">>> "
    _, seg := reader.PeekLine()
    node.AppendSource(seg.TrimRightSpace(reader.Source()))
    reader.AdvanceToEOL()
    return node, parser.HasChildren
}
```

--------------------------------

### Nested Emphasis and Strong Emphasis Examples

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples showing how emphasis and strong emphasis interact when nested.

```markdown
*(**foo**)*
.
<p><em>(<strong>foo</strong>)</em></p>
```

```markdown
**Gomphocarpus (*Gomphocarpus physocarpus*, syn.
*Asclepias physocarpa*)**
.
<p><strong>Gomphocarpus (<em>Gomphocarpus physocarpus</em>, syn.
<em>Asclepias physocarpa</em>)</strong></p>
```

```markdown
**foo "*bar*" foo**
.
<p><strong>foo &quot;<em>bar</em>&quot; foo</strong></p>
```

--------------------------------

### Install migration plugins via CLI

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Use these commands in Claude Code or Copilot CLI to add and install the necessary migration plugins for goldmark v2.

```bash
/plugin marketplace add yuin/goldmark@v2
/plugin install migrate-goldmark-v1-to-v2@yuin-goldmark-v2
```

--------------------------------

### Ordered list start number with leading zeros example 2

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Start numbers with leading zeros are parsed correctly.

```markdown
003. ok
```

```html
<ol start="3">
<li>ok</li>
</ol>
```

--------------------------------

### Inline Code Example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

An example showing how backticks are used for code spans.

```markdown
`foo``bar``
.
<p>`foo<code>bar</code></p>
```

--------------------------------

### List items starting with a blank line

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates how list items containing blocks like code blocks or text can start with a blank line.

```markdown
-
  foo
-
  ```
  bar
  ```
-
      baz
.
<ul>
<li>foo</li>
<li>
<pre><code>bar
</code></pre>
</li>
<li>
<pre><code>baz
</code></pre>
</li>
</ul>
```

--------------------------------

### Blockquote list continuation example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of how Markdown.pl parses continuation paragraphs within a blockquote.

```markdown
>   - one
>
>  two
```

```html
<blockquote>
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>
</blockquote>
```

--------------------------------

### Markdown.pl list continuation example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of how Markdown.pl parses continuation paragraphs with less indentation than the list marker.

```markdown
   - one

  two
```

```html
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>
```

--------------------------------

### Basic URI Autolink

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A standard URI autolink example.

```markdown
<http://foo.bar.baz>
.
<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
```

--------------------------------

### Decorating a node renderer

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Example of decorating a Document node renderer to inject a script tag.

```go
func addMyScript(next html.NodeRenderer) html.NodeRenderer {
    return html.NodeRendererFunc(func(w io.Writer, source []byte, n ast.Node,
        entering bool, rc renderer.Context) (ast.WalkStatus, error) {
        if !entering {
            bw := w.(util.BufWriter)
            _, _ = bw.WriteString(`<script src="my-script.js"></script>`)
        }
        return next.Render(w, source, n, entering, rc)
    })
}
```

--------------------------------

### Define parser and renderer extensions

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Example implementation of parser and HTML renderer extensions using util.Prioritized for ordering.

```go
type myParserExtension struct{}

func NewMyParser() parser.Extension { return &myParserExtension{} }

func (e *myParserExtension) ParserOptions(_ *parser.Config) []parser.Option {
    return []parser.Option{
        parser.WithBlockParsers(
            util.Prioritized(newMyBlockParser(), 600),
        ),
        parser.WithInlineParsers(
            util.Prioritized(newMyInlineParser(), 600),
        ),
    }
}

type myHTMLRendererExtension struct{}

func NewMyHTMLRenderer() html.Extension { return &myHTMLRendererExtension{} }

func (e *myHTMLRendererExtension) RendererOptions(_ *html.Config) []html.Option {
    return []html.Option{
        html.WithNodeRenderers(map[ast.NodeKind]html.NodeRenderer{
            KindMyNode: html.NodeRendererFunc(renderMyNode),
        }),
    }
}
```

--------------------------------

### Four-space rule list example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example demonstrating how the four-space rule parses list items and intervening paragraphs.

```markdown
- foo

  bar

  - baz
```

```html
<ul>
<li>foo</li>
</ul>
<p>bar</p>
<ul>
<li>baz</li>
</ul>
```

--------------------------------

### AsciiDoc list example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A sample of AsciiDoc syntax demonstrating list items, continuation blocks, and indented code blocks.

```text
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--
```

--------------------------------

### Ordered list start number with leading zeros

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Start numbers can begin with zeros, which are stripped in the output.

```markdown
0. ok
.
<ol start="0">
<li>ok</li>
</ol>
```

```markdown
003. ok
.
<ol start="3">
<li>ok</li>
</ol>
```

--------------------------------

### Ordered list start number constraints

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Ordered list start numbers must be nine digits or less.

```markdown
123456789. ok
.
<ol start="123456789">
<li>ok</li>
</ol>
```

```markdown
1234567890. not ok
.
<p>1234567890. not ok</p>
```

--------------------------------

### Empty list items

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example questioning the validity of empty list items.

```markdown
* a
*
* b
```

--------------------------------

### Custom Scheme Autolink

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

An example of a custom scheme autolink.

```markdown
<made-up-scheme://foo,bar>
.
<p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p>
```

--------------------------------

### Emphasis precedence

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example questioning how nested emphasis markers should be parsed.

```markdown
*foo *bar* baz*
```

--------------------------------

### Both Left and Right-flanking Delimiter Runs

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of delimiter runs that are both left-flanking and right-flanking.

```text
 abc***def
"abc"_"def"
```

--------------------------------

### Requirement for Uniform Characters

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example showing that all non-whitespace characters must be the same.

```markdown
 *-*
.
<p><em>-</em></p>
```

--------------------------------

### Strong Emphasis Rule 8 Nesting Example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates valid nesting with double underscores.

```markdown
_(__foo__)_
.
<p><em>(<strong>foo</strong>)</em></p>
```

--------------------------------

### Inline link with empty destination

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples showing how empty destinations are handled in inline links.

```markdown
[link]()
.
<p><a href="">link</a></p>
```

```markdown
[link](<>)
.
<p><a href="">link</a></p>
```

--------------------------------

### Link reference parsing example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates that [foo] is not parsed as a shortcut reference when followed by a defined link label [baz].

```markdown
[foo][bar][baz]

[baz]: /url1
[foo]: /url2
.
<p>[foo]<a href="/url1">bar</a></p>
```

--------------------------------

### Implement Custom Parser and Renderer

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Demonstrates how to initialize a parser and HTML renderer with specific extensions and attributes, then process a source string into an HTML output.

```go
import (
    "bytes"
    "github.com/yuin/goldmark/v2/extension"
    "github.com/yuin/goldmark/v2/parser"
    "github.com/yuin/goldmark/v2/renderer/html"
)

source := []byte("こんにちは、 ~~世界~~ 。")

p := parser.New(parser.WithAttribute(), parser.WithExtensions(extension.StrikethroughParser))
r := html.New(html.WithXHTML(), html.WithUnsafe(), html.WithExtensions(extension.StrikethroughHTMLRenderer))

var buf bytes.Buffer
doc := p.Parse(source)
if err := r.Render(&buf, source, doc); err != nil {
    panic(err)
}
if "<p>こんにちは、 <del>世界</del> 。</p>\n" != buf.String() {
    panic("unexpected output:" + buf.String())
}
```

--------------------------------

### Initialize parser and renderer with extensions

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Shows how to register the custom extensions when creating the parser and renderer instances.

```go
p := parser.New(parser.WithExtensions(NewMyParser()))
r := html.New(html.WithExtensions(NewMyHTMLRenderer()))
doc := p.Parse(source)
if err := r.Render(&buf, source, doc); err != nil {
    // ...
}
```

--------------------------------

### Nested Emphasis and Strong Emphasis

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of nesting emphasis and strong emphasis.

```markdown
_foo __bar__ baz_
.
<p><em>foo <strong>bar</strong> baz</em></p>
```

```markdown
_foo _bar_ baz_
.
<p><em>foo <em>bar</em> baz</em></p>
```

```markdown
__foo_ bar_
.
<p><em><em>foo</em> bar</em></p>
```

```markdown
*foo *bar**
.
<p><em>foo <em>bar</em></em></p>
```

```markdown
*foo **bar** baz*
.
<p><em>foo <strong>bar</strong> baz</em></p>
```

```markdown
*foo**bar**baz*
.
<p><em>foo<strong>bar</strong>baz</em></p>
```

--------------------------------

### Paragraph interruption example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Example of a list interrupting a paragraph.

```markdown
I need to buy
- new shoes
- a coat
- a plane ticket
```

--------------------------------

### Entity References Example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates the parsing of various HTML5 entity references into their corresponding Unicode characters.

```text
&nbsp; &amp; &copy; &AElig; &Dcaron;
&frac34; &HilbertSpace; &DifferentialD;
&ClockwiseContourIntegral; &ngE;
.
<p>  &amp; © Æ Ď
¾ ℋ ⅆ
∲ ≧̸</p>
```

--------------------------------

### Basic block quote

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A standard block quote example using the > marker.

```markdown
> # Foo
> bar
> baz
.
```

```html
<blockquote>
<h1>Foo</h1>
<p>bar
baz</p>
</blockquote>
```

--------------------------------

### Indented code block starting with tab

Source: https://github.com/yuin/goldmark/blob/v2/_test/extra.txt

Indented code blocks can start with a tab character.

```markdown
		x
```

--------------------------------

### Configure Linkify extension with xurls

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Example of initializing the Linkify parser with custom allowed protocols and a strict URL regexp using the xurls library.

```go
import (
    "mvdan.cc/xurls/v2"
    "github.com/yuin/goldmark/v2/extension"
    "github.com/yuin/goldmark/v2/parser"
)

_ = parser.New(
      parser.WithExtensions(
          extension.NewLinkifyParser(
              extension.WithAllowedProtocols([]string{
                  "http:",
                  "https:",
              }),
              extension.WithURLRegexp(
                  xurls.Strict(),
              ),
          ),
      ),
)
```

--------------------------------

### Markdown list example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

The equivalent list structure in Markdown, highlighting the use of indentation for readability.

```markdown
1.  List item one.

    List item one continued with a second paragraph followed by an
    Indented block.

        $ ls *.sh
        $ mv *.sh ~/tmp

    List item continued with a third paragraph.

2.  List item two continued with an open block.

    This paragraph is part of the preceding list item.

    1. This list is nested and does not require explicit item continuation.

       This paragraph is part of the preceding list item.

    2. List item b.

    This paragraph belongs to item two of the outer list.
```

--------------------------------

### Precedence of link text over emphasis example 2

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Another example of link text grouping precedence.

```markdown
[foo *bar][ref]

[ref]: /uri
.
<p><a href="/uri">foo *bar</a></p>
```

--------------------------------

### Build and Render AST

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Constructs an AST manually using the goldmark AST API and renders it to HTML.

```go
import (
    "bytes"
    "github.com/yuin/goldmark/v2/ast"
    "github.com/yuin/goldmark/v2/text"
    "github.com/yuin/goldmark/v2/renderer/html"
)

doc := ast.N(ast.NewDocument(),
    ast.N(ast.NewParagraph(),
        "こんにちは、",
        ast.N(ast.NewEmphasis(),
            "世界",
        ),
        "。",
    ),
    ast.N(func() ast.Node {
        n := ast.NewParagraph()
        n.SetAttribute("class", text.NewMultiLineValue("greeting", text.IdentityDecoder))
        return n
    }(), "Hello, world."),
)

var buf bytes.Buffer
r := html.New()
if err := r.Render(&buf, nil, doc); err != nil {
    panic(err)
}
if "<p>こんにちは、<em>世界</em>。</p>\n<p class=\"greeting\">Hello, world.</p>\n" != buf.String() {
    panic("unexpected output:" + buf.String())
}
```

--------------------------------

### Nested list item example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Example of a list item containing a paragraph followed by a nested sublist.

```markdown
  * I need to buy
    - new shoes
    - a coat
    - a plane ticket
```

--------------------------------

### Indented list markers

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example demonstrating the ambiguity of indented list markers and alignment.

```markdown
 8. item 1
 9. item 2
10. item 2a
```

--------------------------------

### Empty ordered list items

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of empty items within an ordered list.

```markdown
1. foo
2.
3. bar
.
<ol>
<li>foo</li>
<li></li>
<li>bar</li>
</ol>
```

--------------------------------

### Simple ATX headings

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates standard heading levels 1 through 6.

```markdown
# foo
## foo
### foo
#### foo
##### foo
###### foo
.
<h1>foo</h1>
<h2>foo</h2>
<h3>foo</h3>
<h4>foo</h4>
<h5>foo</h5>
<h6>foo</h6>
```

--------------------------------

### Simple tilde code block

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A basic example of a fenced code block using tildes.

```markdown
~~~
<
 >
~~~
```

--------------------------------

### Mixed list markers

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example questioning whether changing list markers creates one list or two.

```markdown
1. fee
2. fie
-  foe
-  fum
```

--------------------------------

### Intraword Emphasis Constraints

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples showing how intraword emphasis is handled for asterisks versus underscores.

```markdown
internal emphasis: foo*bar*baz
no emphasis: foo_bar_baz
```

--------------------------------

### Migrate Top-Level Package Usage

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Shows the transition from the removed goldmark.New() and goldmark.Convert() to using parser.New() and html.New() directly in v2.

```go
// v1
import "github.com/yuin/goldmark"
md := goldmark.New(goldmark.WithExtensions(...))
md.Convert(source, &buf)

// v2
import (
    "github.com/yuin/goldmark/v2/parser"
    "github.com/yuin/goldmark/v2/renderer/html"
)
p := parser.New(parser.WithExtensions(...))
r := html.New(html.WithExtensions(...))
doc := p.Parse(source)
r.Render(&buf, source, doc)
```

--------------------------------

### Negative ordered list start number

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Negative numbers are not valid as ordered list start numbers.

```markdown
-1. not ok
.
<p>-1. not ok</p>
```

--------------------------------

### Indentation requirement example 2

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Shows sufficient indentation to include a second paragraph within the list item.

```markdown
- one

  two
.
<ul>
<li>
<p>one</p>
<p>two</p>
</li>
</ul>
```

--------------------------------

### Inline HTML start and end tags

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Shows that the end tag can occur on the same line as the start tag.

```markdown
<style>p{color:red;}</style>
*foo*
.
<style>p{color:red;}</style>
<p><em>foo</em></p>
```

--------------------------------

### Link reference precedence

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example questioning which definition takes precedence when multiple references exist for the same label.

```markdown
[foo]: /url1
[foo]: /url2

[foo][]
```

--------------------------------

### Brackets in link labels example 2

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Another example showing that unescaped brackets in labels prevent matching.

```markdown
[foo][ref[bar]]

[ref[bar]]: /uri
.
<p>[foo][ref[bar]]</p>
<p>[ref[bar]]: /uri</p>
```

--------------------------------

### Simple Setext Headings

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates basic level 1 and level 2 Setext headings.

```markdown
Foo *bar*
=========

Foo *bar*
---------
.
<h1>Foo <em>bar</em></h1>
<h2>Foo <em>bar</em></h2>
```

--------------------------------

### Using parser.Context for state management

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Demonstrates how to store and retrieve values in a parser.Context, which is scoped to a single parse invocation.

```go
var myKey = parser.NewContextKey()

// store
pc.Set(myKey, myValue)

// retrieve
val := pc.Get(myKey)
```

--------------------------------

### Configure Typographer Substitutions

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Example of overriding default typographic punctuation substitutions using the Typographer extension options.

```go
import (
    "github.com/yuin/goldmark/v2/extension"
    "github.com/yuin/goldmark/v2/parser"
)
_ = parser.New(
        parser.WithExtensions(extension.NewTypographerParser(
            extension.WithTypographicSubstitutions(extension.TypographicSubstitutions{
                extension.LeftSingleQuote:  "&sbquo;",
                extension.RightSingleQuote: "", // "" disables a substitution
            }),
        )),
)
```

--------------------------------

### Initialize custom AST nodes

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Every custom node constructor must call n.Init(n) to support tree mutation methods.

```go
n.Init(n)
```

--------------------------------

### Block-level vs inline-level precedence

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example questioning how block-level structure interacts with inline code spans.

```markdown
- `a long code span can contain a hyphen like this
  - and it can screw things up`
```

--------------------------------

### Ordered list start number overflow

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Start numbers exceeding nine digits are not treated as list items.

```markdown
1234567890. not ok
```

```html
<p>1234567890. not ok</p>
```

--------------------------------

### Run conformance tests with spec_tests.py

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Use this command to run the conformance tests against a specific Markdown program.

```bash
python test/spec_tests.py --spec spec.txt --program PROGRAM
```

--------------------------------

### Markdown multi-line element example

Source: https://github.com/yuin/goldmark/blob/v2/AGENTS.md

Example of a link element spanning multiple lines, which requires tracking segments and using text.MultiLineValue.

```markdown
> [lin
> nk](https://example.com)
```

--------------------------------

### Construct Link and Image nodes

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Link and Image constructors now accept SingleLineValue destinations and optional functional options.

```go
NewLink(destination text.SingleLineValue, opts ...LinkOption)
NewImage(destination text.SingleLineValue, opts ...LinkOption)
ast.WithLinkTitle(title)
ast.WithLinkReference(kind, value)
```

--------------------------------

### Construct Heading nodes

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Headings now require a HeadingKind (ATX or Setext).

```go
NewHeading(level int, kind HeadingKind)
```

--------------------------------

### HTML block with invalid tag start

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates that an HTML block can start with an invalid tag as long as it begins like one.

```html
<div *???-&&&-<---
*foo*
.
<div *???-&&&-<---
*foo*
```

--------------------------------

### Tab handling in code blocks and nested lists

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Examples of tab behavior in code blocks and nested list structures.

```markdown
    foo
→bar
.
<pre><code>foo
bar
</code></pre>
```

```markdown
 - foo
   - bar
→ - baz
.
<ul>
<li>foo
<ul>
<li>bar
<ul>
<li>baz</li>
</ul>
</li>
</ul>
</li>
</ul>
```

--------------------------------

### Hexadecimal Numeric Character References Example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates hexadecimal numeric character references parsed into their corresponding Unicode characters.

```text
&#X22; &#XD06; &#xcab;
.
<p>&quot; ആ ಫ</p>
```

--------------------------------

### Migrate goldmark applications

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Execute this command to migrate an application using goldmark from v1 to v2.

```bash
/migrate-goldmark-v1-to-v2:migrate-goldmark-app-v1-to-v2
```

--------------------------------

### Invalid Lazy Continuation in Block Quote Example 2

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Another example showing that the underline does not trigger a heading inside a block quote.

```markdown
> foo
bar
===
```

```html
<blockquote>
<p>foo
bar
===</p>
</blockquote>
```

--------------------------------

### Update Extension Pattern

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Demonstrates splitting the v1 Extender interface into separate parser and renderer extensions for v2.

```go
// v1
type MyExtension struct{}
func (e *MyExtension) Extend(m goldmark.Markdown) {
    m.Parser().AddOptions(...)
    m.Renderer().AddOptions(...)
}

// v2: split into parser extension and renderer extension
type MyParserExtension struct{}
func (e *MyParserExtension) ParserOptions(c *parser.Config) []parser.Option { ... }

type MyHTMLRendererExtension struct{}
func (e *MyHTMLRendererExtension) RendererOptions(c *html.Config) []html.Option { ... }
```

--------------------------------

### Migrate goldmark extension projects

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Execute this command to migrate an existing goldmark extension project from v1 to v2.

```bash
/migrate-goldmark-v1-to-v2:migrate-goldmark-extension-v1-to-v2
```

--------------------------------

### Document Tree Structure Example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A representation of the document tree showing how paragraphs, softbreaks, lists, and emphasis are structured after the inline parsing phase.

```tree
document
  block_quote
    paragraph
      str "Lorem ipsum dolor"
      softbreak
      str "sit amet."
    list (type=bullet tight=true bullet_char=-)
      list_item
        paragraph
          str "Qui "
          emph
            str "quodsi iracundia"
      list_item
        paragraph
          str "aliquando id"
```

--------------------------------

### Shortcut Image Reference with Formatting

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Shortcut syntax with formatted alt text.

```markdown
![*foo* bar]

[*foo* bar]: /url "title"
.
<p><img src="/url" alt="foo bar" title="title" /></p>
```

--------------------------------

### Basic Emphasis and Strong Emphasis

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates standard strong emphasis syntax.

```markdown
foo-__(bar)__
.
<p>foo-<strong>(bar)</strong></p>
```

--------------------------------

### Indentation requirement example 3

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates how indentation levels affect whether content is treated as a list item or a code block.

```markdown
 -    one

     two
.
<ul>
<li>one</li>
</ul>
<pre><code> two
</code></pre>
```

--------------------------------

### Basic Reference Link

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates a standard reference link with formatted text.

```markdown
[link *foo **bar** `#`*][ref]

[ref]: /uri
.
<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
```

--------------------------------

### Spaced Thematic Breaks

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Examples showing that spaces are allowed between characters.

```markdown
 - - -
.
<hr />
```

```markdown
 **  * ** * ** * **
.
<hr />
```

```markdown
-     -      -      -
.
<hr />
```

--------------------------------

### Implement renderer.Extension interface

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Defines the structure for a renderer extension in Goldmark.

```go
type Extension[C any] interface {
    RendererOptions(c *C) []renderer.Option[C]
}
```

--------------------------------

### Right-flanking Delimiter Runs

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of delimiter runs that are right-flanking but not left-flanking.

```text
 abc***
 abc_
"abc"**
"abc"_
```

--------------------------------

### Left-flanking Delimiter Runs

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of delimiter runs that are left-flanking but not right-flanking.

```text
***abc
  _abc
**"abc"
 _"abc"
```

--------------------------------

### Shortcut Image Syntax

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Shortcut syntax for reference-style images.

```markdown
![foo]

[foo]: /url "title"
.
<p><img src="/url" alt="foo" title="title" /></p>
```

```markdown
![*foo* bar]

[*foo* bar]: /url "title"
.
<p><img src="/url" alt="foo bar" title="title" /></p>
```

--------------------------------

### Convert Markdown to HTML

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Demonstrates parsing a byte slice of Markdown and rendering it to HTML using the default parser and renderer.

```go
import (
    "bytes"
    "github.com/yuin/goldmark/v2/parser"
    "github.com/yuin/goldmark/v2/renderer/html"
)

source := []byte("こんにちは、 **世界** 。")

var buf bytes.Buffer
p := parser.New()
r := html.New()

doc := p.Parse(source)
if err := r.Render(&buf, source, doc); err != nil {
    panic(err)
}
if "<p>こんにちは、 <strong>世界</strong> 。</p>\n" != buf.String() {
    panic("unexpected output:" + buf.String())
}
```

--------------------------------

### Implement parser.Extension interface

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Defines the structure for a parser extension in Goldmark.

```go
type Extension interface {
    ParserOptions(c *parser.Config) []parser.Option
}
```

--------------------------------

### Emphasis and links

Source: https://github.com/yuin/goldmark/blob/v2/_test/extra.txt

Demonstrates combining emphasis with link syntax.

```markdown
_**TL/DR** - [Go see summary.](#my-summary-area)_
```

```html
<p><em><strong>TL/DR</strong> - <a href="#my-summary-area">Go see summary.</a></em></p>
```

--------------------------------

### Paragraph with list-starting numeral

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

A list starting with '1.' will interrupt a paragraph.

```markdown
The number of windows in my house is
1.  The number of doors is 6.
.
<p>The number of windows in my house is</p>
<ol>
<li>The number of doors is 6.</li>
</ol>
```

--------------------------------

### Extended Thematic Break Length

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Example showing that more than three characters can be used.

```markdown
_____________________________________
.
<hr />
```

--------------------------------

### Basic List Parsing

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates standard unordered list parsing with multiple items.

```markdown
- foo
- bar

<!-- -->

- baz
- bim
```

```html
<ul>
<li>foo</li>
<li>bar</li>
</ul>
<!-- -->
<ul>
<li>baz</li>
<li>bim</li>
</ul>
```

--------------------------------

### Excessive Indentation

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Examples where four or more spaces of indentation prevent a thematic break.

```markdown
    ***
.
<pre><code>***
</code></pre>
```

```markdown
Foo
    ***
.
<p>Foo
***</p>
```

--------------------------------

### Indented Thematic Breaks

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Examples showing that 1-3 spaces of indentation are allowed.

```markdown
 ***
  ***
   ***
.
<hr />
<hr />
<hr />
```

--------------------------------

### Reference Precedence Rules

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Demonstrates that full and compact references take precedence over shortcut references.

```markdown
[foo][bar]

[foo]: /url1
[bar]: /url2
.
<p><a href="/url2">foo</a></p>
```

```markdown
[foo][]

[foo]: /url1
.
<p><a href="/url1">foo</a></p>
```

--------------------------------

### Simple open tags

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates basic parsing of simple HTML open tags.

```markdown
<a><bab><c2c>
.
<p><a><bab><c2c></p>
```

--------------------------------

### Emphasis Precedence over Link

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example where emphasis grouping affects the link parsing.

```markdown
[foo *bar](baz*)
.
<p><a href="baz*">foo *bar</a></p>
```

--------------------------------

### Delimiter Interpretation Preclusion

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of how delimiter rules preclude certain interpretations.

```markdown
<p><em>foo</em><em>bar<em></em>baz</em></p>
```

```markdown
*foo**bar*
.
<p><em>foo**bar</em></p>
```

--------------------------------

### Construct CodeBlock nodes

Source: https://github.com/yuin/goldmark/blob/v2/README.md

CodeBlock constructor requires a kind and lines; use WithCodeBlockInfo for info strings.

```go
NewCodeBlock(kind CodeBlockKind, value text.Lines, opts ...CodeBlockOption)
ast.WithCodeBlockInfo(info)
Language(source []byte) (string, bool)
```

--------------------------------

### Non-flanking Delimiter Runs

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of delimiter runs that are neither left-flanking nor right-flanking.

```text
abc *** def
a _ b
```

--------------------------------

### HTML block parsing with standard tags

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates basic HTML table structure parsing.

```markdown
<table>

<tr>

<td>
Hi
</td>

</tr>

</table>
.
<table>
<tr>
<td>
Hi
</td>
</tr>
</table>
```

--------------------------------

### Writing text values safely

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Demonstrates writing text values using context-aware writers to ensure HTML safety.

```go
// Render display text: HTML-escape it, decoding already happened at construction time.
tw := html.ContextTextWriter(rc)
_, _ = n.Value.WriteTo(tw, source)

// Render raw HTML that is trusted to already be valid: only NUL is replaced.
hw := html.ContextHTMLWriter(rc)
_, _ = n.Value.WriteTo(hw, source)
```

--------------------------------

### Basic list item structure example

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates a standard paragraph, indented code block, and block quote being converted into a list item.

```markdown
1.  A paragraph
    with two lines.

        indented code

    > A block quote.
.
<ol>
<li>
<p>A paragraph
with two lines.</p>
<pre><code>indented code
</code></pre>
<blockquote>
<p>A block quote.</p>
</blockquote>
</li>
</ol>
```

--------------------------------

### Invalid Thematic Break Characters

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of characters that do not form a thematic break.

```markdown
+++
.
<p>+++</p>
```

```markdown
===
.
<p>===</p>
```

--------------------------------

### SimpleEastAsianLineBreakStrategy Example

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Shows the input Markdown and resulting HTML output when using the SimpleEastAsianLineBreakStrategy, which ignores soft line breaks between East Asian wide characters.

```md
私はプログラマーです。
東京の会社に勤めています。
GoでWebアプリケーションを開発しています。
```

```html
<p>私はプログラマーです。東京の会社に勤めています。\nGoでWebアプリケーションを開発しています。</p>
```

--------------------------------

### Interrupting Paragraphs with Thematic Breaks

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Example showing that thematic breaks can interrupt a paragraph.

```markdown
Foo
***
bar
.
<p>Foo</p>
<hr />
<p>bar</p>
```

--------------------------------

### HTML processing instruction

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates a PHP processing instruction block.

```markdown
<?php

  echo '>';

?>
okay
.
<?php

  echo '>';

?>
<p>okay</p>
```

--------------------------------

### Trailing Spaces in Thematic Breaks

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Example showing that spaces are allowed at the end of the line.

```markdown
- - - -    
.
<hr />
```

--------------------------------

### Blank lines handling

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates how blank lines between block-level elements are ignored in the output.

```markdown
  

aaa
  

# aaa

  
.
```

```html
<p>aaa</p>
<h1>aaa</h1>
```

--------------------------------

### Basic asterisk emphasis

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates standard emphasis using asterisk delimiters.

```markdown
*foo bar*
.
<p><em>foo bar</em></p>
```

--------------------------------

### Complex Nested Link Attempt

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Another example showing that links cannot contain other links.

```markdown
[foo *[bar [baz](/uri)](/uri)*](/uri)
.
<p>[foo <em>[bar <a href="/uri">baz</a>](/uri)</em>](/uri)</p>
```

--------------------------------

### Construct literal-string trees

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Use ast.NewText or the ast.N builder helper for literal strings.

```go
ast.NewText(text.NewSingleLineValueFromString(s, decoder))
ast.N(...)
```

--------------------------------

### Simple code span

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

A basic example of a code span using single backticks.

```markdown
`foo`
.
<p><code>foo</code></p>
```

--------------------------------

### Shortcut Reference Link

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Demonstrates shortcut reference links which do not require trailing brackets.

```markdown
[foo]

[foo]: /url "title"
.
<p><a href="/url" title="title">foo</a></p>
```

```markdown
[*foo* bar]

[*foo* bar]: /url "title"
.
<p><a href="/url" title="title"><em>foo</em> bar</a></p>
```

```markdown
[[*foo* bar]]

[*foo* bar]: /url "title"
.
<p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
```

```markdown
[[bar [foo]

[foo]: /url
.
<p>[[bar <a href="/url">foo</a></p>
```

```markdown
[Foo]

[foo]: /url "title"
.
<p><a href="/url" title="title">Foo</a></p>
```

--------------------------------

### Bullet list delimiter change

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Changing the bullet character starts a new list.

```markdown
- foo
- bar
+ baz
.
<ul>
<li>foo</li>
<li>bar</li>
</ul>
<ul>
<li>baz</li>
</ul>
```

--------------------------------

### Empty link target

Source: https://github.com/yuin/goldmark/blob/v2/_test/extra.txt

Demonstrates rendering of links with empty or relative paths.

```markdown
[](./target.md)
```

```html
<p><a href="./target.md"></a></p>
```

```markdown
[]()
```

```html
<p><a href=""></a></p>
```

--------------------------------

### Basic underscore emphasis

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Demonstrates standard emphasis using underscore delimiters.

```markdown
_foo bar_
.
<p><em>foo bar</em></p>
```

--------------------------------

### Strong Emphasis Nested Inside Emphasis

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of strong emphasis nested inside emphasis.

```markdown
***foo** bar*
.
<p><em><strong>foo</strong> bar</em></p>
```

```markdown
*foo **bar***
.
<p><em>foo <strong>bar</strong></em></p>
```

--------------------------------

### Construct Emphasis and Strong nodes

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Emphasis and Strong are now separate types; use NewEmphasis() for single emphasis.

```go
NewEmphasis()
```

--------------------------------

### CSSText3LineBreakStrategy Example

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Shows the input Markdown and resulting HTML output when using the CSSText3LineBreakStrategy, which implements CSS text level 3 segment break transformation rules.

```md
私はプログラマーです。
東京の会社に勤めています。
GoでWebアプリケーションを開発しています。
```

```html
<p>私はプログラマーです。東京の会社に勤めています。GoでWebアプリケーションを開発しています。</p>
```

--------------------------------

### Nested list structure

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of a deeply nested list with multiple paragraphs in the final item.

```markdown
- foo
  - bar
    - baz


      bim
.
<ul>
<li>foo
<ul>
<li>bar
<ul>
<li>
<p>baz</p>
<p>bim</p>
</li>
</ul>
</li>
</ul>
</li>
</ul>
```

--------------------------------

### Lazy continuation lines

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example showing how indentation can be omitted for continuation lines in a list item.

```markdown
  1.  A paragraph
with two lines.

          indented code

      > A block quote.
.
<ol>
<li>
<p>A paragraph
with two lines.</p>
<pre><code>indented code
</code></pre>
<blockquote>
<p>A block quote.</p>
</blockquote>
</li>
</ol>
```

--------------------------------

### Create text values using generic constructors

Source: https://github.com/yuin/goldmark/blob/v2/README.md

Use these constructors to create SingleLineValue, MultiLineValue, or Lines types. SingleLineValue and MultiLineValue reference source positions or literal strings, while Lines manages raw block content via segments.

```go
import "github.com/yuin/goldmark/v2/text"

// SingleLineValue — always single-line. Every constructor takes an explicit text.Decoder
// (e.g. text.IdentityDecoder for raw content like inline HTMLs, or a decoder from text.NewDecoder() or reader.Decoder()).
dest := text.NewSingleLineValueFromIndex(text.NewIndex(start, stop), reader.Decoder()) // source position
dest := text.NewSingleLineValueFromString("https://example.com", reader.Decoder())     // literal string

// MultiLineValue — may span lines
title := text.NewMultiLineValueFromIndex(text.NewIndex(start, stop), text.IdentityDecoder)      // single span
title := text.NewMultiLineValueFromIndices([]text.Index{idx1, idx2}, reader.Decoder())      // multiple spans

// Lines — raw block content
var lines text.Lines
lines.AppendSegment(segment) // add one source line at a time
```

--------------------------------

### Indented list item (3 spaces)

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of a list item indented by three spaces.

```markdown
   1.  A paragraph
       with two lines.

           indented code

       > A block quote.
.
<ol>
<li>
<p>A paragraph
with two lines.</p>
<pre><code>indented code
</code></pre>
<blockquote>
<p>A block quote.</p>
</blockquote>
</li>
</ol>
```

--------------------------------

### Processing Instructions

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Shows how processing instructions are handled.

```markdown
foo <?php echo $a; ?>
```

```html
<p>foo <?php echo $a; ?></p>
```

--------------------------------

### Indented list item (2 spaces)

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of a list item indented by two spaces.

```markdown
  1.  A paragraph
      with two lines.

          indented code

      > A block quote.
.
<ol>
<li>
<p>A paragraph
with two lines.</p>
<pre><code>indented code
</code></pre>
<blockquote>
<p>A block quote.</p>
</blockquote>
</li>
</ol>
```

--------------------------------

### Indented list item (1 space)

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Example of a list item indented by one space.

```markdown
 1.  A paragraph
     with two lines.

         indented code

     > A block quote.
.
<ol>
<li>
<p>A paragraph
with two lines.</p>
<pre><code>indented code
</code></pre>
<blockquote>
<p>A block quote.</p>
</blockquote>
</li>
</ol>
```

--------------------------------

### Collapsed Reference Image with Formatting

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/go/_data.md

Collapsed reference syntax with formatted alt text.

```markdown
![*foo* bar][]

[*foo* bar]: /url "title"
.
<p><img src="/url" alt="foo bar" title="title" /></p>
```

--------------------------------

### Empty bullet list items

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Examples of empty bullet list items within a list.

```markdown
- foo
-
- bar
.
<ul>
<li>foo</li>
<li></li>
<li>bar</li>
</ul>
```

--------------------------------

### Empty headings

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

ATX headings can be empty.

```markdown
## 
#
### ###
.
<h2></h2>
<h1></h1>
<h3></h3>
```

--------------------------------

### Inline Image Syntax

Source: https://github.com/yuin/goldmark/blob/v2/_benchmark/cmark/_data.md

Basic inline image syntax with alt text, URL, and optional title.

```markdown
![foo](/url "title")
.
<p><img src="/url" alt="foo" title="title" /></p>
```
Tokens:
Raw