intellij-markdown

一个用Kotlin编写的多平台Markdown处理器。

简介

intellij-markdown是一个用Kotlin编写的可扩展Markdown处理器。它旨在满足以下需求：

使用同一代码库进行客户端和服务器端处理
在不同平台上产生一致的输出
支持不同的Markdown风格
易于扩展

该处理器完全使用Kotlin编写（加上一点flex），因此不仅可以编译为JVM目标，还可以编译为JS和Native。这使得处理器可以在任何地方使用。

使用方法

将`intellij-markdown`添加为依赖项

该库托管在Maven中央仓库中，要使用它，你需要配置中央仓库：

repositories {
  mavenCentral()
}

如果你使用的Gradle版本 >= 5.4，你可以直接添加主要工件作为依赖项：

dependencies {
  implementation("org.jetbrains:markdown:<version>")
}

Gradle应该会解析你的目标平台并决定下载哪个工件（JVM或JS）。

对于多平台项目，你可以将单个依赖项添加到commonMain类路径：

commonMain {
  dependencies {
    implementation("org.jetbrains:markdown:<version>")
  }
}

如果你使用Maven或旧版Gradle，你需要为你的平台指定正确的工件，例如：

org.jetbrains:markdown-jvm:<version>用于JVM版本
org.jetbrains:markdown-js:<version>用于JS版本

使用`intellij-markdown`进行解析和生成HTML

该项目的目标之一是提供灵活性以解决不同的任务。 JetBrains IDEs的Markdown插件是一个使用示例，其中Markdown处理分为几个阶段：

解析块结构而不解析内联元素，为IDE提供可延迟解析的块
快速解析给定块的内联元素，以提供更快的语法高亮更新
生成HTML以预览

这些任务可以根据当前需求独立完成。

简单的HTML生成（Kotlin）

val src = "Some *Markdown*"
val flavour = CommonMarkFlavourDescriptor()
val parsedTree = MarkdownParser(flavour).buildMarkdownTreeFromString(src)
val html = HtmlGenerator(src, parsedTree, flavour).generateHtml()

简单的HTML生成（Java）

final String src = "Some *Markdown*";
final MarkdownFlavourDescriptor flavour = new GFMFlavourDescriptor();
final ASTNode parsedTree = new MarkdownParser(flavour).buildMarkdownTreeFromString(text);
final String html = new HtmlGenerator(src, parsedTree, flavour, false).generateHtml();

开发注意事项

唯一的非Kotlin文件是.flex词法分析器定义。它们用于生成词法分析器，这是内联元素解析的第一阶段。不幸的是，由于bug，原生的java->kt转换对这些文件会崩溃。因此，从.flex到相应Kotlin文件的转换需要一些手动步骤：

安装Grammar Kit插件。打开任何.flex文件时应该会提示安装。
安装jflexToKotlin插件（你需要自己构建并手动安装，通过设置）。
打开.flex文件时运行Run JFlex Generator操作。
- 首次运行时，会打开一个对话框，建议下载JFlex的位置 - 选择项目根目录，然后删除多余下载的.skeleton文件。
会在某处生成相应的_<SomeName>Lexer.java。将其移到现有的_<SomeName>Lexer.kt附近。
删除.kt词法分析器。
打开新的.java文件时运行Convert JFlex Lexer to Kotlin操作。
修复生成的.kt文件中的小问题，如导入。不应该有重大问题。请尽量减少对生成文件的更改。这是为了保持干净的Git历史。

解析算法

解析过程分为两个逻辑部分：

将文档分割成逻辑结构块（列表、引用块、段落等）
解析结果块的内联结构

这与Commonmark规范提出的方法相同。

构建逻辑结构

每个（未来的）节点（列表、列表项、引用块等）都与所谓的_MarkerBlock_相关联。无回溯的解析算法逐个处理文件中的每个标记。标记被传递给打开的标记块，每个块选择是：

不做任何操作
放弃自己
完成自己

