企业官网建设流程全解析

• 前端
• UI组件
• 富文本

mavonEditor 是一款基于 Vue 的 Markdown 编辑器。本文以仓库内置的法语帮助文档 src/dev/assets/lang/fr/help_fr.md（生产包对应 src/lib/lang/fr/help_fr.md）为纲，完整梳理该编辑器内置 Markdown 渲染引擎支持的语法全集，并结合 src/lib/core/markdown.js 的 markdown-it 插件装配源码，讲清每种语法的实现原理、写法与呈现效果。读完本文，你将掌握 mavonEditor 从基础排版到 KaTeX 数学公式、任务列表、定义列表等进阶语法的完整用法，并能理解"帮助面板"在编辑器内部的加载与渲染机制。

一、帮助文档在 mavonEditor 中的定位与加载机制

1.1 帮助文档是一份"可点开的内置语法速查表"

mavonEditor 的工具栏右侧提供"帮助（Guide Markdown）"按钮，点击后会在编辑器上方弹出一个悬浮面板，面板内容就是各语言版本的 Markdown 语法速查文档。该按钮在 src/components/md-toolbar-right.vue 中定义：

<button type="button" v-if="toolbars.help" @click="$clicks('help')" class="op-icon fa fa-mavon-question-circle" :title="d_words.tl_help" aria-hidden="true"></button>

toolbars.help默认开启（见 src/lib/config.js），法语环境下的按钮悬浮提示文案来自语言包 src/lib/lang/fr/words_fr.json 中的"tl_help": "Guide Markdown"。

1.2 帮助文档的加载与渲染链路

点击帮助按钮后，src/lib/toolbar_right_click.js 会切换s_help状态并触发helptoggle回调：

function $toolbar_right_help_click($vm) { $vm.s_help = !$vm.s_help if ($vm.helptoggle) { $vm.helptoggle($vm.s_help, $vm.d_value) } }

帮助面板的挂载点在 src/mavon-editor.vue，面板内容由d_help渲染：

<div @click.self="toolbar_right_click('help')" class="v-note-help-wrapper" v-if="s_help"> <div class="v-note-help-content markdown-body" :class="{'shadow': boxShadow}"> <i @click.stop.prevent="toolbar_right_click('help')" class="fa fa-mavon-times" aria-hidden="true"></i> <div class="scroll-style v-note-help-show" v-html="d_help"></div> </div> </div>

d_help的来源在initLanguage()中（src/mavon-editor.vue）：根据当前language从 src/lib/config.js 导入的help_${lang}模块中取出对应语言文档，交给 markdown-it 渲染成 HTML：

initLanguage() { let lang = CONFIG.langList.indexOf(this.language) >= 0 ? this.language : 'zh-CN'; var $vm = this; $vm.$render(CONFIG[`help_${lang}`], function(res) { $vm.d_help = res; }) this.d_words = CONFIG[`words_${lang}`]; }

其中法语文档在 src/dev/assets/config.js 中被导入：

import help_fr from './lang/fr/help_fr.md'

开发环境（src/dev/assets）与发布环境（src/lib）各维护一份相同内容的语言资源，法语是langList: ['en', 'zh-CN', 'zh-TW', 'fr', 'pt-BR', 'ru', 'de', 'ja']（src/lib/config.js）中正式支持的语言之一。

下图展示了点击帮助按钮后弹出的语法速查面板形态（中文界面示例，帮助面板结构一致）：帮助面板以浮层形式展示在编辑区上方，内部分章节列出各语法及其示例，支持滚动浏览与关闭。

二、基础排版语法：粗体、斜体、标题、分割线

帮助文档的第一部分集中讲解最常用的排版语法，全部由 markdown-it 核心解析器支持。

2.1 粗体（Gras）

两种写法等价，用双星号或双下划线包裹：

**bold** __bold__

2.2 斜体（Italique）

单星号或单下划线包裹：

*italic* _italic_

2.3 标题（Entête）

支持 Setext（=/-下划线式）与 ATX（#井号式）两种标题写法，从 h1 到 h6 六级齐全：

# h1 # h1 ==== ## h2 ## h2 ---- ### h3 ### #### h4 #### ##### h5 ##### ###### h6 ######

工具栏中的"标题"按钮插入的正是#前缀（见 src/lib/toolbar_left_click.js），与帮助文档中的语法一一对应。标题也是编辑器"导航（Navigation）"功能的锚点来源——开启导航后，getNavigation()会根据渲染结果中的标题层级生成目录（见 src/mavon-editor.vue）。

2.4 分割线（Dividing line）

*** ---

三条星号或三条横线均可生成水平分隔线。

三、行内修饰语法：上下标、下划线、删除线、标记

