goldmark

$ go get github.com/yuin/goldmark

import (
    "bytes"
    "github.com/yuin/goldmark"
)

var buf bytes.Buffer
if err := goldmark.Convert(source, &buf); err != nil {
  panic(err)
}

var buf bytes.Buffer
if err := goldmark.Convert(source, &buf, parser.WithContext(ctx)); err != nil {
  panic(err)
}

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)
}
```| Функциональный параметр | Тип | Описание |
| ------------------------ | ---- | ----------- |
| `goldmark.WithParser` | `parser.Parser` | Этот параметр должен передаваться до `goldmark.WithParserOptions` и `goldmark.WithExtensions` |
| `goldmark.WithRenderer` | `renderer.Renderer` | Этот параметр должен передаваться до `goldmark.WithRendererOptions` и `goldmark.WithExtensions` |
| `goldmark.WithParserOptions` | `...parser.Option` |  |
| `goldmark.WithRendererOptions` | `...renderer.Option` |  |
| `goldmark.WithExtensions` | `...goldmark.Extender` |  |Параметры парсера и рендера
------------------------------

### Параметры парсера

| Функциональный параметр | Тип | Описание |
| ----------------------- | ---- | ----------- |
| `parser.WithBlockParsers` | `util.PrioritizedSlice`, чьи элементы являются `parser.BlockParser` | Парсеры для анализа элементов уровня блока. |
| `parser.WithInlineParsers` | `util.PrioritizedSlice`, чьи элементы являются `parser.InlineParser` | Парсеры для анализа элементов уровня встроенной строки. |
| `parser.WithParagraphTransformers` | `util.PrioritizedSlice`, чьи элементы являются `parser.ParagraphTransformer` | Преобразователи для преобразования узлов абзаца. |
| `parser.WithASTTransformers` | `util.PrioritizedSlice`, чьи элементы являются `parser.ASTTransformer` | Преобразователи для преобразования AST. |
| `parser.WithAutoHeadingID` | `-` | Включает автоматическое создание ID для заголовков. |
| `parser.WithAttributes` | `-` | Включает пользовательские атрибуты. В настоящее время поддерживаются только заголовки с атрибутами. |

### Параметры рендера HTML

| Функциональный параметр | Тип | Описание |
| ----------------------- | ---- | ----------- |
| `html.WithWriter` | `html.Writer` | `html.Writer` для записи содержимого в `io.Writer`. |
| `html.WithHardWraps` | `-` | Отображение новой строки как `<br>`. |
| `html.WithXHTML` | `-` | Отображение как XHTML. |
| `html.WithUnsafe` | `-` | По умолчанию, goldmark не отображает сырой HTML или потенциально опасные ссылки. С этим параметром goldmark отображает такое содержимое так, как это записано. |

### Встроенные расширения- `extension.Table`
    - [GitHub Flavored Markdown: Tables](https://github.github.com/gfm/#tables-extension-)
- `extension.Strikethrough`
    - [GitHub Flavored Markdown: Strikethrough](https://github.github.com/gfm/#strikethrough-extension-)
- `extension.Linkify`
    - [GitHub Flavored Markdown: Autolinks](https://github.github.com/gfm/#autolinks-extension-)
- `extension.TaskList`
    - [GitHub Flavored Markdown: Task list items](https://github.github.com/gfm/#task-list-items-extension-)
- `extension.GFM`
    - Это расширение включает таблицы, зачеркивание, автоссылки и задачи.
    - Это расширение не фильтрует теги, определённые в [6.11: Недопустимый сырой HTML (расширение)](https://github.github.com/gfm/#disallowed-raw-html-extension-).
    Если вам требуется фильтровать HTML-теги, см. раздел [Безопасность](#security).
    - Если вам требуется парсинг эмодзи GitHub, вы можете использовать [goldmark-emoji](https://github.com/yuin/goldmark-emoji) расширение.
- `extension.DefinitionList`
    - [PHP Markdown Extra: Определитель списков](https://michelf.ca/projects/php-markdown/extra/#def-list)
- `extension.Footnote`
    - [PHP Markdown Extra: Примечания](https://michelf.ca/projects/php-markdown/extra/#footnotes)
- `extension.Typographer`
    - Это расширение заменяет знаки препинания на типографские сущности, как [smartypants](https://daringfireball.net/projects/smartypants/).
- `extension.CJK`
    - Это расширение является сокращением для связанных с CJK функциональностей.

### Атрибуты
Параметр `parser.WithAttribute` позволяет вам определять атрибуты для некоторых элементов.

На данный момент атрибуты поддерживаются только для заголовков.

**Атрибуты обсуждаются на форуме [CommonMark](https://talk.commonmark.org/t/consistent-attribute-syntax/272). 
Синтаксис может измениться в будущем.**#### Заголовки

```markdown
## Заголовок ## {#id .className attrName=attrValue class="class1 class2"}

## Заголовок {#id .className attrName=attrValue class="class1 class2"}

