目录

2025-06-02
3 分钟

Flatpages 使用文档

Flatpages 是一个简单而强大的静态页面管理系统,支持 Markdown 格式的内容编写,自动生成目录,并提供美观的阅读界面。

功能特点

  • 支持 Markdown 格式编写内容
  • 自动生成文章目录
  • 代码高亮显示
  • 阅读进度指示
  • 响应式设计,支持移动端
  • 支持文章导航(上一篇/下一篇)
  • 支持文章搜索
  • 国际化支持

使用方法

1. 配置启用

在配置文件中启用 flatpages 功能:

[flatpages]
    # 是否启用flatpages
    enable = true
    # 支持配置多个flatpage目录
    [[flatpages.dirs]]
        nav_name = "帮助文档"
        nav_path = "docs"
        file_path = "statics/flatpages/docs"
        # 每页显示的条目数,可选,默认为10
        page_size = 20

    # 可以继续添加更多目录配置...

2. 创建文章

statics/flatpages 目录下创建 .md 文件,按照以下格式编写:

# 文章标题

> 文章描述(会显示在列表页)

正文内容...

## 二级标题

### 三级标题

正文内容...

3. Markdown 格式说明

Flatpages 支持标准 Markdown 语法,包括:

  • 标题(H1-H4)
  • 列表(有序和无序)
  • 代码块(支持语法高亮)
  • 引用块
  • 链接
  • 图片
  • 行内代码

代码块示例:

def hello():
    print("Hello, World!")

4. 特殊功能

代码复制

所有代码块右上角都会自动添加复制按钮,方便用户复制代码。

目录导航

系统会自动根据文章的标题(H2-H4)生成目录,并在右侧显示。目录支持:

  • 自动高亮当前阅读位置
  • 点击跳转
  • 滚动同步

阅读进度

页面顶部会显示阅读进度条,直观展示阅读位置。

实现原理

1. 文件系统

Flatpages 使用 Go 的 embed.FS 来管理静态文件:

//go:embed flatpages/*
var Files embed.FS

2. 路由注册

系统在启动时通过 InitFlatpages 函数注册相关路由:

  • /fp/ - 文章列表页
  • /fp/:slug - 文章详情页

3. Markdown 解析

使用 gomarkdown/markdown 包进行 Markdown 解析,支持:

  • CommonExtensions
  • AutoHeadingIDs
  • HrefTargetBlank

4. 文章管理

系统会在启动时加载所有 Markdown 文件:

  1. 解析文件名作为 URL slug
  2. 提取文章标题(H1)
  3. 提取文章描述(第一个引用块)
  4. 计算阅读时间
  5. 记录更新时间

5. 搜索实现

列表页的搜索功能使用 JavaScript 实现,支持对标题和描述的实时搜索。

6. 国际化支持

系统集成了 i18n 支持,可以通过配置启用多语言支持:

[i18n]
enable = true

最佳实践

  1. 文件命名
    • 使用有意义的文件名,它将作为 URL 的一部分
    • 避免使用特殊字符和空格
    • 推荐使用小写字母和连字符
  2. 内容组织
    • 每个文件必须有一个 H1 标题
    • 使用引用块来添加文章描述
    • 合理使用二级和三级标题来组织内容
    • 控制单个文件的大小,建议不超过 1000 行
  3. 图片处理
    • 图片建议存放在 statics/img 目录下
    • 使用相对路径引用图片
    • 压缩图片以提高加载速度
  4. 代码展示
    • 指定代码块的语言以获得正确的语法高亮
    • 为重要的代码添加注释
    • 确保代码块的缩进正确

故障排除

  1. 页面未显示
    • 检查配置文件中 flatpages.enable 是否为 true
    • 确认 Markdown 文件位于正确的目录
  2. 目录未生成
    • 检查文章是否包含二级或三级标题
    • 确认标题格式正确(## 或 ###)
  3. 样式异常
    • 检查 Markdown 语法是否正确
    • 确认文件编码为 UTF-8
  4. 搜索无效
    • 检查浏览器控制台是否有 JavaScript 错误
    • 确认页面 JavaScript 正确加载