Flatpages Nutzungsdokumente

Flatpages ist ein einfaches und leistungsstarkes statisches Seitenverwaltungssystem, das das Schreiben von Inhalten im Markdown -Format unterstützt, automatisch Verzeichnisse erzeugt und eine ästhetische Leseschnittstelle bietet.

Funktionale Merkmale

Unterstützt das Markdown -Format, um Inhalte zu schreiben
Automatisch Artikelkataloge generieren
Code -Hervorhebung
Fortschrittsanweisungen lesen
Responsive Design, Support für Mobilgeräte
Unterstützung der Artikelnavigation (vorher/nächstes)
Unterstützung der Artikelsuche
Internationale Unterstützung

Wie man benutzt

1. Konfiguration aktivieren

Aktivieren Sie Flatpages in der Konfigurationsdatei:

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

2. Erstellen Sie einen Artikel

Erstellen Sie eine .md -Datei im Verzeichnis statics/flatpages und schreiben Sie sie im folgenden Format:

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

3. Beschreibung des Markdown -Formats

Flatpages unterstützt die Standard -Markdown -Syntax, darunter:

Titel (H1-H4)
Liste (bestellt und ungeordnet)
Codeblock (unterstützt Syntax -Hervorhebung)
Referenzblock
Link
Bild
Inline -Code

Codeblockbeispiel:

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

4. Sonderfunktionen

Codekopie

Die Kopie -Taste wird automatisch zur oberen rechten Ecke aller Codeblöcke hinzugefügt, um den Benutzern das Kopieren des Codes zu erleichtern.

Verzeichnisnavigation

Das System generiert automatisch ein Verzeichnis basierend auf dem Titel des Artikels (H2-H4) und zeigt es rechts an. Verzeichnisunterstützung:

Markieren Sie automatisch die aktuelle Leseposition
Klicken Sie zum Springen
Bildlaufsynchronisation

Lesefortschritt

Am oberen Rand der Seite wird eine Lesebralleiste angezeigt, wodurch die Leseposition visuell angezeigt wird.

Implementierungsprinzip

1. Dateisystem

Flatpages verwendet die GO embed.FS , um statische Dateien zu verwalten:

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

2. Registrierung Routing

Das System registriert die relevanten Routen über die InitFlatpages -Funktion beim Start:

/fp/ - Artikelliste Seite
/fp/:slug - Artikeldetails Seite

3. Markdown -Analyse

Verwenden Sie gomarkdown/markdown -Paket für Markdown -Parsen, Unterstützung:

Commonextinsions
Autoheadingids
HreftargetBlank

4. Artikelmanagement

Alle Markdown -Dateien werden beim Start geladen:

Lösen Sie den Dateinamen als URL -Slug
Extrahieren Sie den Artikeltitel (H1)
Extrahieren Sie die Artikelbeschreibung (erster Zitierblock)
Berechnen Sie die Lesezeit
Aktualisierungszeit aufzeichnen

5. Suchimplementierung

Die Suchfunktion von Listenseiten ist in JavaScript implementiert, das die Echtzeit-Suche nach Titeln und Beschreibungen unterstützt.

6. Internationale Unterstützung

Das System integriert die Unterstützung von I18N, und mehrsprachige Unterstützung kann durch Konfiguration aktiviert werden:

[i18n] 
enable = true

Best Practices

Datei Benennung
- Verwenden Sie einen sinnvollen Dateinamen, der als Teil der URL verwendet wird
- Vermeiden Sie Sonderzeichen und Räume
- Kleinbuchstaben und Bindestriche werden empfohlen
Inhaltsorganisation
- Jede Datei muss einen H1 -Titel haben
- Verwenden Sie Zitierblöcke, um eine Artikelbeschreibung hinzuzufügen
- Verwenden Sie Sekundär- und dritte Titel angemessen, um Inhalte zu organisieren
- Steuern Sie die Größe einer einzelnen Datei, es wird empfohlen, 1000 Zeilen nicht zu überschreiten.
Bildverarbeitung
- Die Bilder werden empfohlen, im Verzeichnis statics/img gespeichert zu werden
- Referenzbilder mit relativen Pfaden
- Komprimieren Sie Bilder, um die Ladegeschwindigkeit zu erhöhen
Codeanzeige
- Geben Sie die Sprache des Codeblocks an, um die richtige Syntax -Hervorhebung zu erhalten
- Fügen Sie Kommentaren zu wichtigem Code hinzu
- Stellen Sie sicher, dass der Codeblock richtig eingerückt ist

Fehlerbehebung

Seite nicht angezeigt
- Überprüfen Sie, ob flatpages.enable in der Konfigurationsdatei wahr ist
- Bestätigen Sie, dass sich die Markdown -Datei im richtigen Verzeichnis befindet
Verzeichnis nicht generiert
- Überprüfen Sie, ob der Artikel einen sekundären oder tertiären Titel enthält
- Bestätigen Sie, dass der Titel korrekt ist (## oder ###)
Stilausnahme
- Überprüfen Sie, ob die Markdown -Syntax korrekt ist
- Bestätigen Sie, dass die Dateikodierung UTF-8 ist
Ungültige Suche
- Überprüfen Sie die Browserkonsole auf JavaScript -Fehler
- Bestätigen Sie, dass die Seite JavaScript korrekt geladen wird

Inhaltsverzeichnis