Конвертировать HTML в Markdown на Java

Markdown (MD) – это простой язык разметки, использующий синтаксис форматирования обычного текста. Он обычно используется для создания документации и файлов readme из-за его легкого для чтения и написания формата. Его дизайн позволяет легко преобразовывать его во многие форматы вывода, но изначально он был создан для преобразования только в HTML. Aspose.HTML предоставляет библиотеку классов, которая позволяет преобразовывать HTML в формат Markdown на Java и других языках программирования Java, предлагая обратное преобразование из HTML в Markdown.

В этой статье вы найдете информацию о том, как конвертировать HTML в Markdown с помощью методов convertHTML() Converter класса и как применить MarkdownSaveOptions.

HTML в Markdown с помощью нескольких строк кода

Вы можете преобразовать HTML в формат Markdown, используя Java и другие языки программирования Java. Статические методы класса Converter в основном используются как самый простой способ преобразования HTML-кода в различные форматы. Следующий фрагмент кода показывает, как преобразовать HTML в Markdown буквально с помощью нескольких строк кода!

// Prepare HTML code and save it to a file
String code = "<h1>Convert HTML to Markdown Using Java</h1>" +
        "<h2>How to Convert HTML to MD in Java</h2>" +
        "<p>The Aspose.HTML for Java library allows you to convert HTML to Markdown.</p>";
FileHelper.writeAllText($o("conversion.html"), code);

// Call ConvertHTML() method to convert HTML to Markdown
Converter.convertHTML($o("conversion.html"), new MarkdownSaveOptions(), $o("conversion.md"));

Параметры сохранения

Параметр MarkdownSaveOptions имеет ряд свойств, позволяющих контролировать процесс преобразования. Наиболее важным параметром является «arkdownFeatures. Эта опция позволяет включить/отключить преобразование конкретного элемента.

Method	Description
getDefault()	This method returns a set of options that are compatible with default Markdown documentation.
setFeatures(value)	A flag set that controls which HTML elements are converted to Markdown.
setFormatter(value)	This method gets or sets the Markdown formatting style.
getGit()	This method returns a set of options that are compatible with GitLab Flavored Markdown.
getResourceHandlingOptions()	Gets a ResourceHandlingOptions object which is used for configuration of resources handling.

Чтобы узнать больше о MarkdownSaveOptions, прочитайте статью Конвертеры тонкой настройки.

В статье Синтаксис Markdown вы найдете информацию об основных элементах Markdown, подробности и примеры синтаксиса Markdown.

Конвертировать HTML в Markdown на Java с использованием MarkdownSaveOptions

Метод setFeatures()

Чтобы конвертировать HTML в Markdown с указанием MarkdownSaveOptions, вы должны выполнить несколько шагов:

1. Одним из популярных сценариев является загрузка файла HTML с помощью одного из конструкторов HTMLDocument() класса HTMLDocument. Но в этом примере мы создаем источник HTML с нуля, подготавливая код HTML и сохраняя его в файл.
2. Создайте новый объект MarkdownSaveOptions. Объект MarkdownSaveOptions можно настроить для указания различных параметров процесса преобразования.
3. Используйте метод convertHTML(sourcePath, options, outputPath) класса Converter, чтобы сохранить HTML как файл Markdown.

В следующем примере показано, как обрабатывать только ссылки и абзацы, остальные элементы HTML остаются без изменений:

// Prepare HTML code and save it to the file
String code = "<h1>Header 1</h1>" +
        "<h2>Header 2</h2>" +
        "<p>Hello, World!!</p>" +
        "<a href='aspose.com'>aspose</a>";
FileHelper.writeAllText($o("options.html"), code);

// Create an instance of SaveOptions and set up the rule:
// - only <a> and <p> elements will be converted to Markdown
MarkdownSaveOptions options = new MarkdownSaveOptions();
options.setFeatures(MarkdownFeatures.Link | MarkdownFeatures.AutomaticParagraph);

// Call the ConvertHTML() method to convert the HTML to Markdown
Converter.convertHTML($o("options.html"), options, $o("options-output.md"));

В приведенном выше Java-коде создается объект options, и два параметра устанавливаются с помощью метода setFeatures(). Функция Link указывает, что элементы HTML <a> будут преобразованы в Markdown, а функция AutomaticParagraph определяет, что элементы HTML <p> будут преобразованы в Markdown. Любые другие элементы в документе HTML не будут преобразованы.

Метод getGit()

GitHub Flavored Markdown – это версия синтаксиса Markdown для GitHub.com, которая предоставляет дополнительный набор полезных функций, облегчающих работу с контентом на GitHub.com. Это расширение стандартного синтаксиса Markdown, добавляющее множество дополнительных функций, включая подсветку кода, списки задач, таблицы и многое другое. Чтобы преобразовать HTML в Markdown, вы можете определить свой собственный набор правил или использовать предопределенные шаблоны. Например, вы можете использовать шаблон на основе синтаксиса GitLab Flavored Markdown:

// Prepare HTML code and save it to the file
String code = "<h1>Header 1</h1>" +
        "<h2>Header 2</h2>" +
        "<p>Hello World!!</p>";
