SongLin

我当前的博客系统对文档 Markdown 格式支持分析与使用指南

最近整理博客时，发现有些 Markdown 格式在我的博客系统中显示效果不太理想，于是决定深入分析一下系统支持的 Markdown 格式。今天就来分享一下我的分析结果，希望能对使用这个博客系统的朋友有所帮助。

核心解析引擎

我的博客系统使用的是 Showdown.js 作为核心解析引擎，这是一个功能强大的 Markdown 解析器库，支持多种扩展格式。

支持的 Markdown 格式

基础格式

  • 标题：支持 H1-H6 标题，使用 # 符号表示
  • 段落：直接输入文本即可
  • 粗体：使用 ** 包围文本，如 粗体
  • 斜体：使用 * 包围文本，如 斜体
  • 链接：使用 文本 格式，如 Google
  • 图片：使用
    alt
    alt
    格式，如
    示例图片
    示例图片
  • 列表：支持有序列表（1. 2. 3.）和无序列表（- * +）
  • 引用：使用 > 符号表示，如 > 这是引用内容
  • 代码块：使用 ``` 包围代码，可指定语言
  • 行内代码：使用 包围代码，如console.log("hello")`
  • 水平线：使用 --- 表示

扩展格式

  • 表格：支持 GitHub 风格表格
  | 表头1 | 表头2 |
  | --- | --- |
  | 内容1 | 内容2 |
  • 删除线：使用 包围文本，如 删除线~~
  • 任务列表：使用 - [x] 表示已完成，- [ ] 表示未完成
  - [x] 任务1
  - [ ] 任务2
  • GitHub 风格代码块：支持指定语言进行语法高亮
  console.log("Hello World");

特殊处理

  • 代码高亮：使用 Prism.js 实现，支持多种编程语言
  • 支持的语言：javascript, typescript, bash, css, markup, json, python, go, yaml, sql, nginx, docker, diff, rust, toml, ini, makefile
  • 图片优化：自动包装为 figure 元素，支持点击放大查看
  • 阿里云 OSS 图片：自动转换为 WebP 格式，提升加载速度
  • 媒体元素：支持视频、音频和 iframe 嵌入
  • 表格：自动添加响应式容器，在移动端显示更友好
  • 自动生成摘要：提取文章前 150 个字符作为摘要

不支持的格式

缺失的扩展

  • 脚注：[^footnote] 格式不支持
  • 定义列表：不支持定义列表格式
  • 数学公式：LaTeX 公式不支持
  • 图表：Mermaid 图表不支持
  • 目录生成：[TOC] 标签不支持
  • 语义化标签：如提示框、警告框等不支持

功能限制

  • 代码块行号：不支持显示代码行号
  • 代码复制按钮：代码块没有复制按钮
  • 响应式图片：除了阿里云 OSS 图片外，其他图片不会自动响应式处理

实例展示

代码高亮示例

// JavaScript 代码示例
function greet() {
  console.log("Hello, Markdown!");
}

greet();

# Python 代码示例
def greet():
    print("Hello, Markdown!")

greet()

表格示例

功能 支持情况 备注
基础格式 ✅ 完全支持
表格 ✅ GitHub 风格
代码高亮 ✅ 支持多种语言
脚注 ❌ 不支持
数学公式 ❌ 不支持

任务列表示例

  • 分析 Markdown 解析引擎
  • 测试支持的格式
  • 整理不支持的格式
  • 实现扩展功能

解析流程

  1. YAML 头部解析：使用 front-matter 库解析文章头部元数据
  2. Markdown 转换：使用 Showdown 库将 Markdown 转换为 HTML
  3. 摘要生成：提取前 150 个字符作为文章摘要
  4. 代码高亮：使用 Prism.js 为代码块添加语法高亮
  5. 媒体处理：包装图片、视频、音频和 iframe 为 figure 元素
  6. 表格处理：为表格添加响应式容器
  7. 元数据处理：处理发布时间、更新时间等信息

优化建议

  1. 添加脚注支持：通过 Showdown 扩展实现
  2. 添加数学公式支持：集成 MathJax 或 KaTeX
  3. 添加图表支持：集成 Mermaid
  4. 添加目录生成：实现 [TOC] 功能
  5. 添加代码块行号：增强代码可读性
  6. 添加代码复制按钮：提升用户体验
  7. 图片压缩：在构建时自动压缩图片
  8. 响应式图片：为所有图片添加响应式处理

总结

我的博客系统使用 Showdown.js 作为核心解析引擎，支持大多数常用的 Markdown 格式，并添加了一些实用的扩展功能。虽然缺少一些高级功能，但对于一般的博客文章已经足够使用。

系统的解析流程清晰，代码结构合理，具有良好的可扩展性。通过添加适当的扩展和优化，可以进一步提升系统的功能和性能。

如果你在使用过程中遇到格式显示问题，可以参考本文档了解哪些格式是支持的，哪些是不支持的，以便更好地编写你的博客文章。