Заголовок {#id .className attrName=attrValue}
=================

markdown := goldmark.New(
    goldmark.WithExtensions(
        extension.NewTypographer(
            extension.WithTypographicSubstitutions(extension.TypographicSubstitutions{
                extension.LeftSingleQuote:  []byte("‚"),
                extension.RightSingleQuote: nil, // nil отключает замену
            }),
        ),
    ),
)
```### Расширение Linkify

Расширение Linkify реализует [Автоссылки](https://github.github.com/gfm/#autolinks-extension/), как
определяется в [Спецификации GitHub Flavored Markdown](https://github.github.com/gfm/).

Поскольку спецификация не определяет детали URL, существует множество неоднозначных случаев.

Вы можете переопределить шаблоны автоссылок через параметры.

| Функциональный параметр | Тип | Описание |
| ------------------------ | ---- | ----------- |
| `extension.WithLinkifyAllowedProtocols` | `[][]byte \| []string` | Список допустимых протоколов, таких как `[]string{"http:"}` |
| `extension.WithLinkifyURLRegexp` | `*regexp.Regexp` | Шаблон регулярного выражения, который определяет URL, включая протоколы |
| `extension.WithLinkifyWWWRegexp` | `*regexp.Regexp` | Шаблон регулярного выражения, который определяет URL, начинающийся с `www.`. Этот шаблон соответствует [расширенной автоссылке www](https://github.github.com/gfm/#extended-www-autolink/) |
| `extension.WithLinkifyEmailRegexp` | `*regexp.Regexp` | Шаблон регулярного выражения, который определяет адрес электронной почты |

Пример использования [xurls](https://github.com/mvdan/xurls):

```go
import "mvdan.cc/xurls/v2"

markdown := goldmark.New(
    goldmark.WithRendererOptions(
        html.WithXHTML(),
        html.WithUnsafe(),
    ),
    goldmark.WithExtensions(
        extension.NewLinkify(
            extension.WithLinkifyAllowedProtocols([]string{
                "http:",
                "https:",
            }),
            extension.WithLinkifyURLRegexp(
                xurls.Strict(),
            ),
        ),
    ),
)

for _, path := range files {
    source := readAll(path)
    prefix := getPrefix(path)
}
```    markdown := goldmark.New(
        goldmark.WithExtensions(
            NewFootnote(
                WithFootnoteIDPrefix(path),
            ),
        ),
    )
    var b bytes.Buffer
    err := markdown.Convert(source, &b)
    if err != nil {
        t.Error(err.Error())
    }
}
````extension.WithFootnoteIDPrefixFunction` определяет префикс ID, вызывая данную функцию, поэтому вы можете писать код в следующем виде:

```go
markdown := goldmark.New(
    goldmark.WithExtensions(
        NewFootnote(
                WithFootnoteIDPrefixFunction(func(n gast.Node) []byte {
                    v, ok := n.OwnerDocument().Meta()["footnote-prefix"]
                    if ok {
                        return util.StringToReadOnlyBytes(v.(string))
                    }
                    return nil
                }),
        ),
    ),
)

for _, path := range files {
    source := readAll(path)
    var b bytes.Buffer

    doc := markdown.Parser().Parse(text.NewReader(source))
    doc.Meta()["footnote-prefix"] = getPrefix(path)
    err := markdown.Renderer().Render(&b, source, doc)
}

---
title: document title
slug: article1
footnote-prefix: article1
---

# Моя статья

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

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

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

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

BenchmarkMarkdown/Blackfriday-v2-8                   302           3743747 ns/op         3290445 B/op      20050 allocs/op
BenchmarkMarkdown/GoldMark-8                          280           4200974 ns/op         2559738 B/op      13435 allocs/op
BenchmarkMarkdown/CommonMark-8                        226           5283686 ns/op         2702490 B/op      20792 allocs/op
BenchmarkMarkdown/Lute-8                               12          92652857 ns/op        10602649 B/op      40555 allocs/op
BenchmarkMarkdown/GoMarkdown-8                         13          81380167 ns/op         2245002 B/op      22889 allocs/op

Как видно, производительность goldmark соответствует производительности cmark.Расширения
--------------------
### Список расширений

- [goldmark-meta](https://github.com/yuin/goldmark-meta): Расширение YAML метаданных для парсера Markdown goldmark.
- [goldmark-highlighting](https://github.com/yuin/goldmark-highlighting): Расширение синтаксического выделения для парсера Markdown goldmark.
- [goldmark-emoji](https://github.com/yuin/goldmark-emoji): Расширение эмодзи для парсера Markdown goldmark.
- [goldmark-mathjax](https://github.com/litao91/goldmark-mathjax): Поддержка MathJax для парсера Markdown goldmark.
- [goldmark-pdf](https://github.com/stephenafamo/goldmark-pdf): Представление в виде PDF, которое можно передать методу `goldmark.WithRenderer()`.
- [goldmark-hashtag](https://github.com/abhinav/goldmark-hashtag): Добавляет поддержку тегирования на основе `#hashtag` для goldmark.
- [goldmark-wikilink](https://github.com/abhinav/goldmark-wikilink): Добавляет поддержку ссылок типа `[[wiki]]` для goldmark.
- [goldmark-anchor](https://github.com/abhinav/goldmark-anchor): Добавляет анкоры (постоянные ссылки) рядом со всеми заголовками в документе.
- [goldmark-figure](https://github.com/mangoumbrella/goldmark-figure): Добавляет поддержку отображения абзацев, начинающихся с изображения, как элементы `<figure>`.
- [goldmark-frontmatter](https://github.com/abhinav/goldmark-frontmatter): Добавляет поддержку YAML, TOML и пользовательских данных в начале документов.
- [goldmark-toc](https://github.com/abhinav/goldmark-toc): Добавляет поддержку генерации оглавлений для документов goldmark.
- [goldmark-mermaid](https://github.com/abhinav/goldmark-mermaid): Добавляет поддержку отображения диаграмм Mermaid в документах goldmark.
- [goldmark-pikchr](https://github.com/jchenry/goldmark-pikchr): Добавляет поддержку отображения диаграмм Pikchr в документах goldmark.
- [goldmark-embed](https://github.com/com/13rac1/goldmark-embed): Добавляет поддержку отображения встраиваемых объектов из ссылок YouTube.
- [goldmark-latex](https://github.com/soypat/goldmark-latex): Представление LaTeX, которое можно передать методу `goldmark.WithRenderer()`.
- [goldmark-fences](https://github.com/stefanfritsch/goldmark-fences): Поддержка разделителей стилей Pandoc для парсера Markdown goldmark.
- [goldmark-d2](https://github.com/FurqanSoftware/goldmark-d2): Добавляет поддержку диаграмм D2.
- [goldmark-katex](https://github.com/FurqanSoftware/goldmark-katex): Добавляет поддержку математических выражений и уравнений KaTeX.
- [goldmark-img64](https://github.com/tenkoh/goldmark-img64): Добавляет поддержку встраивания изображений в документ как DataURL (зашифрованные base64).
- [goldmark-enclave](https://github.com/quailyquaily/goldmark-enclave): Добавляет поддержку встраивания видео с YouTube/Bilibili, [oembed X](https://publish.x.com/), [графики TradingView](https://www.tradingview.com/widget/), [виджета Quaily](https://quaily.com), [встроенных Spotify](https://developer.spotify.com/documentation/embeds), [встроенных Dify](https://dify.ai/) и аудио HTML в документ.
- [goldmark-wiki-table](https://github.com/movsb/goldmark-wiki-table): Добавляет поддержку встраивания таблиц Wikipedia.
- [goldmark-tgmd](https://github.com/Mad-Pixels/goldmark-tgmd): Представитель рендера Markdown для Telegram, который можно передать в `goldmark.WithRenderer()`.

### Загрузка расширений в режиме выполнения
[goldmark-dynamic](https://github.com/yuin/goldmark-dynamic) позволяет вам писать расширение для goldmark на Lua и загружать его в режиме выполнения без необходимости повторной компиляции.Для получения подробностей обратитесь к [goldmark-dynamic](https://github.com/yuin/goldmark-dynamic).

Goldmark внутренний (для разработчиков расширений)
---------------------------------------------------
### Обзор
Структура процессинга Markdown в Goldmark представлена ниже.

        <Markdown в []byte, parser.Context>
                       |
                       V
        +-------- parser.Parser ---------------------------
        | 1. Парсинг блочных элементов в AST
        |   1. Если парсится абзац, применяется 
        |      ast.ParagraphTransformer
        | 2. Прохождение по AST и парсинг блоков.
        |   1. Обработка разделителей(элементов выделения) в конце
        |      парсинга блока
        | 3. Применение parser.ASTTransformers к AST
                       |
                       V
                  <ast.Node>
                       |
                       V
        +------- renderer.Renderer ------------------------
        | 1. Прохождение по AST и применение renderer.NodeRenderer
        |    соответствующего типа узла

                       |
                       V
                    <Выход>

### Парсинг
Документы Markdown читаются через интерфейс `text.Reader`.

Узлы AST не содержат конкретного текста. Узлы AST имеют информацию о сегментах документов, представленную как `text.Segment`.

`text.Segment` имеет три атрибута: `Start`, `End`, `Padding`.

(TBC)

**TODO**

Примеры расширений можно найти в директории `extension`.

Сводка:1. Определите узел AST как структуру, содержащую встраивание `ast.BaseBlock` или `ast.BaseInline`.
2. Напишите парсер, реализующий `parser.BlockParser` или `parser.InlineParser`.
3. Напишите рендерер, реализующий `renderer.NodeRenderer`.
4. Определите ваше расширение для Goldmark, реализующее `goldmark.Extender`.Пожертвования
--------------------
BTC: 1NEDSyUmo4SMTDP83JJQSWi1MvQUGGNMZB

Лицензия
--------------------
MIT

Автор
--------------------
Юсуке Инузuka