这一组语法在标准 CommonMark 之外，是 mavonEditor 通过 markdown-it 插件扩展的能力，也是帮助文档重点强调的"个性化特性"。

3.1 上标与下标（Super/sub script）

super x^2^ sub H~2~0

^...^渲染为上标（如 x²），~...~渲染为下标（如 H₂O）。实现来自markdown-it-sup与markdown-it-sub插件（src/lib/core/markdown.js）：

var sub = require('markdown-it-sub') var sup = require('markdown-it-sup')

3.2 下划线与删除线（Underline & Strikethrough）

++underline++ ~~strikethrough~~

++...++渲染为下划线文本（markdown-it-ins插件），~~...~~渲染为删除线（markdown-it-strikethrough由 markdown-it 核心提供）。源码装配见 src/lib/core/markdown.js：

var insert = require('markdown-it-ins') var mark = require('markdown-it-mark')

3.3 标记（Mark）

==mark==

==...==渲染为高亮标记文本，由markdown-it-mark插件提供。工具栏中"下划线、删除线、标记、上标、下标"五个按钮默认全部开启（src/lib/config.js），法语界面对应文案分别为Souligné、Barré、Mark、Exposant、Sous-exposant（src/lib/lang/fr/words_fr.json）。

四、段落结构语法：引用、列表、任务列表

4.1 多级引用（Quote）

支持通过连续>嵌套多层引用，每多一个>深一层：

> quote 1 >> quote 2 >>> quote 3 ...

4.2 有序列表与无序列表（List）

ol 1. 2. 3. ... ul - - ...

有序列表用1. 2. 3.前缀，无序列表用-前缀。工具栏中的ol/ul按钮会调用insertOl()/insertUl()自动插入列表前缀（见 src/lib/toolbar_left_click.js）。

4.3 任务列表（Todo List）

任务列表（勾选清单）是 mavonEditor 的实用特性之一，语法为- [x]（已完成）与- [ ]（未完成）：

- [x] Équipe 1 - [ ] Équipe 2

实现依赖markdown-it-task-lists插件（src/lib/core/markdown.js）：

var taskLists = require('markdown-it-task-lists')

五、链接、图片与代码块

5.1 文本链接与图片链接（Link / Image）

Text Link Text Image Link ![Text](http://www.image.com)

帮助文档原样给出了两种链接的写法。值得一提的实现细节：mavonEditor 在渲染时会为所有<a>链接自动添加target="_blank"，使其在新标签页打开（src/lib/core/markdown.js）：

var defaultRender = markdown.renderer.rules.link_open || function(tokens, idx, options, env, self) { return self.renderToken(tokens, idx, options); }; markdown.renderer.rules.link_open = function (tokens, idx, options, env, self) { var aIndex = tokens[idx].attrIndex('target'); if (aIndex < 0) { tokens[idx].attrPush(['target', '_blank']); } else { tokens[idx].attrs[aIndex][1] = '_blank'; } return defaultRender(tokens, idx, options, env, self); };

工具栏"链接/图片"按钮通过toolbar_left_addlink()插入对应语法结构：文本链接为文本，图片为描述（src/lib/toolbar_left_click.js）。

5.2 代码块与行内代码（Code）

围栏式代码块用三个反引号 + 语言名声明，并支持语法高亮；行内代码用单个反引号包裹：

``` type code block

code

带语言的示例（C++）： ```c++ int main() { printf("hello world!"); }

高亮渲染由 markdown-it 的highlight配置实现（src/lib/core/markdown.js），根据语言从hljsLangs中匹配高亮模式，输出带hljs样式的<pre><code>结构：

highlight: function (str, lang) { if (lang && hljsLangs[lang]) { return '<pre><div class="hljs"><code class="' + lang + '">' + markdown.utils.escapeHtml(str) + '</code></div></pre>'; } return '<pre><code class="' + lang + '">' + markdown.utils.escapeHtml(str) + '</code></pre>'; }

六、表格、脚注与 Emoji

6.1 表格（Table）

GitHub 风格表格：第一行为表头，第二行定义各列对齐方式（:--左对齐、:--:居中、--:右对齐），后续行为数据：

| th1 | th2 | th3 | | :-- | :--: | ----: | | left | center | right |

实际渲染效果：

6.2 脚注（Footnote）

在正文中引用[^hello]，文末定义[^hello]: 脚注内容，点击正文引用即可跳转到对应脚注：

hello[^hello] Look at the bottom[^hello] [^hello]: footnote

脚注解析由markdown-it-footnote插件提供（src/lib/core/markdown.js）。

6.3 Emoji 表情（Emojis）

支持简写式 Emoji 与部分短代码：

:laughing: :blush: :smiley: :) ...

渲染示例：:laughing: :blush: :smiley: :)。实现依赖markdown-it-emoji插件（src/lib/core/markdown.js），可识别完整的 emoji cheat-sheet 短代码表。

