Конвертировать 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 буквально с помощью нескольких строк кода!

1    // Prepare HTML code and save it to a file
2    String code = StringExtensions.concat("<h1>Convert HTML to Markdown Using Java</h1>",
3                "<h2>How to Convert HTML to MD in Java</h2>",
4                "<p>The Aspose.HTML for Java library allows you to convert HTML to Markdown.</p>");
5    com.aspose.html.internal.ms.System.IO.File.writeAllText("conversion.html", code);
6
7    // Call convertHTML() method
8    com.aspose.html.converters.Converter.convertHTML("conversion.html", new MarkdownSaveOptions(), Path.combine(getOutputDir(), "conversion.md"));

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

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

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, вы должны выполнить несколько шагов:

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

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

 1    // Prepare a path for converted file saving 
 2    String outputPath = Path.combine(getOutputDir(), "save-options-output.md");
 3
 4    // Prepare HTML code and save it to a file
 5    String code = StringExtensions.concat("<h1>How to Use MarkdownSaveOptions</h1>", 
 6                "<h2>setFeatures() method</h2>", 
 7                "<p>Hello, World!!!</p>", 
 8                "<a href='aspose.com'>Aspose</a>");
 9    com.aspose.html.internal.ms.System.IO.File.writeAllText(Path.combine(getOutputDir(), "save-options.html"), code);
10
11    // Create an instance of MarkdownSaveOptions and set up the rule: 
12    // – only <a> and <p> elements will be converted to Markdown
13    MarkdownSaveOptions options = new MarkdownSaveOptions();
14    options.setFeatures (MarkdownFeatures.Link | MarkdownFeatures.AutomaticParagraph);
15
16    // Convert HTML to MD
17    com.aspose.html.converters.Converter.convertHTML(Path.combine(getOutputDir(), "save-options.html"), options, outputPath);

В приведенном выше 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:

 1    // Prepare a path for converted file saving 
 2    String savePath = Path.combine(getOutputDir(), "output-git.md");
 3
 4    // Prepare HTML code and save it to the file
 5    String code = StringExtensions.concat("<h1>Header 1</h1>", 
 6                "<h2>Header 2</h2>", 
 7                "<p>Hello World!!</p>");
 8    com.aspose.html.internal.ms.System.IO.File.writeAllText(Path.combine(getOutputDir(), "document.html"), code);
 9
10    // Convert HTML to Markdown
11    com.aspose.html.converters.Converter.convertHTML(Path.combine(getOutputDir(), "document.html"), MarkdownSaveOptions.getGit(), savePath);

В приведенном выше примере 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». Чтобы использовать его, вы должны поместить один из определенных элементов, поддерживаемых этой функцией, в начале новой строки. Или вы можете пометить один из таких элементов как “Inline HTML”, добавив к этому элементу атрибут markdown со значением inline. Вот небольшой пример, демонстрирующий, как использовать этот атрибут:

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

 1    // Prepare a path for converted file saving 
 2    String savePath = Path.combine(getOutputDir(), "inline-html.md");
 3
 4    // Prepare HTML code and save it to the file
 5    String code = "text<div markdown='inline'><code>text</code></div>";
 6    com.aspose.html.internal.ms.System.IO.File.writeAllText(Path.combine(getOutputDir(), "inline.html"), code);
 7
 8    // Call convertHTML method to convert HTML to Markdown.
 9    com.aspose.html.converters.Converter.convertHTML(Path.combine(getOutputDir(), "inline.html"), new MarkdownSaveOptions(), savePath);
10
11    // 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

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

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

Конвертировать HTML в XPS Конвертировать HTML в MHTML