Documentos de uso de platas
FlatPages es un sistema de gestión de páginas estático simple y potente que admite la escritura de contenido en formato de Markdown, genera directorios y proporciona una interfaz de lectura estética.
Características funcionales
- Admite el formato de markdown para escribir contenido
- Generar automáticamente los catálogos de artículos
- Resaltado de código
- Leer instrucciones de progreso
- Diseño receptivo, soporte para dispositivos móviles
- Apoye la navegación del artículo (anterior/siguiente)
- Soporte de búsqueda de artículos
- Apoyo internacional
Cómo usar
1. Habilitación de configuración
Habilitar PLATOPAGE en el archivo de configuración:
[flatpages]
# 是否启用flatpages
enable = true
# 支持配置多个flatpage目录
[[flatpages.dirs]]
nav_name = "帮助文档"
nav_path = "docs"
file_path = "statics/flatpages/docs"
# 每页显示的条目数,可选,默认为10
page_size = 20
# 可以继续添加更多目录配置...
2. Crea un artículo
Cree un archivo .md
en el directorio de statics/flatpages
y escríbelo en el siguiente formato:
# 文章标题
> 文章描述(会显示在列表页)
正文内容...
## 二级标题
### 三级标题
正文内容...
3. Descripción del formato de Markdown
FlatPages admite la sintaxis de Markdown estándar, que incluye:
- Título (H1-H4)
- Lista (ordenada y desordenada)
- Bloque de código (admite resaltar la sintaxis)
- Bloque de referencia
- Enlace
- imagen
- Código en línea
Ejemplo de bloque de código:
def hello():
print("Hello, World!")
4. Funciones especiales
Copia del código
El botón Copiar se agregará automáticamente a la esquina superior derecha de todos los bloques de código para facilitar los usuarios que copien el código.
Navegación de directorio
El sistema generará automáticamente un directorio basado en el título del artículo (H2-H4) y lo mostrará a la derecha. Soporte de directorio:
- Resaltar automáticamente la posición de lectura actual
- Haga clic para saltar
- Sincronización por desplazamiento
Progreso de lectura
Se mostrará una barra de progreso de lectura en la parte superior de la página, que mostrará visualmente la posición de lectura.
Principio de implementación
1. Sistema de archivos
FlatPages usa Go's embed.FS
para administrar archivos estáticos:
//go:embed flatpages/*
var Files embed.FS
2. Registro de enrutamiento
El sistema registra las rutas relevantes a través de la función InitFlatpages
al inicio:
-
/fp/
- Página de lista de artículos -
/fp/:slug
- Página de detalles del artículo
3. Análisis de Markdown
Use gomarkdown/markdown
para el análisis de Markdown, soporte:
- Commonextensions
- Autoheadingids
- Hreftargetblank
4. Gestión de artículos
Todos los archivos de Markdown se cargarán al inicio:
- Resolver el nombre de archivo como Slug URL
- Extraiga el título del artículo (H1)
- Extraiga la descripción del artículo (primer bloque de citas)
- Calcular el tiempo de lectura
- Hora de actualización de registro
5. Implementación de búsqueda
La función de búsqueda de las páginas de lista se implementa en JavaScript, que admite la búsqueda en tiempo real de títulos y descripciones.
6. Apoyo internacional
El sistema integra el soporte I18N, y el soporte multilingüe se puede habilitar a través de la configuración:
[i18n]
enable = true
Mejores prácticas
- Nomentario de archivos
- Use un nombre de archivo significativo, que se utilizará como parte de la URL
- Evite los caracteres y espacios especiales
- Se recomiendan letras en minúsculas y guiones
- Organización de contenido
- Cada archivo debe tener un título H1
- Use bloques de citas para agregar la descripción del artículo
- Use títulos secundarios y de tercer nivel razonablemente para organizar contenido
- Controle el tamaño de un solo archivo, se recomienda que no exceda las 1000 líneas.
- Procesamiento de imágenes
- Se recomienda que las imágenes se almacenen en
statics/img
- Imágenes de referencia utilizando rutas relativas
- Comprimir imágenes para aumentar la velocidad de carga
- Se recomienda que las imágenes se almacenen en
- Visualización de código
- Especifique el lenguaje del bloque de código para obtener el resaltado de sintaxis correcto
- Agregar comentarios al código importante
- Asegúrese de que el bloque de código esté sangrado correctamente
solución de problemas
- Página no se muestra
- Verifique si
flatpages.enable
es cierto en el archivo de configuración - Confirme que el archivo Markdown está en el directorio correcto
- Verifique si
- Directorio no generado
- Verifique si el artículo contiene un título secundario o terciario
- Confirmar que el título es correcto (## o ###)
- Excepción de estilo
- Compruebe si la sintaxis de Markdown es correcta
- Confirmar que la codificación del archivo es UTF-8
- Búsqueda no válida
- Verifique la consola del navegador en busca de errores de JavaScript
- Confirme que la página JavaScript se carga correctamente