Yapılandırma

Eklenti seçeneklerini ve isteğe bağlı Vite ayarlarını sitelo.config.js içine koyun. vite.config.js gerekmez.

export default {
  site: 'https://example.com',
  rss: {
    site: 'https://example.com',
    title: 'Blogum',
    description: 'Son yazılar',
    routePrefix: '/blog',
  },
  vite: {
    publicDir: 'static',
    build: {
      emptyOutDir: true,
      outDir: 'public',
    },
    server: {
      port: 8888,
    },
  },
}

Eklenti seçenekleri

Geliştirme araç çubuğu

sitelo (geliştirme) çalışırken her sayfanın altındaki küçük bir çubuk sayfa dosyasını, parametreleri ve sayfada kaç sunucu adası olduğunu gösterir. Desktop / Tablet / Mobile önizlemesi arasında geçmek için görünüm düğmesini (iframe olduğundan medya sorguları uyuşur), sorun bildirirken hata ayıklama bilgisi için Copy düğmesini kullanın. sitelo build çıktısında hiç görünmez.

// sitelo.config.js
export default {
  devToolbar: false, // bu projede herkes için gizle
}

Vite seçenekleri

vite altındaki her şey Vite’ın yapılandırmasıyla birleştirilir. CLI bayrakları (örneğin --port) ikisini de geçersiz kılar.

Sitelo derlemeleri build.rollupOptions.checks.pluginTimings: false ayarlar. Rolldown aksi hâlde derlemeye eklenti kancalarının egemen olduğunu bildirir; bu bir sitelo sitesinde her zaman doğrudur — sayfaları üretmek zaten derlemenin kendisidir — dolayısıyla her çalıştırmada aynı eklentiyi adlandırır. Kendi eklentilerinizi profillerken vite altında true yapın.

Var olan vite.config.js

Hâlâ destekleniyor — ya yalnızca Vite seçenekleri ya da eklenti üzerinde tam denetim:

// Yalnızca Vite seçenekleri; sitelo eklentiyi yine de ekler
export default {
  publicDir: 'static',
  server: { port: 8888 },
}
// Eklentiyi kendin kaydet
import htmlPages from 'sitelo'

export default {
  plugins: [htmlPages({
    site: 'https://example.com',
  })],
}

Eklenti zaten Vite yapılandırmanızdaysa eklenti seçeneklerini oraya koyun — ayrıca sitelo.config.js içinde de eklenti seçeneği olarak değil (sitelo hata verir).

Site haritası ve RSS

dist/sitemap.xml üretmek için site değerini ayarlayın.

RSS:

export default {
  rss: {
    site: 'https://example.com',
    title: 'Blogum',
    description: 'Son yazılar',
    routePrefix: '/blog',
  },
}

routePrefix altındaki her sayfa için bir öğe içeren dist/rss.xml üretir.

Bağlantı denetimi

Bozuk <script src> ve stil sayfası href değerleri derlemeyi zaten düşürür (bkz. missingAssets). linkCheck öbür yarıyı kapsar: var olmayan bir sayfayı gösteren iç <a href> bağlantıları.

export default {
  linkCheck: true,   // 'warn' (varsayılan), 'error' ya da bir seçenek nesnesi
}

sitelo build sonrasında çıktıdaki her iç bağlantı çözülür ve arkasında sayfa olmayan her şey, göründüğü sayfaya göre gruplanarak bildirilir:

[sitelo] 3 kırık iç bağlantılar

  index.html
    ../escape           -> çıktı dizininin dışına çıkıyor
    /abuot              -> böyle bir sayfa yok
    /blog/missing-post  -> böyle bir sayfa yok

Bağlantılar nasıl çözülür

Denetim rota tablosuna değil, üretilen siteye karşı çalışır — bu yüzden cleanUrls, rota grupları, mapOutputPath, public/ içinden kopyalanan dosyalar ve dinamik rotaların ürettiği sayfalar hesaba katılır. Ayrıca görsel optimizasyonundan ve Pagefind’den sonra çalışır, dolayısıyla tam olarak yayımlananı görür. Bir bağlantı, statik bir sunucunun deneyeceği sırayla gerçek bir dosya yanıt verdiğinde geçerlidir:

Göreli bağlantılar (../about) onları barındıran sayfaya göre çözülür ve çıktı dizininin dışına tırmanan biri bildirilir. Sorgu dizeleri çözümlemede yok sayılır — /about?utm=x için /about denetlenir.

Dış bağlantılar hiçbir zaman getirilmez. https://, protokole göreli //cdn.example.com, mailto:, tel: ve diğer şemalar tümüyle atlanır.

Seçenekler

