1goldmark
  2==========================================
  3
  4[![https://pkg.go.dev/github.com/yuin/goldmark](https://pkg.go.dev/badge/github.com/yuin/goldmark.svg)](https://pkg.go.dev/github.com/yuin/goldmark)
  5[![https://github.com/yuin/goldmark/actions?query=workflow:test](https://github.com/yuin/goldmark/actions/workflows/test.yaml/badge.svg?branch=master&event=push)](https://github.com/yuin/goldmark/actions?query=workflow:test)
  6[![https://coveralls.io/github/yuin/goldmark](https://coveralls.io/repos/github/yuin/goldmark/badge.svg?branch=master)](https://coveralls.io/github/yuin/goldmark)
  7[![https://goreportcard.com/report/github.com/yuin/goldmark](https://goreportcard.com/badge/github.com/yuin/goldmark)](https://goreportcard.com/report/github.com/yuin/goldmark)
  8
  9> A Markdown parser written in Go. Easy to extend, standards-compliant, well-structured.
 10
 11goldmark is compliant with CommonMark 0.31.2.
 12
 13- [goldmark playground](https://yuin.github.io/goldmark/playground/) : Try goldmark online. This playground is built with WASM(5-10MB).
 14
 15There is also a Rust version of goldmark: [rushdown](https://github.com/yuin/rushdown)
 16
 17Motivation
 18----------------------
 19I needed a Markdown parser for Go that satisfies the following requirements:
 20
 21- Easy to extend.
 22    - Markdown is poor in document expressions compared to other light markup languages such as reStructuredText.
 23    - We have extensions to the Markdown syntax, e.g. PHP Markdown Extra, GitHub Flavored Markdown.
 24- Standards-compliant.
 25    - Markdown has many dialects.
 26    - GitHub-Flavored Markdown is widely used and is based upon CommonMark, effectively mooting the question of whether or not CommonMark is an ideal specification.
 27        - CommonMark is complicated and hard to implement.
 28- Well-structured.
 29    - AST-based; preserves source position of nodes.
 30- Written in pure Go.
 31
 32[golang-commonmark](https://gitlab.com/golang-commonmark/markdown) may be a good choice, but it seems to be a copy of [markdown-it](https://github.com/markdown-it).
 33
 34[blackfriday.v2](https://github.com/russross/blackfriday/tree/v2) is a fast and widely-used implementation, but is not CommonMark-compliant and cannot be extended from outside of the package, since its AST uses structs instead of interfaces.
 35
 36Furthermore, its behavior differs from other implementations in some cases, especially regarding lists: [Deep nested lists don't output correctly #329](https://github.com/russross/blackfriday/issues/329), [List block cannot have a second line #244](https://github.com/russross/blackfriday/issues/244), etc.
 37
 38This behavior sometimes causes problems. If you migrate your Markdown text from GitHub to blackfriday-based wikis, many lists will immediately be broken.
 39
 40As mentioned above, CommonMark is complicated and hard to implement, so Markdown parsers based on CommonMark are few and far between.
 41
 42Features
 43----------------------
 44
 45- **Standards-compliant.**  goldmark is fully compliant with the latest [CommonMark](https://commonmark.org/) specification.
 46- **Extensible.**  Do you want to add a `@username` mention syntax to Markdown?
 47  You can easily do so in goldmark. You can add your AST nodes,
 48  parsers for block-level elements, parsers for inline-level elements,
 49  transformers for paragraphs, transformers for the whole AST structure, and
 50  renderers.
 51- **Performance.**  goldmark's performance is on par with that of cmark,
 52  the CommonMark reference implementation written in C.
 53- **Robust.**  goldmark is tested with `go test --fuzz`.
 54- **Built-in extensions.**  goldmark ships with common extensions like tables, strikethrough,
 55  task lists, and definition lists.
 56- **Depends only on standard libraries.**
 57
 58Installation
 59----------------------
 60```bash
 61$ go get github.com/yuin/goldmark
 62```
 63
 64
 65Usage
 66----------------------
 67Import packages:
 68
 69```go
 70import (
 71    "bytes"
 72    "github.com/yuin/goldmark"
 73)
 74```
 75
 76
 77Convert Markdown documents with the CommonMark-compliant mode:
 78
 79```go
 80var buf bytes.Buffer
 81if err := goldmark.Convert(source, &buf); err != nil {
 82  panic(err)
 83}
 84```
 85
 86With options
 87------------------------------
 88
 89```go
 90var buf bytes.Buffer
 91if err := goldmark.Convert(source, &buf, parser.WithContext(ctx)); err != nil {
 92  panic(err)
 93}
 94```
 95
 96| Functional option | Type | Description |
 97| ----------------- | ---- | ----------- |
 98| `parser.WithContext` | A `parser.Context` | Context for the parsing phase. |
 99
100Context options
101----------------------
102
103| Functional option | Type | Description |
104| ----------------- | ---- | ----------- |
105| `parser.WithIDs` | A `parser.IDs` | `IDs` allows you to change logics that are related to element id(ex: Auto heading id generation). |
106
107
108Custom parser and renderer
109--------------------------
110```go
111import (
112    "bytes"
113    "github.com/yuin/goldmark"
114    "github.com/yuin/goldmark/extension"
115    "github.com/yuin/goldmark/parser"
116    "github.com/yuin/goldmark/renderer/html"
117)
118
119md := goldmark.New(
120          goldmark.WithExtensions(extension.GFM),
121          goldmark.WithParserOptions(
122              parser.WithAutoHeadingID(),
123          ),
124          goldmark.WithRendererOptions(
125              html.WithHardWraps(),
126              html.WithXHTML(),
127          ),
128      )
129var buf bytes.Buffer
130if err := md.Convert(source, &buf); err != nil {
131    panic(err)
132}
133```
134
135| Functional option | Type | Description |
136| ----------------- | ---- | ----------- |
137| `goldmark.WithParser` | `parser.Parser`  | This option must be passed before `goldmark.WithParserOptions` and `goldmark.WithExtensions` |
138| `goldmark.WithRenderer` | `renderer.Renderer`  | This option must be passed before `goldmark.WithRendererOptions` and `goldmark.WithExtensions`  |
139| `goldmark.WithParserOptions` | `...parser.Option`  |  |
140| `goldmark.WithRendererOptions` | `...renderer.Option` |  |
141| `goldmark.WithExtensions` | `...goldmark.Extender`  |  |
142
143Parser and Renderer options
144------------------------------
145
146### Parser options
147
148| Functional option | Type | Description |
149| ----------------- | ---- | ----------- |
150| `parser.WithBlockParsers` | A `util.PrioritizedSlice` whose elements are `parser.BlockParser` | Parsers for parsing block level elements. |
151| `parser.WithInlineParsers` | A `util.PrioritizedSlice` whose elements are `parser.InlineParser` | Parsers for parsing inline level elements. |
152| `parser.WithParagraphTransformers` | A `util.PrioritizedSlice` whose elements are `parser.ParagraphTransformer` | Transformers for transforming paragraph nodes. |
153| `parser.WithASTTransformers` | A `util.PrioritizedSlice` whose elements are `parser.ASTTransformer` | Transformers for transforming an AST. |
154| `parser.WithAutoHeadingID` | `-` | Enables auto heading ids. |
155| `parser.WithAttribute` | `-` | Enables custom attributes. Currently only headings supports attributes. |
156
157### HTML Renderer options
158
159| Functional option | Type | Description |
160| ----------------- | ---- | ----------- |
161| `html.WithWriter` | `html.Writer` | `html.Writer` for writing contents to an `io.Writer`. |
162| `html.WithHardWraps` | `-` | Render newlines as `<br>`.|
163| `html.WithXHTML` | `-` | Render as XHTML. |
164| `html.WithUnsafe` | `-` | By default, goldmark does not render raw HTML or potentially dangerous links. With this option, goldmark renders such content as written. |
165
166### Built-in extensions
167
168- `extension.Table`
169    - [GitHub Flavored Markdown: Tables](https://github.github.com/gfm/#tables-extension-)
170- `extension.Strikethrough`
171    - [GitHub Flavored Markdown: Strikethrough](https://github.github.com/gfm/#strikethrough-extension-)
172- `extension.Linkify`
173    - [GitHub Flavored Markdown: Autolinks](https://github.github.com/gfm/#autolinks-extension-)
174- `extension.TaskList`
175    - [GitHub Flavored Markdown: Task list items](https://github.github.com/gfm/#task-list-items-extension-)
176- `extension.GFM`
177    - This extension enables Table, Strikethrough, Linkify and TaskList.
178    - This extension does not filter tags defined in [6.11: Disallowed Raw HTML (extension)](https://github.github.com/gfm/#disallowed-raw-html-extension-).
179    If you need to filter HTML tags, see [Security](#security).
180    - If you need to parse github emojis, you can use [goldmark-emoji](https://github.com/yuin/goldmark-emoji) extension.
181- `extension.DefinitionList`
182    - [PHP Markdown Extra: Definition lists](https://michelf.ca/projects/php-markdown/extra/#def-list)
183- `extension.Footnote`
184    - [PHP Markdown Extra: Footnotes](https://michelf.ca/projects/php-markdown/extra/#footnotes)
185- `extension.Typographer`
186    - This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/).
187- `extension.CJK`
188    - This extension is a shortcut for CJK related functionalities.
189
190### Attributes
191The `parser.WithAttribute` option allows you to define attributes on some elements.
192
193Currently only headings support attributes.
194
195**Attributes are being discussed in the
196[CommonMark forum](https://talk.commonmark.org/t/consistent-attribute-syntax/272).
197This syntax may possibly change in the future.**
198
199
200#### Headings
201
202```
203## heading ## {#id .className attrName=attrValue class="class1 class2"}
204
205## heading {#id .className attrName=attrValue class="class1 class2"}
206```
207
208```
209heading {#id .className attrName=attrValue}
210============
211```
212
213### Table extension
214The Table extension implements [Table(extension)](https://github.github.com/gfm/#tables-extension-), as
215defined in [GitHub Flavored Markdown Spec](https://github.github.com/gfm/).
216
217Specs are defined for XHTML, so specs use some deprecated attributes for HTML5.
218
219You can override alignment rendering method via options.
220
221| Functional option | Type | Description |
222| ----------------- | ---- | ----------- |
223| `extension.WithTableCellAlignMethod` | `extension.TableCellAlignMethod` | Option indicates how are table cells aligned. |
224
225### Typographer extension
226
227The Typographer extension translates plain ASCII punctuation characters into typographic-punctuation HTML entities.
228
229Default substitutions are:
230
231| Punctuation | Default entity |
232| ------------ | ---------- |
233| `'`           | `&lsquo;`, `&rsquo;` |
234| `"`           | `&ldquo;`, `&rdquo;` |
235| `--`       | `&ndash;` |
236| `---`      | `&mdash;` |
237| `...`      | `&hellip;` |
238| `<<`       | `&laquo;` |
239| `>>`       | `&raquo;` |
240
241You can override the default substitutions via `extensions.WithTypographicSubstitutions`:
242
243```go
244markdown := goldmark.New(
245    goldmark.WithExtensions(
246        extension.NewTypographer(
247            extension.WithTypographicSubstitutions(extension.TypographicSubstitutions{
248                extension.LeftSingleQuote:  []byte("&sbquo;"),
249                extension.RightSingleQuote: nil, // nil disables a substitution
250            }),
251        ),
252    ),
253)
254```
255
256### Linkify extension
257
258The Linkify extension implements [Autolinks(extension)](https://github.github.com/gfm/#autolinks-extension-), as
259defined in [GitHub Flavored Markdown Spec](https://github.github.com/gfm/).
260
261Since the spec does not define details about URLs, there are numerous ambiguous cases.
262
263You can override autolinking patterns via options.
264
265| Functional option | Type | Description |
266| ----------------- | ---- | ----------- |
267| `extension.WithLinkifyAllowedProtocols` | `[][]byte \| []string` | List of allowed protocols such as `[]string{ "http:" }` |
268| `extension.WithLinkifyURLRegexp` | `*regexp.Regexp` | Regexp that defines URLs, including protocols |
269| `extension.WithLinkifyWWWRegexp` | `*regexp.Regexp` | Regexp that defines URL starting with `www.`. This pattern corresponds to [the extended www autolink](https://github.github.com/gfm/#extended-www-autolink) |
270| `extension.WithLinkifyEmailRegexp` | `*regexp.Regexp` | Regexp that defines email addresses` |
271
272Example, using [xurls](https://github.com/mvdan/xurls):
273
274```go
275import "mvdan.cc/xurls/v2"
276
277markdown := goldmark.New(
278    goldmark.WithRendererOptions(
279        html.WithXHTML(),
280        html.WithUnsafe(),
281    ),
282    goldmark.WithExtensions(
283        extension.NewLinkify(
284            extension.WithLinkifyAllowedProtocols([]string{
285                "http:",
286                "https:",
287            }),
288            extension.WithLinkifyURLRegexp(
289                xurls.Strict(),
290            ),
291        ),
292    ),
293)
294```
295
296### Footnotes extension
297
298The Footnote extension implements [PHP Markdown Extra: Footnotes](https://michelf.ca/projects/php-markdown/extra/#footnotes).
299
300This extension has some options:
301
302| Functional option | Type | Description |
303| ----------------- | ---- | ----------- |
304| `extension.WithFootnoteIDPrefix` | `[]byte \| string` |  a prefix for the id attributes.|
305| `extension.WithFootnoteIDPrefixFunction` | `func(gast.Node) []byte` |  a function that determines the id attribute for given Node.|
306| `extension.WithFootnoteLinkTitle` | `[]byte \| string` |  an optional title attribute for footnote links.|
307| `extension.WithFootnoteBacklinkTitle` | `[]byte \| string` |  an optional title attribute for footnote backlinks. |
308| `extension.WithFootnoteLinkClass` | `[]byte \| string` |  a class for footnote links. This defaults to `footnote-ref`. |
309| `extension.WithFootnoteBacklinkClass` | `[]byte \| string` |  a class for footnote backlinks. This defaults to `footnote-backref`. |
310| `extension.WithFootnoteBacklinkHTML` | `[]byte \| string` |  a class for footnote backlinks. This defaults to `&#x21a9;&#xfe0e;`. |
311
312Some options can have special substitutions. Occurrences of “^^” in the string will be replaced by the corresponding footnote number in the HTML output. Occurrences of “%%” will be replaced by a number for the reference (footnotes can have multiple references).
313
314`extension.WithFootnoteIDPrefix` and `extension.WithFootnoteIDPrefixFunction` are useful if you have multiple Markdown documents displayed inside one HTML document to avoid footnote ids to clash each other.
315
316`extension.WithFootnoteIDPrefix` sets fixed id prefix, so you may write codes like the following:
317
318```go
319for _, path := range files {
320    source := readAll(path)
321    prefix := getPrefix(path)
322
323    markdown := goldmark.New(
324        goldmark.WithExtensions(
325            NewFootnote(
326                WithFootnoteIDPrefix(path),
327            ),
328        ),
329    )
330    var b bytes.Buffer
331    err := markdown.Convert(source, &b)
332    if err != nil {
333        t.Error(err.Error())
334    }
335}
336```
337
338`extension.WithFootnoteIDPrefixFunction` determines an id prefix by calling given function, so you may write codes like the following:
339
340```go
341markdown := goldmark.New(
342    goldmark.WithExtensions(
343        NewFootnote(
344                WithFootnoteIDPrefixFunction(func(n gast.Node) []byte {
345                    v, ok := n.OwnerDocument().Meta()["footnote-prefix"]
346                    if ok {
347                        return util.StringToReadOnlyBytes(v.(string))
348                    }
349                    return nil
350                }),
351        ),
352    ),
353)
354
355for _, path := range files {
356    source := readAll(path)
357    var b bytes.Buffer
358
359    doc := markdown.Parser().Parse(text.NewReader(source))
360    doc.Meta()["footnote-prefix"] = getPrefix(path)
361    err := markdown.Renderer().Render(&b, source, doc)
362}
363```
364
365You can use [goldmark-meta](https://github.com/yuin/goldmark-meta) to define a id prefix in the markdown document:
366
367
368```markdown
369---
370title: document title
371slug: article1
372footnote-prefix: article1
373---
374
375# My article
376
377```
378
379### CJK extension
380CommonMark gives compatibilities a high priority and original markdown was designed by westerners. So CommonMark lacks considerations for languages like CJK.
381
382This extension provides additional options for CJK users.
383
384| Functional option | Type | Description |
385| ----------------- | ---- | ----------- |
386| `extension.WithEastAsianLineBreaks` | `...extension.EastAsianLineBreaksStyle` | Soft line breaks are rendered as a newline. Some asian users will see it as an unnecessary space. With this option, soft line breaks between east asian wide characters will be ignored. This defaults to `EastAsianLineBreaksStyleSimple`. |
387| `extension.WithEscapedSpace` | `-` | Without spaces around an emphasis started with east asian punctuations, it is not interpreted as an emphasis(as defined in CommonMark spec). With this option, you can avoid this inconvenient behavior by putting 'not rendered' spaces around an emphasis like `太郎は\ **「こんにちわ」**\ といった`. |
388
389#### Styles of Line Breaking
390
391| Style | Description |
392| ----- | ----------- |
393| `EastAsianLineBreaksStyleSimple` | Soft line breaks are ignored if both sides of the break are east asian wide character. This behavior is the same as [`east_asian_line_breaks`](https://pandoc.org/MANUAL.html#extension-east_asian_line_breaks) in Pandoc. |
394| `EastAsianLineBreaksCSS3Draft` | This option implements CSS text level3 [Segment Break Transformation Rules](https://drafts.csswg.org/css-text-3/#line-break-transform) with [some enhancements](https://github.com/w3c/csswg-drafts/issues/5086). |
395
396#### Example of `EastAsianLineBreaksStyleSimple`
397
398Input Markdown:
399
400```md
401私はプログラマーです。
402東京の会社に勤めています。
403GoでWebアプリケーションを開発しています。
404```
405
406Output:
407
408```html
409<p>私はプログラマーです。東京の会社に勤めています。\nGoでWebアプリケーションを開発しています。</p>
410```
411
412#### Example of `EastAsianLineBreaksCSS3Draft`
413
414Input Markdown:
415
416```md
417私はプログラマーです。
418東京の会社に勤めています。
419GoでWebアプリケーションを開発しています。
420```
421
422Output:
423
424```html
425<p>私はプログラマーです。東京の会社に勤めています。GoでWebアプリケーションを開発しています。</p>
426```
427
428Security
429--------------------
430By default, goldmark does not render raw HTML or potentially-dangerous URLs.
431If you need to gain more control over untrusted contents, it is recommended that you
432use an HTML sanitizer such as [bluemonday](https://github.com/microcosm-cc/bluemonday).
433
434Benchmark
435--------------------
436You can run this benchmark in the `_benchmark` directory.
437
438### against other golang libraries
439
440blackfriday v2 seems to be the fastest, but as it is not CommonMark compliant, its performance cannot be directly compared to that of the CommonMark-compliant libraries.
441
442goldmark, meanwhile, builds a clean, extensible AST structure, achieves full compliance with
443CommonMark, and consumes less memory, all while being reasonably fast.
444
445- MBP 2019 13″(i5, 16GB), Go1.17
446
447```
448BenchmarkMarkdown/Blackfriday-v2-8                   302           3743747 ns/op         3290445 B/op      20050 allocs/op
449BenchmarkMarkdown/GoldMark-8                         280           4200974 ns/op         2559738 B/op      13435 allocs/op
450BenchmarkMarkdown/CommonMark-8                       226           5283686 ns/op         2702490 B/op      20792 allocs/op
451BenchmarkMarkdown/Lute-8                              12          92652857 ns/op        10602649 B/op      40555 allocs/op
452BenchmarkMarkdown/GoMarkdown-8                        13          81380167 ns/op         2245002 B/op      22889 allocs/op
453```
454
455### against cmark (CommonMark reference implementation written in C)
456
457- MBP 2019 13″(i5, 16GB), Go1.17
458
459```
460----------- cmark -----------
461file: _data.md
462iteration: 50
463average: 0.0044073057 sec
464------- goldmark -------
465file: _data.md
466iteration: 50
467average: 0.0041611990 sec
468```
469
470As you can see, goldmark's performance is on par with cmark's.
471
472Extensions
473--------------------
474### List of extensions
475
476- [goldmark-meta](https://github.com/yuin/goldmark-meta): A YAML metadata
477  extension for the goldmark Markdown parser.
478- [goldmark-highlighting](https://github.com/yuin/goldmark-highlighting): A syntax-highlighting extension
479  for the goldmark markdown parser.
480- [goldmark-emoji](https://github.com/yuin/goldmark-emoji): An emoji
481  extension for the goldmark Markdown parser.
482- [goldmark-mathjax](https://github.com/litao91/goldmark-mathjax): Mathjax support for the goldmark markdown parser
483- [goldmark-pdf](https://github.com/stephenafamo/goldmark-pdf): A PDF renderer that can be passed to `goldmark.WithRenderer()`.
484- [goldmark-hashtag](https://github.com/abhinav/goldmark-hashtag): Adds support for `#hashtag`-based tagging to goldmark.
485- [goldmark-wikilink](https://github.com/abhinav/goldmark-wikilink): Adds support for `[[wiki]]`-style links to goldmark.
486- [goldmark-anchor](https://github.com/abhinav/goldmark-anchor): Adds anchors (permalinks) next to all headers in a document.
487- [goldmark-figure](https://github.com/mangoumbrella/goldmark-figure): Adds support for rendering paragraphs starting with an image to `<figure>` elements.
488- [goldmark-frontmatter](https://github.com/abhinav/goldmark-frontmatter): Adds support for YAML, TOML, and custom front matter to documents.
489- [goldmark-toc](https://github.com/abhinav/goldmark-toc): Adds support for generating tables-of-contents for goldmark documents.
490- [goldmark-mermaid](https://github.com/abhinav/goldmark-mermaid): Adds support for rendering [Mermaid](https://mermaid-js.github.io/mermaid/) diagrams in goldmark documents.
491- [goldmark-pikchr](https://github.com/jchenry/goldmark-pikchr): Adds support for rendering [Pikchr](https://pikchr.org/home/doc/trunk/homepage.md) diagrams in goldmark documents.
492- [goldmark-embed](https://github.com/13rac1/goldmark-embed): Adds support for rendering embeds from YouTube links.
493- [goldmark-latex](https://github.com/soypat/goldmark-latex): A $\LaTeX$ renderer that can be passed to `goldmark.WithRenderer()`.
494- [goldmark-fences](https://github.com/stefanfritsch/goldmark-fences): Support for pandoc-style [fenced divs](https://pandoc.org/MANUAL.html#divs-and-spans) in goldmark.
495- [goldmark-d2](https://github.com/FurqanSoftware/goldmark-d2): Adds support for [D2](https://d2lang.com/) diagrams.
496- [goldmark-katex](https://github.com/FurqanSoftware/goldmark-katex): Adds support for [KaTeX](https://katex.org/) math and equations.
497- [goldmark-img64](https://github.com/tenkoh/goldmark-img64): Adds support for embedding images into the document as DataURL (base64 encoded).
498- [goldmark-enclave](https://github.com/quailyquaily/goldmark-enclave): Adds support for embedding youtube/bilibili video, X's [oembed X](https://publish.x.com/), [tradingview chart](https://www.tradingview.com/widget/)'s chart, [quaily widget](https://quaily.com), [spotify embeds](https://developer.spotify.com/documentation/embeds), [dify embed](https://dify.ai/) and html audio into the document.
499- [goldmark-wiki-table](https://github.com/movsb/goldmark-wiki-table): Adds support for embedding Wiki Tables.
500- [goldmark-tgmd](https://github.com/Mad-Pixels/goldmark-tgmd): A Telegram markdown renderer that can be passed to `goldmark.WithRenderer()`.
501- [goldmark-treeblood](https://github.com/Wyatt915/goldmark-treeblood): Renders $\LaTeX$ expressions as MathML (pure Go, no external dependencies).
502- [goldmark-subtext](https://github.com/zeozeozeo/goldmark-subtext): Support for Discord-style markdown subtexts
503- [goldmark-customtag](https://github.com/tendstofortytwo/goldmark-customtag): Allows you to define custom block tags.
504- [goldmark-cjk-friendly](https://github.com/tats-u/goldmark-cjk-friendly): Port of npm package [`remark-cjk-friendly` / `markdown-it-cjk-friendly`](https://github.com/tats-u/markdown-cjk-friendly) to goldmark. Similar to the [CJK extension](#cjk-extension) (`WithEscapedSpace`), but you do not need to explicitly add `\ ` around `*` and `**`. You can combine this with the [CJK extension](#cjk-extension).
505- [goldmark-chart](https://github.com/TheGreatRambler/goldmark-chart): Generate static ChartJS charts using the simple [Markvis](https://markvis.js.org/#/) format.
506
507### Loading extensions at runtime
508[goldmark-dynamic](https://github.com/yuin/goldmark-dynamic) allows you to write a goldmark extension in Lua and load it at runtime without re-compilation.
509
510Please refer to  [goldmark-dynamic](https://github.com/yuin/goldmark-dynamic) for details.
511
512
513goldmark internal(for extension developers)
514----------------------------------------------
515### Overview
516goldmark's Markdown processing is outlined in the diagram below.
517
518```
519            <Markdown in []byte, parser.Context>
520                           |
521                           V
522            +-------- parser.Parser ---------------------------
523            | 1. Parse block elements into AST
524            |   1. If a parsed block is a paragraph, apply 
525            |      ast.ParagraphTransformer
526            | 2. Traverse AST and parse blocks.
527            |   1. Process delimiters(emphasis) at the end of
528            |      block parsing
529            | 3. Apply parser.ASTTransformers to AST
530                           |
531                           V
532                      <ast.Node>
533                           |
534                           V
535            +------- renderer.Renderer ------------------------
536            | 1. Traverse AST and apply renderer.NodeRenderer
537            |    corespond to the node type
538
539                           |
540                           V
541                        <Output>
542```
543
544### Parsing
545Markdown documents are read through `text.Reader` interface.
546
547AST nodes do not have concrete text. AST nodes have segment information of the documents, represented by `text.Segment` .
548
549`text.Segment` has 3 attributes: `Start`, `End`, `Padding` .
550
551(TBC)
552
553**TODO**
554
555See `extension` directory for examples of extensions.
556
557Summary:
558
5591. Define AST Node as a struct in which `ast.BaseBlock` or `ast.BaseInline` is embedded.
5602. Write a parser that implements `parser.BlockParser` or `parser.InlineParser`.
5613. Write a renderer that implements `renderer.NodeRenderer`.
5624. Define your goldmark extension that implements `goldmark.Extender`.
563
564
565Donation
566--------------------
567BTC: 1NEDSyUmo4SMTDP83JJQSWi1MvQUGGNMZB
568
569License
570--------------------
571MIT
572
573Author
574--------------------
575Yusuke Inuzuka