返回列表

目錄

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 正確加載
返回列表