Вернуться в список

Оглавление

2025-06-02
3 минута

Документы использования плоских страниц

Flatpages - это простая и мощная статическая система управления страницами, которая поддерживает написание контента в формате разметки, автоматически генерирует каталоги и обеспечивает эстетический интерфейс чтения.

Функциональные особенности

  • Поддерживает формат разметки для написания контента
  • Автоматически генерировать каталоги статей
  • Подсветка кода
  • Прочитайте инструкции по прогрессу
  • Отзывчивый дизайн, поддержка мобильных
  • Навигация по поддержке статьи (предыдущий/следующий)
  • Поддержка поиска статьи
  • Международная поддержка

Как использовать

1. Включение конфигурации

Включить плоские страницы в файле конфигурации:

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

2. Создать статью

Создайте файл .md в каталоге statics/flatpages и напишите его в следующем формате:

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

3. Описание формата Marckdown

Flatpages поддерживает стандартный синтаксис разметки, в том числе:

  • Название (H1-H4)
  • Список (упорядоченный и неупорядоченный)
  • Кодовый блок (поддерживает выделение синтаксиса)
  • Справочный блок
  • Связь
  • картина
  • Встроенный код

Пример блока кода:

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

4. Специальные функции

Код копия

Кнопка копирования будет автоматически добавлена ​​в верхний правый угол всех кодовых блоков, чтобы облегчить пользователям копировать код.

Навигация по каталогу

Система автоматически генерирует каталог на основе названия статьи (H2-H4) и отобразить его справа. Поддержка каталога:

  • Автоматически выделить текущую позицию чтения
  • Нажмите, чтобы прыгнуть
  • Синхронизация прокрутки

Прогресс чтения

В верхней части страницы будет отображаться панель прогресса чтения, которая визуально отображает позицию чтения.

Принцип реализации

1. Файл -система

FlatePages использует go embed.FS для управления статическими файлами:

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

2. Регистрация маршрутизации

Система регистрирует соответствующие маршруты через функцию InitFlatpages при запуске:

  • /fp/ - страница списка статьи
  • /fp/:slug - страница сведений в статье

3. Анализ отметки

Используйте пакет gomarkdown/markdown для анализа Markdown, поддержка:

  • Commonextensions
  • AutoHeadingids
  • HreftargetBlank

4. Управление статьями

Все файлы разметки будут загружены при запуске:

  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 в файле конфигурации
    • Убедитесь, что файл разметки находится в правильном каталоге
  2. Каталог не генерируется
    • Проверьте, содержит ли статья вторичное или третичное название
    • Подтвердите, что заголовок верен (## или ###)
  3. Стиль исключение
    • Проверьте, правильно ли синтаксис разметки
    • Подтвердите, что кодирование файла-UTF-8
  4. Неверный поиск
    • Проверьте консоли браузера на ошибки JavaScript
    • Подтвердите, что страница JavaScript правильно загружается
Вернуться в список