Lute 一款对中文语境优化的 Markdown 引擎,支持 Go 和 JavaScript

本贴最后更新于 648 天前,其中的信息可能已经时移世异

Lute

一款对中文语境优化的 Markdown 引擎,支持 Go 和 JavaScript

千呼万唤始出来 犹抱琵琶半遮面
转轴拨弦三两声 未成曲调先有情





        

English

💡 简介

Lute 是一款结构化的 Markdown 引擎,完整实现了最新的 GFM/CommonMark 规范,对中文语境支持更好。

欢迎到 Lute 官方讨论区了解更多。同时也欢迎关注 B3log 开源社区微信公众号 B3log开源

b3logos.png

📽️ 背景

之前我一直在使用其他 Markdown 引擎,它们或多或少都有些“瑕疵”:

Lute 的目标是构建一个结构化的 Markdown 引擎,实现 GFM/CM 规范并对中文提供更好的支持。所谓的“结构化”指的是从输入的 MD 文本构建抽象语法树,通过操作树来进行 HTML 输出、原文格式化等。
实现规范是为了保证 Markdown 渲染不存在二义性,让同一份 Markdown 文本可以在实现规范的 Markdown 引擎处理后得到一样的结果,这一点非常重要。

实现规范的引擎并不多,我想试试看自己能不能写上一个,这也是 Lute 的动机之一。关于如何实现一个 Markdown 引擎,网上众说纷纭:

我赞同后者,因为正则确实太难维护而且运行效率较低。最重要的原因是符合 GFM/CM 规范的 Markdown 引擎的核心解析算法不可能用正则写出来,因为规范定义的规则实在是太复杂了。

最后,还有一个很重要的动机就是 B3log 开源社区需要一款自己的 Markdown 引擎:

✨ 特性

🗃 案例

🇨🇳 中文语境优化

♍ 格式化

格式化功能可将“不整洁”的 Markdown 文本格式化为统一风格,在需要公共编辑的场景下,统一的排版风格能让大家更容易协作。

点此展开格式化示例。
Markdown 原文:
# ATX 标题也有可能需要格式化的 ##
一个简短的段落。

Setext 说实话我不喜欢 Setext 标题
----
0. 有序列表可以从 0 开始
0. 应该自增序号的
1.   对齐对齐对齐

我们再来看看另一个有序列表。
1. 没空行的情况下序号要从 1 开始才能打断段落开始一个新列表
3. 虽然乱序不影响渲染
2. 但是随意写序号容易引起误解

试下贴段代码:
```go
package main

import "fmt"

func main() {
  fmt.Println("Hello, 世界")
}
```
对了,缩进代码块建议换成围栏代码块:

    缩进代码块太隐晦了
    也没法指定编程语言,容易导致代码高亮失效
    所以建议大家用 ``` 围栏代码块
试下围栏代码块匹配场景:
````markdown
围栏代码块只要开头的 ` 和结束的 ` 数量匹配即可,这样可以实现在围栏代码块中显示围栏代码块:
```
这里只有 3 个 `,所以不会匹配markdown代码块结束
```
下面匹配到就真的结束了。
````
以上块级内容都挤在一坨了,插入合理的空行也很有必要。


但是过多的空行分段也不好啊,用来分段的话一个空行就够了。



接下来让我们试试稍微复杂点的场景,比如列表项包含多个段落的情况:
1. 列表项中的第一段

   这里是第二个段落,贴段代码:
   ```markdown
   要成为Markdown程序员并不容易,同理PPT架构师也是。
   注意代码块中的中西文间并没有插入空格。
   ```
   这里是最后一段了。
1. 整个有序列表是“松散”的:列表项内容要用 `<p>` 标签

最后,我们试下对 GFM 的格式化支持:

|col1|col2  |       col3   |
---           |---------------|--
col1 without left pipe      |   this is col2   | col3 without right pipe
                                 ||need align cell|

**以上就是为什么我们需要Markdown Format,而且是带中西文自动空格的格式化。**

格式化后:

# ATX 标题也有可能需要格式化的

一个简短的段落。

