Рендерер.рендер(документ); // "## My title\n"

Для рендеринга в простой текст с минимальной разметкой также существует TextContentRenderer.

Используйте посетителя для обработки разобранных узлов

После того как исходный текст был разобран, результатом является дерево узлов. Это дерево можно изменить перед рендерингом или просто проверить без рендеринга:

Node node = parser.parse("Example\n=======\n\nSome more text");
WordCountVisitor visitor = new WordCountVisitor();
node.accept(visitor);
visitor.wordCount;  // 4

class WordCountVisitor extends AbstractVisitor {
    int wordCount = 0;

    @Override
    public void visit(Text text) {
        // Этот метод вызывается для всех текстовых узлов. Переопределите другие методы посещения для других типов узлов.

        // Считаем слова (это всего лишь пример, на самом деле не делайте этого по разным причинам).
        wordCount += text.getLiteral().split("\\W+").length;

        // Спускаемся к детям (в этом случае можно было бы опустить, потому что у текстовых узлов нет детей).
        visitChildren(text);
    }
}

Добавьте или измените атрибуты HTML-элементов

Иногда вы можете захотеть настроить способ рендеринга HTML. Если всё, что вы хотите сделать, это добавить или изменить атрибуты некоторых элементов, есть простой способ сделать это.

В этом примере мы регистрируем фабрику для AttributeProvider на рендерере, чтобы установить атрибут class="border" для элементов img.

Parser parser = Parser.builder().build();
HtmlRenderer renderer = HtmlRenderer.builder()
        .attributeProviderFactory(new AttributeProviderFactory() {
            public AttributeProvider create(AttributeProviderContext context) {
                return new ImageAttributeProvider();
            }
        })
        .build();

Node document = parser.parse("![text](/url.png)");
renderer.render(document);
// "<p><img src=\"/url.png\" alt=\"text\" class=\"border\" /></p>\n"

class ImageAttributeProvider implements AttributeProvider {
    @Override
    public void setAttributes(Node node, String tagName, Map<String, String> attributes) {
        if (node instanceof Image) {
            attributes.put("class", "border");
        }
    }
}

Настройте рендеринг HTML

Если вы хотите сделать больше, чем просто изменить атрибуты, есть также способ полностью контролировать способ рендеринга HTML.

В этом примере мы меняем рендеринг отступов блоков кода, чтобы они были заключены только в pre, а не в pre и code:

Parser parser = Parser.builder().build();
HtmlRenderer renderer = HtmlRenderer.builder()
        .nodeRendererFactory(new HtmlNodeRendererFactory() {
            public NodeRenderer create(HtmlNodeRendererContext context) {
                return new IndentedCodeBlockNodeRenderer(context);
            }
        })
        .build();

Node document = parser.parse("Example:\n\n    code");
renderer.render(document);
// "<p>Example:</p>\n<pre>code\n</pre>\n"

class IndentedCodeBlockNodeRenderer implements NodeRenderer {

    private final HtmlWriter html;

    IndentedCodeBlockNodeRenderer(HtmlNodeRendererContext context) {
        this.html = context.getWriter();
    }

    @Override
    public Set<Class<? extends Node>> getNodeTypes() {
        // Возвращаем типы узлов, для которых мы хотим использовать этот рендерер.
        return Set.of(IndentedCodeBlock.class);
    }

    @Override
    public void render(Node node) {
        // Мы обрабатываем только один тип в соответствии с getNodeTypes, поэтому здесь мы можем просто привести его.
        IndentedCodeBlock codeBlock = (IndentedCodeBlock) node;
        html.line();
        html.tag("pre");
        html.text(codeBlock.getLiteral());
        html.tag("/pre");
        html.line();
    }
}

Добавьте свои собственные типы узлов

Если вы хотите сохранить дополнительные данные в документе или иметь пользовательские элементы в результирующем HTML, вы можете создать свой собственный подкласс CustomNode и добавить экземпляры в качестве дочерних узлов к существующим узлам.

Чтобы определить рендеринг HTML для них, вы можете использовать NodeRenderer, как описано выше.

Настройка парсинга

Существует несколько способов расширить синтаксический анализ или даже переопределить встроенный синтаксический анализ, все они через методы. on Parser.Builder (см. Blocks and inlines в спецификации для обзора блоков/вставок):

— Разбор определённых типов блоков (например, заголовков, блоков кода и т. д.) можно включить/отключить с помощью enabledBlockTypes.

— Разбирать блоки можно расширить/переопределить с помощью customBlockParserFactory.

— Разобрать встроенный контент можно расширить/переопределить с помощью customInlineContentParserFactory.

— Разбор разделителей во встроенном контенте можно расширить с помощью customDelimiterProcessor.

Поточная безопасность

