Retourner à la liste

Table des matières

2025-06-02
3 minute

Documents d'utilisation des pages à plat

FlatPages est un système de gestion de page statique simple et puissant qui prend en charge l'écriture de contenu au format Markdown, génère automatiquement des répertoires et fournit une interface de lecture esthétique.

Caractéristiques fonctionnelles

  • Prend en charge le format Markdown pour écrire du contenu
  • Générer automatiquement des catalogues d'articles
  • Code de mise en évidence
  • Lire les instructions de progression
  • Conception réactive, support pour mobile
  • Soutenir l'article Navigation (précédent / suivant)
  • Soutenir la recherche d'article
  • Soutien international

Comment utiliser

1. Configuration Activer

Activer les pages plats dans le fichier de configuration:

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

2. Créer un article

Créez un fichier .md dans le répertoire statics/flatpages et écrivez-le dans le format suivant:

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

3. Description du format de marquage

FlatPages prend en charge la syntaxe standard de Markdown, notamment:

  • Titre (H1-H4)
  • Liste (commandée et non ordonnée)
  • Bloc de code (prend en charge la mise en surbrillance de la syntaxe)
  • Bloc de référence
  • Lien
  • image
  • Code en ligne

Exemple de bloc de code:

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

4. Fonctions spéciales

Copie de code

Le bouton de copie sera automatiquement ajouté au coin supérieur droit de tous les blocs de code pour faciliter les utilisateurs pour copier le code.

Navigation d'annuaire

Le système générera automatiquement un répertoire basé sur le titre de l'article (H2-H4) et l'affichera à droite. Prise en charge du répertoire:

  • Mettez automatiquement en surbrillance la position de lecture actuelle
  • Cliquez pour sauter
  • Synchronisation de défilement

Progrès en lecture

Une barre de progression de lecture sera affichée en haut de la page, qui affichera visuellement la position de lecture.

Principe de mise en œuvre

1. Système de fichiers

FlatPages utilise GO embed.FS pour gérer les fichiers statiques:

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

2. Enregistrement de routage

Le système enregistre les routes pertinentes via la fonction InitFlatpages au démarrage:

  • /fp/ - Page de liste d'articles
  • /fp/:slug - Page Détails de l'article

3. Analyse de Markdown

Utilisez gomarkdown/markdown pour l'analyse Markdown, support:

  • Commonextensions
  • Auto-la-tête
  • Hreftargetblank

4. Gestion de l'article

Tous les fichiers Markdown seront chargés au démarrage:

  1. Résoudre le nom de fichier comme limace d'URL
  2. Extraire le titre de l'article (H1)
  3. Extraire la description de l'article (premier bloc de citation)
  4. Calculer le temps de lecture
  5. Temps de mise à jour d'enregistrement

5. Recherche d'implémentation

La fonction de recherche des pages de liste est implémentée dans JavaScript, qui prend en charge la recherche en temps réel des titres et des descriptions.

6. Soutien international

Le système intègre la prise en charge I18N et la prise en charge multilingue peut être activée via la configuration:

[i18n] 
enable = true 

Meilleures pratiques

  1. Dénomination des fichiers
    • Utilisez un nom de fichier significatif, qui sera utilisé dans le cadre de l'URL
    • Évitez les caractères et les espaces spéciaux
    • Des lettres en minuscules et des traits d'entreprise sont recommandés
  2. Organisation de contenu
    • Chaque fichier doit avoir un titre H1
    • Utilisez des blocs de citation pour ajouter une description de l'article
    • Utilisez raisonnablement les titres secondaires et de troisième niveau pour organiser le contenu
    • Contrôlez la taille d'un seul fichier, il est recommandé de ne pas dépasser 1000 lignes.
  3. Traitement d'image
    • Les images sont recommandées pour être stockées dans statics/img
    • Des images de référence utilisant des chemins relatifs
    • Compression des images pour augmenter la vitesse de chargement
  4. Affichage du code
    • Spécifiez la langue du bloc de code pour obtenir la mise en surbrillance de la syntaxe correcte
    • Ajouter des commentaires à un code important
    • Assurez-vous que le bloc de code est correctement en retrait

dépannage

  1. Page non affichée
    • Vérifiez si flatpages.enable est vrai dans le fichier de configuration
    • Confirmez que le fichier Markdown est dans le bon répertoire
  2. Répertoire non généré
    • Vérifiez si l'article contient un titre secondaire ou tertiaire
    • Confirmer que le titre est correct (## ou ###)
  3. Exception de style
    • Vérifiez si la syntaxe de Markdown est correcte
    • Confirmez que l'encodage du fichier est UTF-8
  4. Recherche non valide
    • Vérifiez la console du navigateur pour les erreurs JavaScript
    • Confirmez que la page JavaScript charge correctement
Retourner à la liste