用 Java 将 HTML 转换为 Markdown

Markdown (MD) 是一种使用纯文本格式语法的简单标记语言。由于其格式易读易写，常用于创建文档和自述文件。它的设计使其可以很容易地转换成多种输出格式，但最初创建时只能转换成 HTML 格式。Aspose.HTML for Java 允许您进行反向转换，您可以在 Java 中轻松地将 HTML 转换为 Markdown。

本文将介绍如何使用 Converter 类的 convertHTML() 方法将 HTML 转换为 Markdown，以及如何应用 MarkdownSaveOptions。

通过几行 Java 代码将 HTML 转换为 Markdown

您可以使用 Java 和其他 Java 编程语言将 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 类

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 的更多信息，请阅读 Fine-Tuning Converters 一文。

在 Markdown 语法 一文中，您将找到有关 Markdown 主要元素、细节和 Markdown 语法示例的信息。

使用 MarkdownSaveOptions 将 HTML 转换为 Markdown

setFeatures()方法

Aspose.HTML for Java 中的 MarkdownSaveOptions.Features 属性允许通过对 MarkdownFeatures 枚举中的标志进行比特组合来启用或禁用特定功能，从而对 Markdown 转换进行细粒度控制。例如

• MarkdownFeatures.Link 可以在输出的 Markdown 中生成或保留超链接。
• MarkdownFeatures.AutomaticParagraph 可将 HTML 中的<p>元素转换为 Markdown 段落。

要将指定了 MarkdownSaveOptions.Features 的 HTML 转换为 Markdown，应遵循以下几个步骤：

1. 一种常用的方法是使用 HTMLDocument 类的 HTMLDocument() 构造函数加载 HTML 文件。但在本例中，我们通过编写 HTML 代码并将其保存到文件中，从头开始创建 HTML 源文件。
2. 创建一个新的 MarkdownSaveOptions 对象。使用 setFeatures() 在 HTML 到 Markdown 的转换中启用超链接生成和自动段落格式化。
3. 使用 Converter 类的 convertHTML(sourcePath, options, outputPath) 方法将 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 是 GitHub.com 版本的 Markdown 语法，它提供了一系列额外的有用功能，使用户能更轻松地处理 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 的实例。我们使用 MarkdownSaveOptions 中的 getGit() 方法，该方法会返回一个已启用 Git 的 options 实例。在 MarkdownSaveOptions 中启用 Git 意味着生成的 Markdown 输出文件将包含 Git 风格的 Markdown，即包含 Git 特有功能的 Markdown 语法。

限制

Markdown 是一种轻量级且易于使用的语法。并非所有 HTML 元素都可以转换为 Markdown，因为 Markdown 语法中没有对应的元素。在转换过程中， STYLE、 SCRIPT、 LINK、 EMBED 等元素将被丢弃。

内联 HTML - Inline HTML

Markdown 允许您指定纯 HTML 代码，这些代码将按原样渲染。实现此功能的特性称为 Inline HTML。要使用此功能，您应该将支持此功能的特定元素之一放在新行的开头。或者，您可以通过向此类元素添加 markdown 属性并将其值设置为 inline 来将其标记为Inline HTML。以下是一个演示如何使用此属性的小示例：

// 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、ide aside、header、address、hr、dd、figure、figcaption、 abbr、video、audio、output、canvas、section、details、hgroup、summary。

功能嵌套

尽管 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 利用convertHTML()方法和可定制的MarkdownSaveOptions，为 HTML 到 Markdown 的转换提供了强大的工具。

MarkdownSaveOptions 类为开发人员提供了对转换过程的精细控制。它包括启用或禁用特定 HTML 元素、设置格式样式和有效处理资源的功能。对于高级应用场景，可使用 GitHub Flavored Markdown (GFM) 等预定义选项，从而与支持扩展 Markdown 语法的平台实现无缝集成。

不过，由于 Markdown 的轻量级特性，它也存在一些限制。某些 HTML 元素，如<style>和<script>，缺乏直接的 Markdown 对应元素，因此在转换过程中会被省略。尽管如此，Markdown 对 “内联 HTML “的支持为包含不支持的元素提供了一种变通方法。

您可以从 GitHub 下载完整的示例和数据文件。

Aspose.HTML 提供免费的在线 HTML 到 Markdown 转换器，可将 HTML 高质量、方便快捷地转换为 Markdown。只需上传、转换您的文件，几秒钟就能得到结果！