И Parser, и HtmlRenderer спроектированы таким образом, чтобы вы могли настроить их один раз с помощью билдеров, а затем использовать их многократно/из нескольких потоков. Это делается путём разделения состояния для разбора/рендеринга от конфигурации.

При этом, конечно, могут быть ошибки. Если вы обнаружите одну из них, пожалуйста, сообщите о проблеме.

Документация по API

Javadocs доступны онлайн на javadoc.io.

Расширения

Расширения должны расширять парсер или HTML-рендерер, либо и то, и другое. Чтобы использовать расширение, объекты билдера можно настроить со списком расширений. Поскольку расширения являются необязательными, они живут в отдельных артефактах, поэтому необходимо добавить дополнительные зависимости.

Давайте посмотрим, как включить таблицы из GitHub Flavored Markdown. Сначала добавьте дополнительную зависимость (см. Maven Central для других):

<dependency>
    <groupId>org.commonmark</groupId>
    <artifactId>commonmark-ext-gfm-tables</artifactId>
    <version>0.22.0</version>
</dependency>

Затем настройте расширение на билдерах:

import org.commonmark.ext.gfm.tables.TablesExtension;

List<Extension> extensions = List.of(TablesExtension.create());
Parser parser = Parser.builder()
        .extensions(extensions)
        .build();
HtmlRenderer renderer = HtmlRenderer.builder()
        .extensions(extensions)
        .build();

Чтобы настроить другое расширение в приведённом выше примере, просто добавьте его в список.

Следующие расширения разработаны с использованием этой библиотеки, каждое в своём собственном артефакте.

Autolink

Превращает простые ссылки, такие как URL-адреса и адреса электронной почты, в ссылки (на основе autolink-java).

Используйте класс AutolinkExtension из артефакта commonmark-ext-autolink.

Strikethrough

Включает зачёркивание текста, заключая его в ~~. Например, в hey you слово you будет отображаться как зачёркнутый текст.

Используйте класс StrikethroughExtension в артефакте commonmark-ext-gfm-strikethrough.

Tables

Включение таблиц с использованием каналов, как в GitHub Flavored Markdown.

Используйте класс TablesExtension в артефакте commonmark-ext-gfm-tables.

Heading anchor

Позволяет добавлять автоматически генерируемые атрибуты «id» к тегам заголовков. «Id» основан на тексте заголовка.

# Heading будет отображаться следующим образом:

<h1 id="heading">Heading</h1>

Используйте класс HeadingAnchorExtension в артефакте commonmark-ext-heading-anchor.

Если вы хотите настроить рендеринг заголовка, вы можете использовать класс IdGenerator напрямую вместе с фабрикой HtmlNodeRendererFactory (см. пример выше).

Ins

Включает подчёркивание текста, помещая его в ++. Например, в hey ++you++ слово you будет отображаться как подчёркнутый текст. Использует тег <ins>.

Используйте класс InsExtension в артефакте commonmark-ext-ins.

YAML front matter

Добавляет поддержку метаданных через блок YAML front matter. Это расширение поддерживает только подмножество синтаксиса YAML. Вот пример того, что поддерживается:

---
key: value
list:
  - value 1
  - value 2
literal: |
  this is literal value.

  literal values 2
---

document start here

Используйте класс YamlFrontMatterExtension в артефакте commonmark-ext-yaml-front-matter. Чтобы получить метаданные, используйте YamlFrontMatterVisitor.

Image Attributes

Добавляет поддержку указания атрибутов (в частности, высоты и ширины) для изображений.

Элементы атрибута задаются в виде пар key=value внутри фигурных скобок { } после ### Список задач

Добавляет поддержку для задач в виде элементов списка.

Задача может быть представлена как элемент списка, где первым символом без пробела является левая квадратная скобка [, затем один пробел или буква x в нижнем или верхнем регистре, затем правая квадратная скобка ], за которой следует хотя бы один пробел перед любым другим содержимым.

Например:

- [ ] задача №1
- [x] задача №2

будет отображаться следующим образом:

<ul>
<li><input type="checkbox" disabled=""> задача №1</li>
<li><input type="checkbox" disabled="" checked=""> задача №2</li>
</ul>

Используйте класс TaskListItemsExtension в артефакте commonmark-ext-task-list-items.

Сторонние расширения

Вы также можете найти другие расширения в сети:

• commonmark-ext-notifications: это расширение позволяет легко создавать абзацы уведомлений/предупреждений, такие как INFO, SUCCESS, WARNING или ERROR.

См. также:

• Markwon: библиотека Android для рендеринга markdown в качестве системных нативных Spannables.
• flexmark-java: форк, который добавил поддержку гораздо большему количеству синтаксиса и гибкости.

Вклад

Смотрите файл CONTRIBUTING.md.

Лицензия

Авторские права (c) Atlassian и другие.

Лицензия BSD (2-clause), см. файл LICENSE.txt.