Torna all'elenco

Sommario

2025-06-02
3 minuto

Documenti di utilizzo di Flatpages

FlatPages è un semplice e potente sistema di gestione statico che supporta la scrittura di contenuti in formato Markdown, genera automaticamente directory e fornisce un'interfaccia di lettura estetica.

Caratteristiche funzionali

  • Supporta il formato Markdown per scrivere contenuti
  • Generare automaticamente cataloghi di articoli
  • Evidenziazione del codice
  • Leggi le istruzioni di avanzamento
  • Design reattivo, supporto per il cellulare
  • Support Article Navigation (precedente/Next)
  • Supporta la ricerca degli articoli
  • Supporto internazionale

Come usare

1. Abilita di configurazione

Abilita FlatPages nel file di configurazione:

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

2. Crea un articolo

Crea un file .md nella directory statics/flatpages e scriverlo nel seguente formato:

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

3. Descrizione del formato markdown

FlatPages supporta la sintassi di markdown standard, tra cui:

  • Titolo (H1-H4)
  • Elenco (ordinato e non ordinato)
  • Blocco codice (supporta l'evidenziazione della sintassi)
  • Blocco di riferimento
  • Collegamento
  • immagine
  • Codice inline

Esempio di blocco del codice:

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

4. Funzioni speciali

Copia del codice

Il pulsante di copia verrà aggiunto automaticamente all'angolo in alto a destra di tutti i blocchi di codice per facilitare gli utenti a copiare il codice.

Navigazione directory

Il sistema genererà automaticamente una directory in base al titolo dell'articolo (H2-H4) e la mostrerà a destra. Supporto directory:

  • Evidenzia automaticamente la posizione di lettura corrente
  • Fai clic per saltare
  • Scorri di sincronizzazione

Leggere i progressi

Una barra di avanzamento di lettura verrà visualizzata nella parte superiore della pagina, che visualizzerà visivamente la posizione di lettura.

Principio di attuazione

1. File system

FlatPages utilizza embed.FS di GO per gestire i file statici:

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

2. Registrazione del routing

Il sistema registra i percorsi pertinenti attraverso la funzione InitFlatpages all'avvio:

  • /fp/ - pagina dell'elenco degli articoli
  • /fp/:slug - pagina dei dettagli dell'articolo

3. Analisi di markdown

Utilizzare gomarkdown/markdown per l'analisi di Markdown, supporto:

  • Commonextensions
  • Autoheadingids
  • Hreftargetblank

4. Gestione degli articoli

Tutti i file di markdown verranno caricati all'avvio:

  1. Risolvi il nome file come Slug URL
  2. Estrai il titolo dell'articolo (H1)
  3. Estrai la descrizione dell'articolo (primo blocco di citazione)
  4. Calcola il tempo di lettura
  5. Tempo di aggiornamento del record

5. Cerca l'implementazione

La funzione di ricerca delle pagine di elenco è implementata in JavaScript, che supporta la ricerca in tempo reale di titoli e descrizioni.

6. Supporto internazionale

Il sistema integra il supporto I18N e il supporto multilingue può essere abilitato attraverso la configurazione:

[i18n] 
enable = true 

Best practice

  1. NAMING FILE
    • Usa un nome file significativo, che verrà utilizzato come parte dell'URL
    • Evita caratteri e spazi speciali
    • Si consigliano lettere e trattini minuscola
  2. Organizzazione dei contenuti
    • Ogni file deve avere un titolo H1
    • Usa i blocchi di citazione per aggiungere la descrizione dell'articolo
    • Usa i titoli secondari e di terzo livello ragionevolmente per organizzare il contenuto
    • Controllare le dimensioni di un singolo file, si consiglia di non superare 1000 righe.
  3. Elaborazione delle immagini
    • Si consiglia alle immagini di essere archiviate nella directory statics/img
    • Immagini di riferimento usando percorsi relativi
    • Comprimere le immagini per aumentare la velocità di caricamento
  4. Visualizzazione del codice
    • Specificare la lingua del blocco di codice per ottenere l'evidenziazione della sintassi corretta
    • Aggiungi commenti a un codice importante
    • Assicurati che il blocco di codice sia rientrato correttamente

Risoluzione dei problemi

  1. Pagina non visualizzata
    • Controlla se flatpages.enable è vero nel file di configurazione
    • Conferma che il file di markdown è nella directory corretta
  2. Directory non generato
    • Controlla se l'articolo contiene un titolo secondario o terziario
    • Conferma il titolo è corretto (## o ###)
  3. Eccezione di stile
    • Controlla se la sintassi di Markdown è corretta
    • Conferma che la codifica del file è UTF-8
  4. Ricerca non valida
    • Controlla la console del browser per gli errori JavaScript
    • Conferma che la pagina JavaScript si carica correttamente
Torna all'elenco