Kembali ke daftar

Daftar isi

2025-06-02
3 menit

Dokumen Penggunaan FlatPages

FlatPages adalah sistem manajemen halaman statis yang sederhana dan kuat yang mendukung penulisan konten dalam format markdown, secara otomatis menghasilkan direktori, dan menyediakan antarmuka membaca estetika.

Fitur fungsional

  • Mendukung format markdown untuk menulis konten
  • Secara otomatis menghasilkan katalog artikel
  • Sorotan Kode
  • Baca instruksi kemajuan
  • Desain responsif, dukungan untuk seluler
  • Dukungan Navigasi Artikel (Sebelumnya/Berikutnya)
  • Pencarian Artikel Dukungan
  • Dukungan Internasional

Cara menggunakan

1. Konfigurasi Aktifkan

Aktifkan FlatPages di file konfigurasi:

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

2. Buat artikel

Buat file .md di direktori statics/flatpages , dan tulis dalam format berikut:

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

3. Deskripsi Format Markdown

FlatPages mendukung sintaks markdown standar, termasuk:

  • Judul (H1-H4)
  • Daftar (dipesan dan tidak dipesan)
  • Blok kode (mendukung penyorotan sintaks)
  • Blok referensi
  • Link
  • gambar
  • Kode inline

Contoh blok kode:

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

4. Fungsi Khusus

Salinan Kode

Tombol salin akan ditambahkan secara otomatis ke sudut kanan atas semua blok kode untuk memfasilitasi pengguna untuk menyalin kode.

Navigasi Direktori

Sistem akan secara otomatis menghasilkan direktori berdasarkan judul artikel (H2-H4) dan menampilkannya di sebelah kanan. Dukungan Direktori:

  • Secara otomatis menyoroti posisi membaca saat ini
  • Klik untuk melompat
  • Sinkronisasi gulir

Kemajuan Membaca

Bilah Kemajuan Membaca akan ditampilkan di bagian atas halaman, yang secara visual akan menampilkan posisi membaca.

Prinsip Implementasi

1. Sistem File

FlatPages menggunakan go's embed.FS untuk mengelola file statis:

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

2. Pendaftaran perutean

Sistem mendaftarkan rute yang relevan melalui fungsi InitFlatpages saat startup:

  • /fp/ - halaman daftar artikel
  • /fp/:slug - halaman detail artikel

3. Analisis Markdown

Gunakan paket gomarkdown/markdown untuk parsing markdown, dukungan:

  • Commonextensions
  • AutoHeadingIDS
  • HreftargetBlank

4. Manajemen Artikel

Semua file Markdown akan dimuat saat startup:

  1. Menyelesaikan nama file sebagai slug url
  2. Ekstrak judul artikel (H1)
  3. Ekstrak deskripsi artikel (blok kutipan pertama)
  4. Hitung waktu membaca
  5. Rekam waktu pembaruan

5. Implementasi Pencarian

Fungsi pencarian halaman daftar diimplementasikan dalam JavaScript, yang mendukung pencarian judul dan deskripsi real-time.

6. Dukungan Internasional

Sistem ini mengintegrasikan dukungan I18N, dan dukungan multibahasa dapat diaktifkan melalui konfigurasi:

[i18n] 
enable = true 

Praktik terbaik

  1. File penamaan
    • Gunakan nama file yang bermakna, yang akan digunakan sebagai bagian dari URL
    • Hindari karakter dan ruang khusus
    • Surat huruf kecil dan tanda hubung direkomendasikan
  2. Organisasi konten
    • Setiap file harus memiliki judul H1
    • Gunakan blok kutipan untuk menambahkan deskripsi artikel
    • Gunakan judul sekunder dan tingkat ketiga secara wajar untuk mengatur konten
    • Kontrol ukuran satu file, disarankan untuk tidak melebihi 1000 baris.
  3. Pemrosesan gambar
    • Gambar disarankan untuk disimpan di direktori statics/img
    • Gambar referensi menggunakan jalur relatif
    • Kompres gambar untuk meningkatkan kecepatan pemuatan
  4. Tampilan Kode
    • Tentukan bahasa blok kode untuk mendapatkan sorotan sintaks yang benar
    • Tambahkan komentar ke kode penting
    • Pastikan blok kode indentasi dengan benar

Pemecahan masalah

  1. Halaman tidak ditampilkan
    • Periksa apakah flatpages.enable benar dalam file konfigurasi
    • Konfirmasikan bahwa file markdown ada di direktori yang benar
  2. Direktori tidak dihasilkan
    • Periksa apakah artikel tersebut berisi judul sekunder atau tersier
    • Konfirmasikan judulnya benar (## atau ###)
  3. Pengecualian Gaya
    • Periksa apakah sintaks penandaan itu benar
    • Konfirmasikan pengkodean file adalah UTF-8
  4. Pencarian tidak valid
    • Periksa konsol browser untuk kesalahan javascript
    • Konfirmasikan bahwa halaman javascript memuat dengan benar
Kembali ke daftar