Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/88250/lute

🎼 一款结构化的 Markdown 引擎，支持 Go 和 JavaScript。A structured Markdown engine that supports Go and JavaScript.
https://github.com/88250/lute

gopherjs markdown protyle siyuan vditor

Last synced: about 11 hours ago
JSON representation

🎼 一款结构化的 Markdown 引擎，支持 Go 和 JavaScript。A structured Markdown engine that supports Go and JavaScript.

Host: GitHub
URL: https://github.com/88250/lute
Owner: 88250
License: other
Created: 2019-12-01T12:50:28.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2024-12-04T16:16:50.000Z (8 days ago)
Last Synced: 2024-12-04T17:26:01.172Z (8 days ago)
Topics: gopherjs, markdown, protyle, siyuan, vditor
Language: Go
Homepage: https://ld246.com/tag/lute
Size: 119 MB
Stars: 1,252
Watchers: 9
Forks: 134
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome - 88250/lute - 🎼 一款结构化的 Markdown 引擎，支持 Go 和 JavaScript。A structured Markdown engine that supports Go and JavaScript. (Go)
awesome-starts - 88250/lute - 🎼 一款对中文语境优化的 Markdown 引擎，支持 Go 和 JavaScript。A structured Markdown engine that supports Go and JavaScript. (Go)
go-awesome - Lute - Structured markdown engine (Open source library / Word Processing)
awesome-seeds - lute
my-awesome - 88250/lute - 12 star:1.3k fork:0.1k 🎼 一款结构化的 Markdown 引擎，支持 Go 和 JavaScript。A structured Markdown engine that supports Go and JavaScript. (Go)

README

        








一款结构化的 Markdown 引擎，支持 Go 和 JavaScript





千呼万唤始出来 犹抱琵琶半遮面


转轴拨弦三两声 未成曲调先有情
































  

  

  







English



## 💡 简介

