Voltar para a lista

Índice

2025-06-02
3 minuto

Documentos de uso da FlatPages

O FlatPages é um sistema de gerenciamento de páginas estático simples e poderoso que suporta a redação de conteúdo no formato de marcação, gera automaticamente diretórios e fornece uma interface de leitura estética.

Recursos funcionais

  • Suporta o formato de marcação para escrever conteúdo
  • Gerar automaticamente catálogos de artigos
  • Código destacando
  • Leia as instruções de progresso
  • Design responsivo, suporte para celular
  • Artigo de suporte Navegação (anterior/próximo)
  • Pesquisa de artigo de suporte
  • Apoio internacional

Como usar

1. Configuração Ativar

Habilite Papages no arquivo de configuração:

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

2. Crie um artigo

Crie um arquivo .md no diretório statics/flatpages e escreva -o no seguinte formato:

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

3. Descrição do formato de marcação

O FlatPages suporta a sintaxe padrão de marcação, incluindo:

  • Título (H1-H4)
  • Lista (ordenada e não ordenada)
  • Bloco de código (suporta destaque da sintaxe)
  • Bloco de referência
  • Link
  • foto
  • Código embutido

Exemplo de bloco de código:

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

4. Funções especiais

Cópia de código

O botão Copiar será adicionado automaticamente ao canto superior direito de todos os blocos de código para facilitar os usuários a copiar o código.

Navegação de diretório

O sistema gerará automaticamente um diretório com base no título do artigo (H2-H4) e o exibirá à direita. Suporte de diretório:

  • Destaque automaticamente a posição de leitura atual
  • Clique para pular
  • Rolagem de sincronização

Leitura Progresso

Uma barra de progresso de leitura será exibida na parte superior da página, que exibirá visualmente a posição de leitura.

Princípio da implementação

1. Sistema de arquivos

O FlatPages usa o Go's embed.FS para gerenciar arquivos estáticos:

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

2. Registro de roteamento

O sistema registra as rotas relevantes através da função InitFlatpages na inicialização:

  • /fp/ - página de lista de artigos
  • /fp/:slug - página de detalhes do artigo

3. Análise de Marydown

Use gomarkdown/markdown para análise de marcação, suporte:

  • CommOnextensions
  • AutoHeadingIds
  • Hreftargetblank

4. Gerenciamento de artigos

Todos os arquivos de marcação serão carregados na inicialização:

  1. Resolva o nome do arquivo como URL Slug
  2. Extraia o título do artigo (H1)
  3. Extraia a descrição do artigo (primeiro bloco de citação)
  4. Calcule o tempo de leitura
  5. Recorde tempo de atualização

5. Implementação de pesquisa

A função de pesquisa das páginas da lista é implementada no JavaScript, que suporta pesquisas em tempo real de títulos e descrições.

6. Apoio internacional

O sistema integra o suporte I18N, e o suporte multilíngue pode ser ativado por meio da configuração:

[i18n] 
enable = true 

Práticas recomendadas

  1. Nomeação de arquivos
    • Use um nome de arquivo significativo, que será usado como parte do URL
    • Evite personagens e espaços especiais
    • Letras minúsculas e hífens são recomendados
  2. Organização de conteúdo
    • Cada arquivo deve ter um título H1
    • Use blocos de citação para adicionar a descrição do artigo
    • Use títulos secundários e de terceiro nível razoavelmente para organizar o conteúdo
    • Controle o tamanho de um único arquivo, recomenda -se não exceder 1000 linhas.
  3. Processamento de imagem
    • As fotos são recomendadas para serem armazenadas no diretório statics/img
    • Imagens de referência usando caminhos relativos
    • Compactar imagens para aumentar a velocidade de carregamento
  4. Exibição de código
    • Especifique o idioma do bloco de código para obter o destaque da sintaxe correta
    • Adicione comentários ao código importante
    • Verifique se o bloco de código está recuado corretamente

solução de problemas

  1. Página não exibida
    • Verifique se flatpages.enable é verdadeiro no arquivo de configuração
    • Confirme que o arquivo de remarcação está no diretório correto
  2. Diretório não gerado
    • Verifique se o artigo contém um título secundário ou terciário
    • Confirme que o título está correto (## ou ###)
  3. Exceção de estilo
    • Verifique se a sintaxe de Markdown está correta
    • Confirme que a codificação do arquivo é UTF-8
  4. Pesquisa inválida
    • Verifique o console do navegador para obter erros de JavaScript
    • Confirme que a página JavaScript carrega corretamente
Voltar para a lista