Trở lại danh sách

Mục lục

2025-06-02
3 phút

Tài liệu sử dụng FlatPages

FlatPages là một hệ thống quản lý trang tĩnh đơn giản và mạnh mẽ, hỗ trợ viết nội dung ở định dạng Markdown, tự động tạo các thư mục và cung cấp giao diện đọc thẩm mỹ.

Các tính năng chức năng

  • Hỗ trợ định dạng đánh dấu để ghi nội dung
  • Tự động tạo danh mục bài viết
  • Mã làm nổi bật
  • Đọc hướng dẫn tiến trình
  • Thiết kế đáp ứng, hỗ trợ cho thiết bị di động
  • Hỗ trợ điều hướng bài viết (trước/tiếp theo)
  • Hỗ trợ tìm kiếm bài viết
  • Hỗ trợ quốc tế

Cách sử dụng

1. Kích hoạt cấu hình

Bật FLATPAGE trong tệp cấu hình:

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

2. Tạo một bài viết

Tạo tệp .md trong thư mục statics/flatpages và ghi nó theo định dạng sau:

# 文章标题 
 
> 文章描述（会显示在列表页） 
 
正文内容... 
 
## 二级标题 
 
### 三级标题 
 
正文内容... 

3. Mô tả định dạng đánh dấu

FlatPages hỗ trợ cú pháp tiêu chuẩn Markdown, bao gồm:

  • Tiêu đề (H1-H4)
  • Danh sách (đặt hàng và không theo thứ tự)
  • Khối mã (hỗ trợ làm nổi bật cú pháp)
  • Khối tham chiếu
  • Liên kết
  • hình ảnh
  • Mã nội tuyến

Ví dụ khối mã:

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

4. Chức năng đặc biệt

Sao chép mã

Nút sao chép sẽ được tự động thêm vào góc trên bên phải của tất cả các khối mã để tạo điều kiện cho người dùng sao chép mã.

Điều hướng thư mục

Hệ thống sẽ tự động tạo một thư mục dựa trên tiêu đề của bài viết (H2-H4) và hiển thị nó ở bên phải. Hỗ trợ thư mục:

  • Tự động làm nổi bật vị trí đọc hiện tại
  • Bấm để nhảy
  • Cuộn đồng bộ hóa

Đọc tiến trình

Một thanh tiến trình đọc sẽ được hiển thị ở đầu trang, sẽ hiển thị trực quan vị trí đọc.

Nguyên tắc thực hiện

1. Hệ thống tệp

FlatPages sử dụng GO's embed.FS để quản lý các tệp tĩnh:

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

2. Đăng ký định tuyến

Hệ thống đăng ký các tuyến đường có liên quan thông qua chức năng InitFlatpages khi khởi động:

  • /fp/ - trang danh sách bài viết
  • /fp/:slug - trang chi tiết bài viết

3. Phân tích Markdown

Sử dụng gói gomarkdown/markdown để phân tích cú pháp đánh dấu, hỗ trợ:

  • Commonextensions
  • Autoheadingids
  • Hreftargetblank

4. Quản lý bài viết

Tất cả các tệp Markdown sẽ được tải khi khởi động:

  1. Giải quyết tên tệp dưới dạng sên URL
  2. Trích xuất tiêu đề bài viết (H1)
  3. Trích xuất mô tả bài viết (Khối trích dẫn đầu tiên)
  4. Tính thời gian đọc
  5. Ghi lại thời gian cập nhật

5. Thực hiện tìm kiếm

Chức năng tìm kiếm của các trang danh sách được triển khai trong JavaScript, hỗ trợ tìm kiếm thời gian thực các tiêu đề và mô tả.

6. Hỗ trợ quốc tế

Hệ thống tích hợp hỗ trợ i18N và hỗ trợ đa ngôn ngữ có thể được bật thông qua cấu hình:

[i18n] 
enable = true 

Thực tiễn tốt nhất

  1. Đặt tên tập tin
    • Sử dụng tên tệp có ý nghĩa, sẽ được sử dụng như một phần của URL
    • Tránh các ký tự và không gian đặc biệt
    • Chữ thường và dấu gạch nối được khuyến nghị
  2. Tổ chức nội dung
    • Mỗi tệp phải có tiêu đề H1
    • Sử dụng các khối trích dẫn để thêm mô tả bài viết
    • Sử dụng các tiêu đề cấp phụ và cấp ba một cách hợp lý để tổ chức nội dung
    • Kiểm soát kích thước của một tệp, nên không vượt quá 1000 dòng.
  3. Xử lý hình ảnh
    • Các hình ảnh được khuyến nghị được lưu trữ trong thư mục statics/img
    • Hình ảnh tham chiếu sử dụng các đường dẫn tương đối
    • Nén hình ảnh để tăng tốc độ tải
  4. Hiển thị mã
    • Chỉ định ngôn ngữ của khối mã để có được cú pháp chính xác
    • Thêm nhận xét vào mã quan trọng
    • Đảm bảo rằng khối mã được thụt vào chính xác

Khắc phục sự cố

  1. Trang không được hiển thị
    • Kiểm tra xem flatpages.enable có đúng trong tệp cấu hình không
    • Xác nhận rằng tệp đánh dấu nằm trong thư mục chính xác
  2. Thư mục không được tạo ra
    • Kiểm tra xem bài viết có chứa tiêu đề thứ cấp hay đại học
    • Xác nhận tiêu đề là chính xác (## hoặc ###)
  3. Ngoại lệ phong cách
    • Kiểm tra xem cú pháp đánh dấu có đúng không
    • Xác nhận mã hóa tệp là UTF-8
  4. Tìm kiếm không hợp lệ
    • Kiểm tra bảng điều khiển trình duyệt để biết lỗi JavaScript
    • Xác nhận rằng trang javascript tải chính xác
Trở lại danh sách