[Lute](https://github.com/88250/lute) 是一款结构化的 Markdown 引擎，完整实现了最新的 [GFM](https://github.github.com/gfm/)/[CommonMark](https://commonmark.org) 规范，对中文语境支持更好。

欢迎到 [Lute 官方讨论区](https://ld246.com/tag/lute)了解更多。同时也欢迎关注 B3log 开源社区微信公众号 `B3log开源`：

![b3logos.jpg](https://b3logfile.com/file/2020/08/b3logos-032af045.jpg)

## 📽️ 背景

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

* 对标准规范的支持不一致

* 对“怪异”文本处理非常耗时，甚至挂死

* 对中文支持不够好

Lute 的目标是构建一个结构化的 Markdown 引擎，实现 GFM/CM 规范并对中文提供更好的支持。所谓的“结构化”指的是从输入的 MD 文本构建抽象语法树，通过操作树来进行 HTML 输出、原文格式化等。

实现规范是为了保证 Markdown 渲染不存在二义性，让同一份 Markdown 文本可以在实现规范的 Markdown 引擎处理后得到一样的结果，这一点非常重要。

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

* 有的人说 Markdown 适合用正则解析，因为文法规则太简单

* 也有的人说 Markdown 可以用编译原理来处理，正则太难维护

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

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

* [Solo](https://github.com/88250/solo)、[Pipe](https://github.com/88250/pipe)、[Sym](https://github.com/88250/symphony) 需要效果统一的 Markdown 渲染，并且性能非常重要

* [Vditor](https://github.com/Vanessa219/vditor) 需要一款结构化的引擎作为支撑以实现下一代的 Markdown 编辑器

## ✨  特性

* 实现最新版 GFM/CM 规范

* 零正则，非常快

* 内置代码块语法高亮

* 对中文语境支持更好

* 术语拼写修正

* Markdown 格式化

* Emoji 解析

* HTML 转换 Markdown

* 自定义渲染函数

* 支持 JavaScript 端使用

## 🗃 案例

* [链滴](https://ld246.com)

* [思源笔记](https://github.com/siyuan-note/siyuan)

* [Vditor 编辑器](https://github.com/Vanessa219/vditor)

* [Sym 社区系统](https://github.com/88250/symphony)

* [Solo 博客系统](https://github.com/88250/solo)

* [Pipe 博客系统](https://github.com/88250/pipe)

## 🇨🇳 中文语境优化

* 自动链接识别加强

* 在中西文间自动插入空格

## ♍ 格式化

格式化功能可将“不整洁”的 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. 整个有序列表是“松散”的：列表项内容要用 `
` 标签

最后，我们试下对 GFM 的格式化支持：

|col1|col2  |       col3   |

---           |---------------|--

col1 without left pipe      |   this is col2   | col3 without right pipe

                                 ||need align cell|

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

````````

格式化后：

````````markdown

# 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. 整个有序列表是“松散”的：列表项内容要用 `
` 标签

最后，我们试下对 GFM 的格式化支持：

| col1                   | col2            | col3                    |

| ---------------------- | --------------- | ----------------------- |

| col1 without left pipe | this is col2    | col3 without right pipe |

|                        | need align cell |                         |

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

````````



## ✍️ 术语修正

Markdown 原文：

```markdown

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

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

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

```

修正后：

```markdown

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

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

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

```

## ⚡ 性能

请看 [Golang markdown 引擎性能基准测试](https://ld246.com/article/1574570835061)。

## 💪 健壮性

Lute 承载了[链滴](https://ld246.com)上的所有 Markdown 处理，每天处理数百万解析渲染请求，运行表现稳定。

## 🔒 安全性

Lute 没有实现实现 GFM 中的 [Disallowed Raw HTML (extension)](https://github.github.com/gfm/#disallowed-raw-html-extension-)，因为该扩展还是存在一定漏洞（比如没有处理 `` ）。

建议通过其他库（比如 [bluemonday](https://github.com/microcosm-cc/bluemonday)）来进行 HTML 安全过滤，这样也能更好地适配应用场景。

## 🛠️ 使用

有三种方式使用 Lute：

1. 后端：用 Go 语言的话引入 `github.com/88250/lute` 包

2. 后端：将 Lute 启动为一个 HTTP 服务进程供其他进程调用，具体请参考[这里](https://github.com/88250/lute-http)

3. 前端：引入 js 目录下的 lute.min.js，支持 Node.js

### Go

引入 Lute 库：

```shell

go get -u github.com/88250/lute

```

最小化可工作示例：

```go

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)

	// 
Lute - A structured Markdown engine.

}

```

关于代码块语法高亮：

* 默认使用外部样式表，主题为 github.css，可从 chroma-styles 目录下拷贝该样式文件到项目中引入

* 可通过 `lutenEngine.SetCodeSyntaxHighlightXXX()` 来指定高亮相关参数，比如是否启用内联样式、行号以及主题

### JavaScript

简单示例可参考 JavaScript 目录下的 demo，结合前端编辑器的完整用法请参考 [Vditor 中的示例](https://github.com/Vanessa219/vditor/tree/master/demo)。

![Vditor](https://b3logfile.com/file/2020/02/%E6%88%AA%E5%9B%BE%E4%B8%93%E7%94%A8-ef21ef12.png)

一些细节：

1. lute.js 没有内置语法高亮特性

2. lute.js 编译后大小为 ~3.5MB，GZip 压缩后大小 ~500KB

## 📜 文档

* [《提问的智慧》精读注解版](https://ld246.com/article/1536377163156)

* [CommonMark 规范要点解读](https://ld246.com/article/1566893557720)

* [Lute 实现后记](https://ld246.com/article/1567062979327)

* [Markdown 解析原理详解和 Markdown AST 描述](https://ld246.com/article/1587637426085)

## 🏘️ 社区

* [讨论区](https://ld246.com/tag/lute)

* [报告问题](https://github.com/88250/lute/issues/new/choose)

## 📄 授权

Lute 使用 [木兰宽松许可证, 第2版](http://license.coscl.org.cn/MulanPSL2) 开源协议。

## 🙏 鸣谢

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

* [commonmark.js](https://github.com/commonmark/commonmark.js)：该项目是 CommonMark 官方参考实现的 JavaScript 版，Lute 参考了其解析器实现部分

* [goldmark](https://github.com/yuin/goldmark)：另一款用 golang 写的 Markdown 引擎，Lute 参考了其树遍历实现部分

* [golang-commonmark](https://gitlab.com/golang-commonmark/markdown)：另一款用 golang 写的 Markdown 引擎，Lute 参考了其 URL 编码以及 HTML 转义算法

* [Chroma](https://github.com/alecthomas/chroma)：用 golang 写的语法高亮引擎

* [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)：统一中文文案、排版的相关用法，降低团队成员之间的沟通成本，增强网站气质

* [GopherJS](https://github.com/gopherjs/gopherjs)：将 Go 代码编译成 JavaScript 代码