Listeye Dön

İçindekiler

2025-06-02
3 dakika

Düz sayfa kullanım belgeleri

FlatPages, içerik yazmayı markdown formatında destekleyen, otomatik olarak dizinler üreten ve estetik bir okuma arayüzü sağlayan basit ve güçlü bir statik sayfa yönetim sistemidir.

İşlevsel özellikler

  • İçerik yazmak için işaretleme biçimini destekler
  • Otomatik olarak makale katalogları oluşturun
  • Kod Vurgulama
  • İlerleme Talimatlarını Oku
  • Duyarlı tasarım, mobil cihazlar için destek
  • Destek Makale Gezinme (Önceki/Sonraki)
  • Makale Arama Destek
  • Uluslararası Destek

Nasıl Kullanılır

1. Yapılandırma etkinleştir

Yapılandırma dosyasındaki düz sayfaları etkinleştirin:

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

2. Bir Makale Oluşturun

statics/flatpages dizininde bir .md dosyası oluşturun ve aşağıdaki formatta yazın:

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

3. Markdown Biçim Açıklaması

FlatPages, aşağıdakileri dahil olmak üzere standart markdown sözdizimini destekler:

  • Başlık (H1-H4)
  • Liste (Sipariş Edildi ve Sırasız)
  • Kod Bloğu (Sözdizimi Vurgulamayı Destekler)
  • Referans bloğu
  • Bağlantı
  • resim
  • Satır içi kodu

Kod bloğu örneği:

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

4. Özel işlevler

Kod kopyası

Kullanıcıların kodu kopyalamasını kolaylaştırmak için tüm kod bloklarının sağ üst köşesine otomatik olarak kopyalama düğmesi eklenir.

Dizin gezinmesi

Sistem, makalenin (H2-H4) başlığına göre otomatik olarak bir dizin oluşturacak ve sağda görüntülenecektir. Dizin Desteği:

  • Geçerli okuma konumunu otomatik olarak vurgulayın
  • Atlamak için tıklayın
  • Kaydırma senkronizasyonu

Okuma İlerleme

Okuma konumunu görsel olarak görüntüleyecek olan sayfanın üstünde bir okuma ilerleme çubuğu görüntülenecektir.

Uygulama İlkesi

1. Dosya Sistemi

FlatPages, statik dosyaları yönetmek için Go's embed.FS kullanır:

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

2. Yönlendirme kaydı

Sistem, başlangıçta InitFlatpages işlevi aracılığıyla ilgili yolları kaydeder:

  • /fp/ - makale listesi sayfası
  • /fp/:slug - makale detayları sayfası

3. Markdown analizi

Markdown ayrıştırma, destek için gomarkdown/markdown paketini kullanın:

  • Commonextentions
  • Otomatik başlıklar
  • HreftargetBlank

4. Makale Yönetimi

Tüm Markdown dosyaları başlangıçta yüklenecektir:

  1. Dosya adını url slug olarak çözün
  2. Makale başlığını çıkarın (H1)
  3. Makale açıklamasını çıkarın (ilk alıntı bloğu)
  4. Okuma süresini hesapla
  5. Güncelleme Süresini Kaydet

5. Arama uygulaması

Liste sayfalarının arama işlevi, başlıkların ve açıklamaların gerçek zamanlı aramasını destekleyen JavaScript'te uygulanır.

6. Uluslararası Destek

Sistem i18n desteğini entegre eder ve çok dilli destek yapılandırma yoluyla etkinleştirilebilir:

[i18n] 
enable = true 

En İyi Uygulamalar

  1. Dosya Adlandırma
    • URL'nin bir parçası olarak kullanılacak anlamlı bir dosya adı kullanın
    • Özel karakterlerden ve alanlardan kaçının
    • Küçük harf ve tire önerilir
  2. İçerik Organizasyonu
    • Her dosyanın bir H1 başlığı olması gerekir
    • Makale Açıklaması eklemek için alıntı bloklarını kullanın
    • İçeriği düzenlemek için ikincil ve üçüncü seviyeli başlıkları makul olarak kullanın
    • Tek bir dosyanın boyutunu kontrol edin, 1000 satırı geçmemesi önerilir.
  3. Görüntü işleme
    • Resimlerin statics/img dizininde saklanması önerilir
    • Göreceli yolları kullanarak görüntüleri referans
    • Yükleme hızını artırmak için görüntüleri sıkıştırın
  4. Kod ekranı
    • Doğru sözdizimi vurgulamayı almak için kod bloğunun dilini belirtin
    • Önemli koda yorum ekle
    • Kod bloğunun doğru girintili olduğundan emin olun

sorun giderme

  1. Sayfa görüntülenmedi
    • flatpages.enable yapılandırma dosyasında doğru olup olmadığını kontrol edin
    • Markdown dosyasının doğru dizinde olduğunu onaylayın
  2. Dizin oluşturulmadı
    • Makalenin ikincil veya üçüncül bir başlık içerip içermediğini kontrol edin
    • Başlığın doğru olduğunu onaylayın (## veya ###)
  3. Stil istisnası
    • Markdown sözdiziminin doğru olup olmadığını kontrol edin
    • Dosya kodlamasının UTF-8 olduğunu onaylayın
  4. Geçersiz arama
    • JavaScript hataları için tarayıcı konsolunu kontrol edin
    • JavaScript sayfasının doğru yüklendiğini onaylayın
Listeye Dön