SeçenekVarsayılanAçıklama
mode'warn''warn' günlükler ve sürdürür; 'error' derlemeyi düşürür — CI’da kullanışlıdır
exclude[]Atlanacak href değerlerinin globları ya da düzenli ifadeleri
checkFragmentsfalseBağlantılı sayfada #fragment hedeflerinin var olduğunu da doğrular
export default {
  linkCheck: {
    mode: 'error',                    // ölü bağlantıda derlemeyi başarısız kıl
    checkFragments: true,             // #parça hedeflerini de doğrula
    exclude: ['/api/**', /^\/legacy\//],
  },
}

checkFragments varsayılan olarak kapalıdır, çünkü istemci tarafı JavaScript’in eklediği kimlikler derlenmiş HTML’de bulunmaz ve eksik olarak bildirilirdi. Hem id hem de eski çapa name öznitelikleri parça hedefi sayılır.

Bir temelden sunulan siteler

Siteniz bir base altında dağıtılıyorsa (diyelim bir GitHub Pages proje sitesi), o temeli taşımayan kök göreli bir bağlantı bildirilir. /repo/ üzerinden sunulan bir sitedeki /about bağlantısı tarayıcıyı sitenize değil sunucu köküne gönderir — onu yine de çıktıya göre çözmek, tam da yakalanmaya değer hatayı gizlerdi. Kasıtlı olduğunda exclude kullanın.

Lighthouse denetimleri

sitelo lighthouse, bitmiş derlemeyi Lighthouse ile denetler. İsteğe bağlı bir eş bağımlılıktır:

npm install -D lighthouse

sitelo, dist/ dizinini sitelo preview gibi sunar, başsız bir Chrome’u her sayfaya yöneltir ve puanları yazdırır:

[sitelo] lighthouse mobile - 3 pages

  page           perf  a11y  best   seo
  /                98   100   100   100
  /docs            95   100   100   100
  /docs/routing    97   100   100   100

[sitelo] lighthouse audited 3 pages in 31.4s

Her sayfa, sitenin bağladığı URL’de denetlenir — /docs, asla dist/docs.html değil — bu yüzden cleanUrls, rota grupları ve bir base hepsi hesaba katılır. Eşikler ekleyin, rapor bir denetime dönüşsün: eşiğinin altındaki her puan komutu başarısız kılar.

export default {
  lighthouse: {
    exclude: ['404.html'],   // 404 sayfasını denetlemeye genelde değmez
    thresholds: {
      performance: 90,
      accessibility: 100,
      'best-practices': 95,
      seo: 100,
    },
  },
}

Puanlar Lighthouse’un gösterdiği biçimde yazılır (0–100); kendi 0–1 kesirleri de çalışır. Düşürmek yerine günlüklemek için mode: 'warn' kullanın.

export default {
  lighthouse: {
    formFactor: 'desktop',   // Lighthouse masaüstü ön ayarı
    runs: 3,                 // sayfa başına üç çalıştırma, ortanca puan
    output: true,            // tam raporlar .sitelo/lighthouse/ içinde
    onBuild: true,           // sitelo build sonunda da denetle
    flags: { throttlingMethod: 'provided' },
  },
}

Lighthouse gerçek bir Chrome sürer: denetimin çalıştığı yere bir tane kurun ya da CHROME_PATH değişkenini bir ikili dosyaya yöneltin. Başarım puanları çalıştırmalar arasında oynar, bu yüzden onlara bir eşik sabitlemeden önce runs: 3 kullanın.

Pagefind araması

İsteğe bağlı bir eş bağımlılık olan Pagefind ile çalışan, tercihe bağlı statik arama. Arama istediğinizde onu kurun, sonra dizinlemeyi açın, içeriği işaretleyin, arayüzü bağlayın ve sitelo build çalıştırın.

npm install -D pagefind

1. Dizinlemeyi açın

pagefind: true ayarlayın. sitelo build sonrasında dist/pagefind/ dizinini ve varsayılan olarak public/pagefind/ içinde bir kopyasını alırsınız; böylece bir sonraki sitelo (geliştirme) ya da sitelo preview yeniden derlemeden /pagefind/ adresini sunabilir.

export default {
  pagefind: true,
}

2. İçeriği işaretleyin ve bir bağlama noktası ekleyin

Gezinme ve alt bilgi dizinlenmesin diye ana içeriğe data-pagefind-body koyun. Arama arayüzü için boş bir öğe bırakın:

import {
  html, head, title, link, script, body, header, a, div, main, h1, p,
} from 'javascript-to-html'

export default () =>
  html({ lang: 'tr' },
    head(
      title('Sitem'),
      link({ rel: 'stylesheet', href: '/styles.css' }),
      script({ type: 'module', src: '/main.js' }),
    ),
    body(
      header(
        a({ href: '/' }, 'Ana sayfa'),
        div({ id: 'search' }),
      ),
      main({ 'data-pagefind-body': '' },
        h1('Merhaba'),
        p('Yalnızca bu bölge dizinlenir.'),
      ),
    ),
  )

3. Pagefind arayüzünü bağlayın

İstemci betiğinizden /pagefind/pagefind-ui.js ve pagefind-ui.css dosyalarını yükleyin (yalnızca bir derleme dizini ürettikten sonra):

async function initSearch() {
  const mount = document.querySelector('#search')
  if (!mount) return

  // Dizin yalnızca `sitelo build` sonrası vardır (varsayılan olarak public/pagefind ile eşitlenir)
  try {
    const probe = await fetch('/pagefind/pagefind-ui.js', { method: 'HEAD' })
    if (!probe.ok) return
  } catch {
    return
  }

  const style = document.createElement('link')
  style.rel = 'stylesheet'
  style.href = '/pagefind/pagefind-ui.css'
  document.head.appendChild(style)

  await new Promise((resolve, reject) => {
    const script = document.createElement('script')
    script.src = '/pagefind/pagefind-ui.js'
    script.onload = resolve
    script.onerror = reject
    document.body.appendChild(script)
  })

  new window.PagefindUI({
    element: '#search',
    showImages: false,
  })
}

initSearch()

4. Derleyin ve eşitlenen paketi yok sayın

sitelo build
# sonra: sitelo preview — ya da public/pagefind kullanan sitelo (dev)
public/pagefind/

Gelişmiş seçenekler (syncPublic, glob, dil, seçiciler, …) bir nesneye gider: pagefind: { syncPublic: false, glob: '**/*.html' }. Tüm arayüz seçenekleri: pagefind.app.

404

dist/404.html için src/404.ht.js oluşturun. Aksi hâlde temiz bir varsayılan üretilir.