FileHelper.writeAllText($o("document.html"), code);

// Call ConvertHTML() method to convert HTML to Markdown
Converter.convertHTML($o("document.html"), MarkdownSaveOptions.getGit(), $o("output-git.md"));

В приведенном выше примере Java метод convertHTML(sourcePath, options, outputPath) выполняет преобразование. Он принимает три аргумента: sourcePath, options и outputPath. Второй аргумент – это экземпляр MarkdownSaveOptions. Мы используем метод getGit() в MarkdownSaveOptions, который возвращает экземпляр options с включенным Git. Включение Git в MarkdownSaveOptions означает, что сгенерированный выходной файл Markdown будет содержать Markdown со вкусом Git, синтаксис Markdown, который включает функции, специфичные для Git.

Ограничение – Limitation

Markdown – это легкий и простой в использовании синтаксис. Не все элементы HTML можно преобразовать в Markdown, поскольку в синтаксисе Markdown нет эквивалента. Такие элементы, как STYLE, SCRIPT, LINK, EMBED и т. д. будут удалены при преобразовании.

Встроенный HTML – Inline HTML

Markdown позволяет вам указать чистый HTML-код, который будет отображаться как есть. Функция, которая позволяет это поведение, называется «Встроенный HTML». Чтобы использовать ее, вы должны поместить один из определенных элементов, поддерживаемых этой функцией, в начало новой строки. Или вы можете пометить один из таких элементов как «Встроенный HTML», добавив атрибут markdown со значением inline к этому элементу. Вот небольшой пример, демонстрирующий, как использовать этот атрибут:

// Prepare an HTML code and save it to the file.
String code = "text<div markdown='inline'><code>text</code></div>";
FileHelper.writeAllText($o("inline.html"), code);

// Call ConvertHTML() method to convert HTML to Markdown.
Converter.convertHTML($o("inline.html"), new MarkdownSaveOptions(), $o("inline-html.md"));

// Output file will contain: text\r\n<div markdown="inline"><code>text</code></div>

Как видите, содержимое элемента <div> не преобразуется в Markdown и обрабатывается процессором Markdown как есть. Список элементов, поддерживающих эту функцию, различен для каждого процессора Markdown.

Исходная спецификация Markdown поддерживает следующие теги: BLOCKQUOTE, H1, H2, H3, H4, H5, H6, P, PRE, OL, UL, DL, DIV, INS, DEL, IFRAME, FIELDSET, NOSCRIPT, FORM, MATH.

GitLab Flavored Markdown расширяет этот список следующими тегами: ARTICLE, FOOTER, NAV, ASIDE, HEADER, ADDRESS, HR, DD, FIGURE, FIGCAPTION, ABBR, VIDEO, AUDIO, OUTPUT, CANVAS, SECTION, DETAILS, HGROUP, SUMMARY.

Особенности вложения – Features nesting

Хотя Markdown поддерживает широкий спектр функций, не все из них можно комбинировать. Например, элементы списка внутри элементов таблицы не будут преобразованы. В таблице ниже показано, какие объекты могут быть вложены. Каждая функция является членом перечисления MarkdownFeatures.

Parent feature	Features which can be processed inside
Header	Link, Emphasis, Strong, InlineCode, Image, Strikethrough, Video
Blockquote	Any
List	AutomaticParagraph, Link, Emphasis, Strong, InlineCode, Image, LineBreak, Strikethrough, Video, TaskList, List
Link	Emphasis, Strong, InlineCode, Image, LineBreak, Strikethrough
AutomaticParagraph	Link, Emphasis, Strong, InlineCode, Image, LineBreak, Strikethrough
Strikethrough	Link, Emphasis, Strong, InlineCode, Image, LineBreak
Table	Video, Strikethrough, Image, InlineCode, Emphasis, Strong, Link
Emphasis	Link, InlineCode, Image, LineBreak, Strikethrough, Video
Strong	Link, InlineCode, Image, LineBreak, Strikethrough, Video

Заключение

Aspose.HTML for Java предоставляет мощные инструменты для преобразования HTML в Markdown, используя метод convertHTML() и настраиваемые MarkdownSaveOptions.

Класс MarkdownSaveOptions дает разработчикам детальный контроль над процессом преобразования. Он включает функции для включения или отключения определенных элементов HTML, установки стилей форматирования и эффективной обработки ресурсов. Для расширенных сценариев доступны предопределенные параметры, такие как GitHub Flavored Markdown (GFM), что обеспечивает бесшовную интеграцию с платформами, поддерживающими расширенный синтаксис Markdown.

Однако существуют ограничения из-за легковесной природы Markdown. Некоторые элементы HTML, такие как <style> и <script>, не имеют прямых эквивалентов Markdown и опускаются во время преобразования. Тем не менее, поддержка Markdown встроенного HTML обеспечивает обходной путь для включения неподдерживаемых элементов.

Вы можете скачать полные примеры и файлы данных по адресу GitHub.

Aspose.HTML предлагает бесплатный онлайн Конвертер HTML в Markdown, который конвертирует HTML в Markdown с высоким качеством, легко и быстро. Просто загрузите, конвертируйте файлы и получите результат за несколько секунд!