## Setext 说实话我不喜欢 Setext 标题

0. 有序列表可以从 0 开始
1. 应该自增序号的
2. 对齐对齐对齐

我们再来看看另一个有序列表。

1. 没空行的情况下序号要从 1 开始才能打断段落开始一个新列表
2. 虽然乱序不影响渲染
3. 但是随意写序号容易引起误解

试下贴段代码:

```go
package main

import "fmt"

func main() {
  fmt.Println("Hello, 世界")
}
```

对了,缩进代码块建议换成围栏代码块:

```
缩进代码块太隐晦了
也没法指定编程语言,容易导致代码高亮失效
所以建议大家用 ``` 围栏代码块
```

试下围栏代码块匹配场景:

````markdown
围栏代码块只要开头的 ` 和结束的 ` 数量匹配即可,这样可以实现在围栏代码块中显示围栏代码块:
```
这里只有 3 个 `,所以不会匹配markdown代码块结束
```
下面匹配到就真的结束了。
````

以上块级内容都挤在一坨了,插入合理的空行也很有必要。

但是过多的空行分段也不好啊,用来分段的话一个空行就够了。

接下来让我们试试稍微复杂点的场景,比如列表项包含多个段落的情况:

1. 列表项中的第一段

   这里是第二个段落,贴段代码:

   ```markdown
   要成为Markdown程序员并不容易,同理PPT架构师也是。
   注意代码块中的中西文间并没有插入空格。
   ```

   这里是最后一段了。
2. 整个有序列表是“松散”的:列表项内容要用 `<p>` 标签

最后,我们试下对 GFM 的格式化支持:

| col1                   | col2            | col3                    |
| ---------------------- | --------------- | ----------------------- |
| col1 without left pipe | this is col2    | col3 without right pipe |
|                        | need align cell |                         |

**以上就是为什么我们需要 Markdown Format,而且是带中西文自动空格的格式化。**

✍️ 术语修正

Markdown 原文:

在github上做开源项目是一件很开心的事情,请不要把Github拼写成`github`哦!

特别是简历中千万不要出现这样的情况:

> 熟练使用JAVA、Javascript、GIT,对android、ios开发有一定了解,熟练使用Mysql、postgresql数据库。

修正后:

在 GitHub 上做开源项目是一件很开心的事情,请不要把 GitHub 拼写成`github`哦!

特别是简历中千万不要出现这样的情况:

> 熟练使用 Java、JavaScript、Git,对 Android、iOS 开发有一定了解,熟练使用 MySQL、PostgreSQL 数据库。

⚡ 性能

请看 Golang markdown 引擎性能基准测试

💪 健壮性

Lute 承载了黑客派上的所有 Markdown 处理,每天处理数百万解析渲染请求,运行表现稳定。

🔒 安全性

Lute 没有实现实现 GFM 中的 Disallowed Raw HTML (extension),因为该扩展还是存在一定漏洞(比如没有处理 <input> )。
建议通过其他库(比如 bluemonday)来进行 HTML 安全过滤,这样也能更好地适配应用场景。

🛠️ 使用

有三种方式使用 Lute:

  1. 后端:用 Go 语言的话引入 github.com/88250/lute
  2. 后端:将 Lute 启动为一个 HTTP 服务进程供其他进程调用,具体请参考这里
  3. 前端:引入 js 目录下的 lute.min.js,支持 Node.js

Go

引入 Lute 库:

go get -u github.com/88250/lute

最小化可工作示例:

package main

import (
	"fmt"

	"github.com/88250/lute"
)

func main() {
	luteEngine := lute.New() // 默认已经启用 GFM 支持以及中文语境优化
	html := luteEngine.MarkdownStr("demo", "**Lute** - A structured markdown engine.")
	fmt.Println(html)
	// <p><strong>Lute</strong> - A structured Markdown engine.</p>
}

关于代码块语法高亮:

JavaScript

简单示例可参考 JavaScript 目录下的 demo,结合前端编辑器的完整用法请参考 Vditor 中的示例

Vditor