_MarkerProcessor_存储这些块，执行块选择的操作，并可能添加一些新的块。

解析内联元素

为了提高速度和解析便利性，文本首先传递给MarkdownLexer。然后以特殊方式处理结果标记集。

Markdown中的一些内联结构具有优先级，即如果两个不同的结构重叠，解析结果取决于它们的类型，而不是它们的位置 - 例如 *code, `not* emph` 和 `code, *not` emph* 都是代码段 + 字面星号。这意味着正常的递归解析是不适用的。

尽管如此，内联元素的解析还是相当直接。对于每个内联结构，都有一个特定的_SequentialParser_，它接受一些输入文本并返回：

在此文本中找到的已解析范围；
要传递给后续内联解析器的子文本。

构建AST

在构建逻辑结构和解析内联元素之后，会得到一组对应于某些markdown实体（即节点）的范围。为了有效地处理结果，应将其转换为AST。

最终，返回一个对应于解析后的Markdown文档的根ASTNode。每个AST节点都有自己的类型，称为IElementType，与IntelliJ平台中的一样。

生成HTML

对于给定的AST根，创建一个特殊的访问者来生成结果HTML。使用从IElementType到GeneratingProvider的给定映射，它以深度优先顺序处理解析树，在每个节点访问时生成HTML片段。

扩展解析器

通过创建不同的Markdown风格，可以扩展或重新定义上述过程中的许多例程。最小的默认风格是CommonMark，在本项目中实现。

GitHub Flavoured Markdown是扩展CommonMark风格实现的一个例子。它可以作为实现自己的Markdown特性的参考。

API

MarkdownFlavourDescriptor是用于扩展Markdown解析器的基类。
- markerProcessorFactory负责块结构的自定义。
  - stateInfo值允许在文档解析过程中使用状态。
    
    updateStateInfo(pos: LookaheadText.Position)在每个位置处理开始时调用
  - populateConstraintsTokens在行首创建块结构标记的节点时调用（例如，构成引用块的>字符）
  - getMarkerBlockProviders是（重新）定义块结构类型的地方
- sequentialParserManager
  
  getParserSequence定义内联解析过程。该方法必须返回SequentialParsers列表，其中最早的解析器具有最大的操作优先级。例如，要以正确的优先级解析代码段和强调元素，列表应为[CodeSpanParser, EmphParser]而不是相反。
  
  SequentialParser只有一个方法：
  
  parse(tokens: TokensCache, rangesToGlue: List<IntRange>): ParsingResult
  - tokens是词法分析器返回的标记的特殊持有者
  - rangesToGlue是文档中要搜索相关结构的范围列表。
    
    考虑输入：A * emph `code * span` b * c ，对于强调解析器，范围 [A * emph , b * c]意味着必须在输入A * emph | b * c中搜索强调。
    
    该方法本质上必须返回解析结果（找到的结构的节点）和要给下一个解析器的文本部分。
    
    考虑同样的输入，对于代码段解析器，结果将是`code * span` 类型为"代码段"，委托片段将是[A * emph , b * c]。
- createInlinesLexer应返回词法分析器，在内联解析过程运行之前将文本分割为标记。
- createHtmlGeneratingProviders(linkMap: LinkMap, baseURI: URI?) 是自定义生成HTML的地方。此方法应返回一个映射，定义如何处理结果树中特定类型的节点。
  
  这里的linkMap是通过链接定义计算出的文档中定义的链接的预计算信息。baseURI是要考虑作为相对链接解析的基本路径的URI。例如，给定baseUri='/user/repo-name/blob/master'，链接foo/bar.png应转换为 /user/repo-name/blob/master/foo/bar.png。
  
  每个返回的提供者必须实现processNode(visitor: HtmlGenerator.HtmlGeneratingVisitor, text: String, node: ASTNode) 其中
  - text是正在处理的整个文档，
  - node是给予提供者的节点，
  - visitor是负责HTML生成的特殊对象。有关示例，请参见GeneratingProviders.kt。