在现代开发中，Markdown 已经成为了一种广泛使用的轻量级标记语言，特别是在文档、博客和内容管理系统中，Markdown 为开发者提供了快速、简洁的格式化文本方式。而在 .NET 生态中，Markdig 是一款非常强大的 Markdown 解析器，它不仅支持标准的 Markdown 语法，还提供了许多扩展功能，让开发者能够灵活地定制 Markdown 文本的解析与渲染。
本文将详细介绍 Markdig 的基本用法、扩展功能、定制渲染及自定义扩展等方面，帮助你深入理解 Markdig，并充分发挥它的强大能力。
1. Markdig 简介
Markdig 是一款基于 .NET 平台的 Markdown 解析器，它具有以下特点：
- 高性能：Markdig 采用了优化的解析方式，在解析大文件时表现出色。
- 扩展性强：Markdig 支持多种扩展功能，能够满足不同 Markdown 渲染需求。
- 完全兼容 CommonMark：Markdig 完全兼容 CommonMark 规范，支持大多数标准 Markdown 语法，并且在此基础上提供了额外功能。
- 易于自定义：Markdig 允许开发者定制解析器和渲染器，甚至可以编写自己的扩展功能。
1.1 安装 Markdig
要在 .NET 项目中使用 Markdig，可以通过 NuGet 包管理器安装：
dotnet add package Markdig
安装完成后，你就可以在项目中引用 Markdig 命名空间，开始使用它提供的功能。
2. 基本用法
Markdig 提供了一个简单的接口，用于将 Markdown 文本转换为 HTML。最基础的用法是通过 Markdown.ToHtml() 方法来进行转换：
using Markdig;
string markdown = "# Hello, World!\nThis is a Markdown text!";
string html = Markdown.ToHtml(markdown);
Console.WriteLine(html);
输出：
<h1>Hello, World!</h1>
<p>This is a Markdown text!</p>
这段代码展示了如何将一个简单的 Markdown 字符串转化为 HTML。在这个例子中，Markdig 自动将 # Hello, World! 渲染为 <h1> 标签，将普通文本 This is a Markdown text! 渲染为 <p> 标签。
3. 管道与扩展
Markdig 的强大之处在于它的扩展性。你可以使用 MarkdownPipelineBuilder 创建一个管道，并且可以通过这个管道启用或禁用不同的 Markdown 扩展。管道是 Markdown 解析过程中的核心部分，负责配置 Markdown 渲染的各个步骤。
3.1 创建管道
管道是 Markdig 解析过程的核心，通常通过 MarkdownPipelineBuilder 来构建。通过管道，你可以启用一些常见的 Markdown 扩展，像表格、任务列表、脚注等。
using Markdig;
var pipeline = new MarkdownPipelineBuilder()
.UseAdvancedExtensions() // 启用一些常用的扩展
.Build();
在上面的例子中，UseAdvancedExtensions() 会启用 Markdig 提供的常见扩展，使得解析器能够支持表格、脚注、任务列表等功能。
3.2 启用扩展
Markdig 提供了许多常见的扩展功能，以下是一些常用的扩展：
3.2.1 表格扩展
Markdig 支持 Markdown 表格语法，但默认情况下没有启用表格支持。如果你希望支持表格，可以启用 UsePipeTables() 扩展。
using Markdig;
var pipeline = new MarkdownPipelineBuilder()
.UsePipeTables() // 启用表格扩展
.Build();
string markdown = "| Header 1 | Header 2 |\n| --- | --- |\n| Row 1 Col 1 | Row 1 Col 2 |";
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
输出：
<table>
<thead>
<tr><th>Header 1</th><th>Header 2</th></tr>
</thead>
<tbody>
<tr><td>Row 1 Col 1</td><td>Row 1 Col 2</td></tr>
</tbody>
</table>
3.2.2 脚注（Footnotes）
Markdig 还支持 Markdown 脚注语法，你可以通过启用 UseFootnotes() 扩展来实现。
using Markdig;
var pipeline = new MarkdownPipelineBuilder()
.UseFootnotes() // 启用脚注扩展
.Build();
string markdown = "This is a text with a footnote[^1].\n\n[^1]: This is the footnote text.";
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
输出：
<p>This is a text with a footnote<a href=\"#fn1\" id=\"fnref1\">¹</a>.</p>
<div class="footnotes">
<hr>
<ol>
<li id="fn1">
<p>This is the footnote text. <a href="#fnref1" rev="footnote" title="Jump back to reference">↩︎</a></p>
</li>
</ol>
</div>
3.2.3 自动链接（Auto Links）
Markdig 还提供了 UseAutoLinks() 扩展，可以自动将文本中的 URL 转换为 <a> 标签。
using Markdig;
var pipeline = new MarkdownPipelineBuilder()
.UseAutoLinks() // 启用自动链接扩展
.Build();
string markdown = "This is a link to [Google](https://www.google.com) and http://example.com";
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
输出：
<p>This is a link to <a href="https://www.google.com">Google</a> and <a href="http://example.com">http://example.com</a></p>
3.2.4 任务列表（Task Lists）
Markdig 还可以渲染 Markdown 的任务列表（[ ] 和 [x] 语法）。
using Markdig;
var pipeline = new MarkdownPipelineBuilder()
.UseTaskLists() // 启用任务列表扩展
.Build();
string markdown = "- [x] Task 1\n- [ ] Task 2";
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
输出：
<ul>
<li><input type="checkbox" checked disabled> Task 1</li>
<li><input type="checkbox" disabled> Task 2</li>
</ul>
4. 自定义渲染
Markdig 允许你自定义 Markdown 渲染过程。例如，你可以自定义如何渲染特定类型的 Markdown 元素，如标题、段落或代码块。
自定义标题渲染
假设你希望将所有的 h1 标签渲染为红色字体，可以通过实现 IObjectRenderer 来完成这一需求：
using Markdig;
using Markdig.Renderers;
using Markdig.Syntax;
public class CustomHeadingRenderer : IObjectRenderer
{
public void Render(HtmlRenderer renderer, MarkdownObject obj)
{
if (obj is HeadingBlock heading)
{
// 自定义 h1 的渲染方式
renderer.Write("<h" + heading.Level + " style='color: red;'>")
.Write(heading.Inline)
.Write("</h" + heading.Level + ">");
}
else
{
// 默认渲染
renderer.Render(obj);
}
}
}
var pipeline = new MarkdownPipelineBuilder().Build();
var renderer = new HtmlRenderer();
renderer.ObjectRenderers.Add(new CustomHeadingRenderer());
string markdown = "# Custom Heading\nThis is a custom heading example!";
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
输出：
<h1 style="color: red;">Custom Heading</h1>
<p>This is a custom heading example!</p>
5. 自定义扩展
除了使用 Markdig 内置的扩展，开发者还可以根据需求编写自己的扩展。例如，如果你想支持某种自定义的 Markdown 语法（例如 [[...]]），你可以创建一个扩展来处理这种语法。
using Markdig;
using Markdig.Parsers;
using Markdig.Syntax;
using Markdig.Extensions;
public class CustomParser : InlineParser
{
public CustomParser()
{
this.OpenDelimiter = '[';
this.CloseDelimiter = ']';
}
public override bool TryParse(InlineProcessor processor)
{
var node = new LiteralInline("Custom Syntax");
processor.Inline = node;
return true;
}
}
public class CustomExtension : IMarkdownExtension
{
public void Setup(MarkdownPipeline
Builder pipeline) { pipeline.Extensions.Add(new CustomParser()); }
public void Setup(MarkdownPipeline pipeline) { }
}
// 使用自定义扩展 var pipeline = new MarkdownPipelineBuilder() .Use() .Build();
string markdown = "[[Custom Syntax]]"; string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
## 6. 语法高亮
Markdig 还支持代码块的语法高亮。你可以通过 `UseSyntaxHighlighting()` 扩展启用代码高亮功能。
```csharp
using Markdig;
using Markdig.Extensions.SyntaxHighlighting;
var pipeline = new MarkdownPipelineBuilder()
.UseSyntaxHighlighting() // 启用语法高亮
.Build();
string markdown = "```csharp\nConsole.WriteLine(\"Hello World\");\n```";
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);
总结
Markdig 是一个功能强大且灵活的 Markdown 解析器，它不仅支持常见的 Markdown 语法，还提供了丰富的扩展功能。通过 Markdig，你可以轻松地将 Markdown 文本转换为 HTML，并且可以根据自己的需求启用或自定义扩展，实现更丰富的功能。
无论是基本的 Markdown 转换，还是定制化的渲染需求，Markdig 都能为你提供强大且易于使用的解决方案。