一些细节:

  1. lute.js 没有内置语法高亮特性
  2. lute.js 编译后大小为 ~2MB,通过 brotli -o lute.min.js.br lute.min.js 压缩后大小 ~200KB,常规 GZip 压缩后大小 ~300KB

📜 文档

🏘️ 社区

📄 授权

Lute 使用 木兰宽松许可证, 第 2 版 开源协议。

🙏 鸣谢

Lute 的诞生离不开以下开源项目,在此对这些项目的贡献者们致敬!

优质回帖
  • csfwff 2
    捐赠者

    作为第 ④ 个 star 表示 666

  • InkDP 1
    捐赠者

    作为第一个点 star 的表示牛逼

  • someone9891 1
    捐赠者

    作为第二个 start 表示很荣幸

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • CheGuevara
    支持者

    大 D,有问题请教一下。我正在帮公司调研内部使用的 md 编辑器,在 Lute 和 Markdown-it 之间纠结。

    我看到 Vditor 之前是用的 Markdown-it,所以文中提到的这些缺点是指 Markdown-it 吗?

    之前我一直在使用其他 Markdown 引擎,它们或多或少都有些“瑕疵”:

    • 对标准规范的支持不一致
    • 对“怪异”文本处理非常耗时,甚至挂死
    • 对中文支持不够好

    我个人是倾向 Lute 的,但是得加上一个对比方案,所以来你这里问问 😭

    @88250

    1 回复
  • 其他回帖
  • clipw

    好的,刚试了一下,直接用 https://github.com/b3log/markdown-http 也方便。有个报错

    [ERROR]-[2019-08-29 23:19:32]-[org.b3log.latke.servlet.renderer.AbstractFreeMarkerRenderer:131]: Renders template [tag-articles.ftl] failed [Request [
        method=GET,
        URL=http://www.test.com:443/tag/java/reply,
        contentType=null,
        characterEncoding=UTF-8,
        local=[
            addr=127.0.0.1,
            port=8080,
            name=127.0.0.1],
    
    
    FreeMarker template error:
    The following has evaluated to null or missing:
    ==> article.articleTagObjs  [in template "classic/common/list-item.ftl" at line 22, column 16]
    The following has evaluated to null or missing:
    ==> article.articleTagObjs  [in template "classic/common/list-item.ftl" at line 22, column 16]
    
    ----
    Tip: It's the step after the last dot that caused this error, not those before it.
    ----
    Tip: If the failing expression is known to legally refer to something that's sometimes null or missing, either specify a default value like myOptionalVar!myDefault, or use <#if myOptionalVar??>when-present<#else>when-missing</#if>. (These only cover the last step of the expression; to cover the whole expression, use parenthesis: (myOptionalVar.foo)!myDefault, (myOptionalVar.foo)??
    ----
    
    ----
    FTL stack trace ("~" means nesting-related):
    	- Failed at: #list article.articleTagObjs as artic...  [in template "classic/common/list-item.ftl" at line 22, column 9]
    	- Reached through: #include "common/list-item.ftl"  [in template "classic/macro-list.ftl" in macro "list" at line 28, column 9]
    	- Reached through: @list listData=articles  [in template "classic/tag-articles.ftl" at line 107, column 25]
    ----
    
    该回帖因偏离主题而被折叠
    3 操作
    csfwff 在 2019-08-30 09:05:22 折叠了该回帖
    csfwff 在 2019-08-30 09:05:02 取消折叠了该回帖
    88250 在 2019-08-29 23:59:50 折叠了该回帖
  • jeffjade

    话说,这些比较好的特性,如:

    • 自动链接识别加强
    • 在中西文间自动插入空格
    • 术语拼写修正

    会考虑也在 Vditor 中注入下么?

    1 回复
  • cuijianzhe
    捐赠者

    从原来视频解析

    <center><video width="100%" height="100%" controls>
    <source src="https://cjz.cjzshilong.cn/sunbayi.mp4" 
     type="video/mp4">
    </video><center>
    

    变为:https://cjz.cjzshilong.cn/sunbayi.mp4

  • 查看全部回帖