Return to the list

Table of contents

2025-06-02
3 minute

Flatpages Usage Documents

Flatpages is a simple and powerful static page management system that supports content writing in Markdown format, automatically generates directories, and provides an aesthetic reading interface.

Functional Features

  • Supports the Markdown format to write content
  • Automatically generate article catalogs
  • Code highlighting
  • Read progress instructions
  • Responsive design, support for mobile
  • Support article navigation (Previous/Next)
  • Support article search
  • International support

How to use

1. Configuration Enable

Enable flatpages in the configuration file:

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

2. Create an article

Create a .md file in the statics/flatpages directory, and write it in the following format:

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

3. Markdown format description

Flatpages supports standard Markdown syntax, including:

  • Title (H1-H4)
  • List (ordered and unordered)
  • Code block (supports syntax highlighting)
  • Reference block
  • Link
  • picture
  • Inline code

Code block example:

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

4. Special functions

Code copy

The copy button will be automatically added to the upper right corner of all code blocks to facilitate users to copy the code.

Directory Navigation

The system will automatically generate a directory based on the title of the article (H2-H4) and display it on the right. Directory support:

  • Automatically highlight the current reading position
  • Click to jump
  • Scroll synchronization

Reading progress

A reading progress bar will be displayed at the top of the page, which will visually display the reading position.

Implementation principle

1. File system

Flatpages uses Go's embed.FS to manage static files:

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

2. Routing registration

The system registers the relevant routes through the InitFlatpages function at startup:

  • /fp/ - Article list page
  • /fp/:slug - Article details page

3. Markdown analysis

Use gomarkdown/markdown package for Markdown parsing, support:

  • CommonExtensions
  • AutoHeadingIDs
  • HrefTargetBlank

4. Article management

All Markdown files will be loaded at startup:

  1. Resolve filename as URL slug
  2. Extract the article title (H1)
  3. Extract the article description (first citation block)
  4. Calculate reading time
  5. Record update time

5. Search implementation

The search function of list pages is implemented in JavaScript, which supports real-time search of titles and descriptions.

6. International support

The system integrates i18n support, and multilingual support can be enabled through configuration:

[i18n] 
enable = true 

Best Practices

  1. File Naming
    • Use a meaningful filename, which will be used as part of the URL
    • Avoid special characters and spaces
    • Lowercase letters and hyphens are recommended
  2. Content organization
    • Each file must have an H1 title
    • Use citation blocks to add article description
    • Use secondary and third-level titles reasonably to organize content
    • Control the size of a single file, it is recommended to not exceed 1000 lines.
  3. Image processing
    • The pictures are recommended to be stored in statics/img directory
    • Reference images using relative paths
    • Compress images to increase loading speed
  4. Code display
    • Specify the language of the code block to get the correct syntax highlighting
    • Add comments to important code
    • Make sure the code block is indented correctly

troubleshooting

  1. Page not displayed
    • Check whether flatpages.enable is true in the configuration file
    • Confirm that the Markdown file is in the correct directory
  2. Directory not generated
    • Check whether the article contains a secondary or tertiary title
    • Confirm the title is correct (## or ###)
  3. Style exception
    • Check if Markdown syntax is correct
    • Confirm the file encoding is UTF-8
  4. Invalid search
    • Check the browser console for JavaScript errors
    • Confirm that the page JavaScript loads correctly
Return to the list