七、KaTeX 数学公式

帮助文档用较多篇幅讲解了数学公式渲染能力，这是 mavonEditor 面向技术写作的核心特性。

7.1 行内公式

用单个$包裹，公式随正文流动显示：

$x_i + y_i = z_i$ 和 $\sum_{i=1}^n a_i=0$

渲染示例：$x_i + y_i = z_i$ 和 $\sum_{i=1}^n a_i=0$

7.2 单行独立公式

用双$包裹，公式独占一行居中显示：

$$\sum_{i=1}^n a_i=0$$

渲染示例：

$$\sum_{i=1}^n a_i=0$$

实现上，数学公式渲染由markdown-it-katex-external插件（源码中的变量名katex）挂载，在 src/lib/core/markdown.js 引入、第 89 行 启用：

var katex = require('markdown-it-katex-external'); // ... .use(katex)

KaTeX 语法支持范围以 Khan/KaTeX 官方函数支持表为准，涉及希腊字母、求和/积分、分数、矩阵等 LaTeX 常用数学记号。

八、布局对齐语法（Layout）

mavonEditor 通过markdown-it-container自定义容器实现了三种段落对齐指令，帮助文档中演示了完整写法：

8.1 左对齐（hljs-left）

::: hljs-left left :::

8.2 居中对齐（hljs-center）

::: hljs-center center :::

8.3 右对齐（hljs-right）

::: hljs-right right :::

实现原理：markdown-it-container插件被三次实例化，分别注册hljs-left、hljs-center、hljs-right三个容器名（src/lib/core/markdown.js）：

.use(container, 'hljs-left') /* align left */ .use(container, 'hljs-center')/* align center */ .use(container, 'hljs-right')/* align right */

工具栏中的"左对齐 / 居中 / 右对齐"三个按钮（alignleft/aligncenter/alignright，默认开启，见 src/lib/config.js）插入的正是这类::: hljs-xxx容器块。

九、定义列表（Definition List）与缩写（Abbreviation）

这两项是面向结构化文档的进阶语法，均由独立插件提供。

9.1 定义列表（deflist）

术语行独立成行，随后用:缩进引出定义，定义可以包含多段落与行内标记，甚至内嵌代码块：

Term 1 : Definition 1 Term 2 with *inline markup* : Definition 2 { some code, part of Definition 2 } Third paragraph of definition 2.

实现依赖markdown-it-deflist插件（src/lib/core/markdown.js），渲染为标准的<dl><dt><dd>结构。

9.2 缩写（abbr）

先用*[缩写]: 全称定义缩写，正文中出现的缩写词会被自动替换为带title提示的<abbr>标签：

*[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium The HTML specification is maintained by the W3C.

实现依赖markdown-it-abbr插件（src/lib/core/markdown.js）。

十、从帮助文档到渲染引擎：完整插件装配清单

将帮助文档中的所有语法点与 src/lib/core/markdown.js 的插件装配代码对照，可以画出一张完整的"语法 → 实现"映射表：

帮助文档还提到 CommonMark 语法细节可参考 commonmark.org 的官方 help 页面；KaTeX 的完整函数支持范围可查阅 Khan/KaTeX 官方的 Function-Support 文档，Emoji 短代码全集可参考 emoji-cheat-sheet。本文档即 mavonEditor 内置语法最权威的"承诺清单"——凡是帮助文档中列出的语法，在渲染引擎层面都有对应的插件与测试路径支撑。

十一、实战：在 mavonEditor 中验证与使用这些语法

11.1 打开帮助面板对照学习

将 mavonEditor 集成到 Vue 项目中后（或直接运行仓库的 dev 示例 src/dev/editor.vue），在任意语言环境下：

1. 点击工具栏最右侧的"问号"图标（法语界面为Guide Markdown）；
2. 面板以浮层形式展开，内容即对应语言的帮助文档（法语即本文分析的 src/lib/lang/fr/help_fr.md）；
3. 逐章节对照语法示例，在左侧编辑区输入，右侧实时查看渲染结果。

11.2 更换帮助面板语言

帮助面板语言跟随编辑器的languageprop（默认'zh-CN'，见 src/mavon-editor.vue）。将language设为'fr'即可在法语环境下使用本文档对应的法语帮助面板，界面按钮文案同步切换为 words_fr.json 中的法语词汇。

11.3 语法速查清单

最后，把 help_fr.md 覆盖的全部语法浓缩为一份速查表，方便日常写作时快速查阅：

这份语法全集既来自帮助文档的明示，也由渲染引擎的插件装配逐项背书——理解 help_fr.md，就等于掌握了 mavonEditor 的全部写作能力边界。

• 前端
• UI组件
• 富文本