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

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

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

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

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

// Convert HTML to Markdown in Java

// 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("conversion.html", code);

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

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

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

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()

Свойство MarkdownSaveOptions.Features в Aspose.HTML for Java позволяет осуществлять детальный контроль над преобразованием Markdown, включая или отключая определенные функции с помощью побитовой комбинации флагов из перечисления MarkdownFeatures. Например,

• MarkdownFeatures.Link включает генерацию или сохранение гиперссылок в выходном Markdown.
• MarkdownFeatures.AutomaticParagraph преобразует элементы HTML <p> в абзацы Markdown.

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

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

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

// Convert selective HTML tags to Markdown using Java

// 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("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 HTML to Markdown
Converter.convertHTML("options.html", options, "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:

// Convert HTML to Markdown in Java using Git syntax

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

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

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

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

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

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

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

// Convert inline HTML elements to Markdown using Java

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

// Call convertHTML() method to convert HTML to Markdown
Converter.convertHTML("inline.html", new MarkdownSaveOptions(), "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 с высоким качеством, легко и быстро. Просто загрузите, конвертируйте файлы и получите результат за несколько секунд!