Yayına almak23 dk okuma
Static export
Siteyi collage export ile static dosyalara render edin: nelerin yazıldığı, nelerin neden atlandığı, dynamic path'ler ve bir static host'ta yayımlama.
Page'leri request'e bağlı olmayan bir sitenin sunucuya hiç ihtiyacı yoktur. collage export, dosya olabilecek her page'i dist/ içine render eder, static dosyalarınızı yanlarına kopyalar ve sitenin kendi 404.html dosyasını yazar. Bu dizini herhangi bir static host'a koyabilirsiniz.
Siteyi sunan program da budur. Aynı template'ler, data handler'lar ve plugin'lerle render eder. İkinci bir build yoktur, sunucuyla senkron tutmanız gereken bir şey de yoktur. Şu an okuduğunuz sayfalar da bu yolla üretildi.
collage export # -> dist/
collage export -clean # empty dist/ first
collage serve # look at dist/ the way a static host would serve it
Nasıl çalışır
collage export uygulamanızı yüklemez. Yükleyemez de, çünkü uygulamanız sizin kodunuzdur. Bunun yerine programınızı özel bir modda çalıştırır:
go run . -collage-build -out dist # plus -clean when you passed it
| Flag | Varsayılan | Anlamı |
|---|---|---|
-out dir | dist | Dosyaların yazılacağı dizin. |
-clean | kapalı | Önce dizinin mevcut içeriğini siler; yalnızca dizini daha önce bir export oluşturduysa (aşağıya bakın). |
Scaffold edilen main.go bu sözleşmeye collage.Main üzerinden uyar. -collage-build ile çalıştığında uygulamayı her zamanki gibi kurar, ama onu sunmak yerine collage'ın builder'ına verir ve ne olduğunu ekrana yazar. Kendi yazdığınız bir main bunu aşağıdakine benzer bir fonksiyonla yapar. Bu, fonksiyonun collage-docs'taki hâlidir. Hangi page'lerin var olduğu onu ilgilendirmez, çünkü bunu her page kendisi söyler:
func staticBuild(app *collage.App, outDir string, clean bool) error {
report, buildErr := collage.Build(context.Background(), app, collage.BuildOptions{
OutDir: outDir,
Clean: clean,
})
collage.PrintBuildReport(os.Stdout, report, buildErr)
return buildErr
}
collage.Build, hata döndürdüğünde bile bir rapor döndürür. Hata veren bir page diğerlerini durdurmaz ve bütün hatalar report.Errors içinde yer alır.
Dönen hata, bunların hepsinin birleşimidir. main bu durumda sıfırdan farklı bir kodla çıkar, böylece bir page yazılamadığında CI job'ı da başarısız olur. Atlanan page'ler ve uyarılar build'i başarısız kılmaz. Error seviyesindeki bir finding ise kılar; bu durumda da her page yine yazılır.
Bir build de uygulamayı shutdown etmez ve ondan sonra hiçbir şey hizmet vermez. Bu yüzden build bitince çıkan bir program app.Shutdown'ı kendisi çağırır. collage.Main de bunu yapar (bkz. CLI).
Aksi hâlde hiçbir plugin'in Shutdown'ı çalışmaz: bir plugin'in elinde tuttuğu şey hiçbir zaman flush edilmez ve elagoht/jobs gibi bir queue plugin'ine build sırasında verilen iş loglanmadan kaybolur.
main.go'yu yeniden yazarsanız -collage-build, -out ve -clean flag'lerini koruyun. Aksi hâlde collage export işe yarar hiçbir şey yapmaz.
Neler yazılır
Uygulamanın her route'u üç yerden birine düşer: bir dosyaya yazılır, atlanıp raporda adıyla listelenir ya da page olmadığı için hiç ele alınmaz.
collage export'un onunla yaptığı. Page'ler, document'lar, not-found page ve mount edilen dosyalar dosyaya dönüşür; varsayılan olmayan bir locale'deki page o locale'in prefix'i altına yazılır. Strateji tanımlamayan bir page ya da document hiçbir şey çekmiyorsa static, çekiyorsa dynamic sayılır. Dynamic bir page ya da document, WithStaticParams'ı olmayan bir {param} pattern'i, guard'lı bir page ve render'ı {{csrfToken}} içeren bir page atlanır; her biri raporda nedeniyle listelenir. Action'lar, fragment path'ler ve app.Handle handler'ları page değildir, bu yüzden export onları ne yazar ne de raporlar. Dosyalar yazıldıktan sonra redirect'ler denetlenir, onları okuyan bir plugin için header'lar yakalanır ve error seviyesindeki bir finding build'i başarısız kılar; dosyaların hepsi yine yazılmış olur.| Ne | Nereye |
|---|---|
Static ya da incremental bir page: Static(), Incremental(ttl) ya da stratejisi ve data handler'ı olmayan bir page | dist/<path>/index.html; / için dist/index.html |
| Aynı page'in varsayılan olmayan bir locale'deki hâli | Locale'in prefix'i altına: dist/tr/<path>/index.html |
Static ya da incremental bir document: Static(), Incremental(ttl) ya da stratejisi olmayan ve sabit bir body'si olan bir document | Birebir kendi path'ine: /sitemap.xml için dist/sitemap.xml |
| Aynı document'ın varsayılan olmayan bir locale'deki hâli | Locale'in prefix'i altına: dist/tr/sitemap.xml |
AtRoot ile kurulan bir document | Her config'de prefix'siz path'ine: dist/robots.txt |
PrefixDefault açıkken varsayılan locale'deki bir page ya da document | Bunlar da prefix'in altına yazılır: dist/en/<path>/index.html ve dist/en/sitemap.xml. dist/index.html ise /en/ home page'inin bir kopyasıdır ve canonical adresi olarak /en/'i gösterir |
| Not-found page | dist/404.html, ayrıca diğer her locale için dist/<locale>/404.html |
| Mount edilen her static dosya sistemi | Kendi prefix'i altına: /static/app.css için dist/static/app.css |
Bir page, içinde index.html olan bir dizine dönüşür. Çünkü her static host, /about istendiğinde bu dosyayı arar. Bir document ise tam olarak kendi path'ine yazılır, çünkü /robots.txt isteyen bir crawler'ın bir dosya alması gerekir.
Not-found page, app.RegisterNotFoundPage ile register edilen page'dir ve render stratejisine bakılmaz. Bu page neredeyse her zaman Dynamic()'tir, çünkü cache'lemeye hiç değmez. Yine de export'a dahil edilmesi gerekir. Host'lar iç içe bir tr/404.html dosyasını arayıp aramama konusunda farklı davranır, bu yüzden ikisi de yazılır. Not-found page'i olmayan bir site için bu dosya yazılmaz. Bilinmeyen bir URL'de ne gösterileceğine de host karar verir.
Mount edilen asset'ler hem orijinal adlarıyla hem de {{asset}}'in link verdiği content-addressed adlarla (app.3a3663df.css) kopyalanır. Böylece iki tür link de çalışır. Production'da bir CDN'den sunulan ya da kopyalanamayacak kadar büyük bir mount bu kopyalamadan çıkabilir:
app.Mount("/media/", mediaFS, collage.WithoutBuildCopy())
Ayrıntılar için Static asset'ler sayfasına bakın.
Neler atlanır
Bazı page'ler dosya olamaz. Build bunları dışarıda bırakır ve her birini nedeniyle birlikte raporda listeler:
- Dynamic page'ler ve document'lar. Bunlar zaten her request'te render edilmek için vardır.
Dynamic()olarak tanımlananlar da, strateji tanımlamayıp veri çekenler de bu gruptadır: data handler ya da slot resolver render eden bir page, handler'ı olan bir document. Handler'ı her okuyucuya aynı şeyi dönen bir page, export edilebilmesi içinStatic()çağrısını yapmalıdır. - Form içeren page'ler. Render'ı
{{csrfToken}}içeren bir page atlanır. Bir form'un post edeceği bir sunucuya ihtiyacı vardır ve forgery token tek bir okuyucuya aittir. Page bilerekStatic()yapılmış olabilir, yani cache'lenir ve post ettiği action tarafından invalidate edilir. Bu durumda da export edilmez, sunucudan sunulur. Scaffold'daki/featurespage'i buna bir örnektir. - Guard'lı page'ler. Layout zincirinde ya da content fragment'inde bir guard bulunan page, stratejisi ne olursa olsun
collage.ErrGuardedile atlanır. Export request olmadan render eder, dolayısıyla guard'a sorulacak bir okuyucu yoktur; static host'taki bir dosya ise herkese sunulur. Çalışan sunucu page'i guard'ıyla birlikte sunmaya devam eder. WithStaticParams'ı olmayan bir{param}pattern'i. Hangi slug'ların var olduğunu bir şey söylemeden/blog/{slug}yazılamaz vecollage.ErrDynamicPathUnresolvedile atlanır. Aşağıya bakın.
Path olmadan register edilen error page'ler hiç listelenmez, çünkü bunlar birer URL değildir.
Bazı şeyler page olmadığı için ne export edilir ne de raporda görünür: action'lar, app.Handle ile mount edilen handler'lar ve middleware'ler.
Export request olmadan render eder. Bu yüzden yazdığı dosyalar için hiçbir middleware çalışmaz ve collage.Vary hiç çağrılmaz. Her page, hiçbir tercihi olmayan bir request'in alacağı hâliyle yazılır. Ardından header'ları yakalayan request'ler middleware'den geçer, ama onların render ettiği hiçbir şey yazılmaz.
Neler için uyarı verilir
WithCacheParams ile hangi query parametrelerini okuduğunu bildiren bir page, her parametre değeri için farklı render edilir. Oysa bir dosyanın query string'i yoktur. Static host, /blog?page=2 isteğine /blog dosyasıyla cevap verir. Page query olmadan yazılır ve rapor bunu açıkça belirtir. Böylece sayfalanmış bir arşiv çalışıyormuş gibi görünmez. WithCacheParams kullanan bir document için de, örneğin sayfalanmış bir feed için, aynı şekilde uyarı verilir.
Sayfalamanın export'ta da çalışması gerekiyorsa sayfa numarasını path'e koyun, örneğin /blog/page/{n}. Ardından bu page'leri WithStaticParams ile listeleyin. Pagination bölümü iki page'i ve link'leri kuran library'yi gösterir.
Neler başarısız olur
Aşağıdakiler hatadır. Page yazılmaz, build bunu raporlar ve sıfırdan farklı bir kodla çıkar.
- Degraded bir render. Bir fragment'i hata veren page,
collage.ErrDegradedRenderile reddedilir ve hata o fragment'in adını içerir. Sunucudan sunulan bir page'de fragment hata verirse page gösterilir ama hiçbir zaman cache'lenmez. Bir dosyanın ise kendini toparlayacağı bir TTL'i yoktur, yani o hatayı bir sonraki export'a kadar taşır. Sidebar'ı eksik bir page, hiç page olmamasından iyiyseBuildOptions.AllowDegradedayarını açın. - Başarısız olan bir
collage.Cachedçekme işlemi. Export hiçbir zaman stale veri kullanmaz. Sunulan bir page'e, değer yenilenirken stale hali verilebilir. Ama bir dosyanın bekleyeceği bir yenileme yoktur.collage.Buildupstream'i bekler ve upstream başarısız olursa page yazılmaz. - Boş bir render (
collage.ErrEmptyRender) ve boş bir document (collage.ErrEmptyDocumentBody). Sıfır byte'lık birindex.htmlhiçbir zaman yazılmaz. - Bir page'de oluşan panic (
collage.ErrBuildPanic). Panic recover edilir ve o page'e ait hata olarak kaydedilir. Build'in geri kalanı devam eder. - Form içeren bir not-found page (
collage.ErrUnresolvedToken). Bunun nedeni, static host'un bu page'e bir dosya olarak ihtiyaç duymasıdır. - Aynı output path'e düşen iki route (
collage.ErrOutputPathCollision): iki page, iki document ya da bir page ile bir document. Sebep yalnızca sondaki slash ile ayrılan iki pattern, aynı değerleri iki kez listeleyen birWithStaticParamsya da bir page'inindex.html'ine düşen bir document olabilir. İki locale'deki tek bir pattern bu duruma girmez, çünkü her locale kendi prefix'i altına yazılır. BuildOutDir'e dokunmadan durur: hiçbir şey temizlenmez ya da yazılmaz,404.htmlya da mount edilen dosya kopyalanmaz veBuildFinishedHookçağrılmaz. Document'larınWithStaticParams'ı hiçbir page render edilmeden önce çalışır, bu yüzden kontrol onları da kapsar. Yalnızca büyük/küçük harfle ayrılan path'ler de çakışır:/Aboutile/aboutmacOS ve Windows'ta tek dosyadır, bu yüzden Linux'ta build olan bir site bir dizüstü bilgisayarda da build olur. - Aynı path'ten iki redirect (
collage.ErrDuplicateRedirect)./oldile/old/ya da/blog/{slug}ile/blog/{x}buna örnektir: page'lerden, document'lardan ya da bir plugin'den gelsinler, router ikisini tek bir redirect sayar. Static bir host'ta hangisinin geçerli olacağına host'un kendi önceliği karar verirdi. İkisinden birini kaldırın. - Yazılmış bir dosyanın üstüne düşen redirect (
collage.ErrRedirectShadowsFile).about/index.htmlyanındaki/aboutya da/about/,docs/intro/index.htmlyanındaki/docs/{rest...}buna örnektir./{slug}gibi placeholder'lı birFrom,404.htmldahil o derinlikteki her dosyayla eşleşir. Pattern'i daraltın ya da page'i kaldırın.
İki redirect kontrolü de, redirect'leri okuyacak bir plugin olsun olmasın her build'de çalışır ve dosyalar yine yazılır.
Error seviyesindeki bir finding de build'i collage.ErrBuildFindings ile başarısız kılar, ama farklı bir şekilde: page'ler her durumda yazılır ve finding'ler raporda yer alır. Bkz. Raporu okumak.
Dinamik path'ler: WithStaticParams
/blog/{slug} adresindeki bir page, birçok URL'si olan tek bir page'dir. Page bu URL'leri WithStaticParams ile kendisi listeler. Verdiğiniz fonksiyon, her dosya için placeholder değerlerinden oluşan bir map döner:
WithStaticParams(fn collage.StaticParamsFunc)
type StaticParamsFunc func(ctx context.Context, locale string) ([]map[string]string, error)
Page'in path'i olan her locale için bir kez çağrılır. Bu dokümantasyon, her dilde /docs/{slug} adresindeki tek bir page'dir: doc. Bu page, orijinalde dokümantasyonun bütün sayfalarını, bir çeviride ise o ana kadar çevrilmiş her sayfayı listeler:
builder := collage.NewPage("doc").
WithLayouts(layouts.Layout(app, docs)).
WithContent(content).
Static().
WithStaticParams(func(_ context.Context, locale string) ([]map[string]string, error) {
set, err := docs()
if err != nil {
return nil, err
}
loaded := set.Site(locale)
if loaded == nil {
return nil, nil
}
params := make([]map[string]string, 0, len(loaded.Pages()))
for _, page := range loaded.Pages() {
params = append(params, map[string]string{"slug": page.Slug})
}
return params, nil
})
- Path'i build yapar. Her map, locale'in pattern'ini adıyla kurulan bir link'in yapacağı gibi doldurur. Dosya da locale'in prefix'i altına yazılır:
dist/docs/caching/index.html,dist/tr/docs/caching/index.html. URL'de escape edilmesi gereken bir değer decode edilmiş path'ine yazılır (h%C3%A9llodeğil,héllo). Static host, o değer için gelen bir request'i orada arar. - Data handler'lar bu değerleri görür.
rc.Param("slug"), o path'e gelen canlı bir request'teki değerin aynısını döner. - Map pattern'i tam olarak doldurmalıdır. Eksik bir ad ya da pattern'de olmayan bir ad, yalnızca o dosyayı
collage.ErrRouteParamsile başarısız kılar. Geri kalanlar build edilir. Tek bir{param}'ın değerindeki bir/da aynı sonucu doğurur. Path olan bir değer bir{rest...}'te yer almalıdır; böylece../aboutgibi bir slug (örneğin bir CMS'ten gelen) kendi page'ini output dizininin içindeki başka bir page'in üzerine yazamaz. Ters bölü ya da NUL içeren bir değer de aynı sonucu doğurur: Windows'ta ters bölü bir ayırıcıdır ve/blog/{slug}altındax\..\..\aboutbaşka bir page'in dosyasına ulaşırdı. Build her yerde aynı davransın diye her platformda reddedilir. - Bir hata ya da panic, o page'in o locale'ini başarısız kılar ve raporda adıyla yer alır. Panic
collage.ErrBuildPanicolarak raporlanır. Hiç map dönülmezse hiçbir şey yazılmaz. Bu bir hata sayılmaz. - Onu yalnızca build çağırır. Çalışan bir sunucu, listelenmiş olsun olmasın, pattern'in eşleştiği her değere cevap verir.
- Page yine de cache'lenebilir olmalıdır. Data handler'ı olan bir page, aksini söylemedikçe dynamic'tir. Bu yüzden export edilecek bir page, yukarıdaki
docgibiStatic()ya daIncremental(ttl)çağrısını yapar.
Document'lar da aynı WithStaticParams'ı kullanır: /feeds/{category}/rss.xml adresindeki bir feed kendi kategorilerini listeler. Bkz. Document'lar.
WithStaticParams'ın ürettiği her path, dosyası yazılmadan önce kontrol edilir. Output dizininin dışına çıkan bir path (/../../etc) collage.ErrPathEscapesOutDir ile reddedilir. Dizinin dışına götüren bir symlink üzerinden yazma da aynı şekilde reddedilir. Bu ret yalnızca o path'i başarısız kılar, build'in geri kalanını etkilemez. Diğer page'ler yine render edilip yazılır ve hata raporda yer alır.
Pagination
Pagination bir plugin değil, bir library'dir: elagoht/paginate için register edecek ya da yapılandıracak bir şey yoktur. Bir data handler ve bir template onu kullanır. go get github.com/Elagoht/collage-paginate ile eklersiniz.
paginate.New(total, perPage, current), Current, Last, Offset, Limit, Prev, Next alanlarına ve sayfa numaralarından oluşan bir Window'a sahip bir Pager döner (1 … 4 5 [6] 7 8 … 20):
p := paginate.New(total, perPage, current)
// p.Current, p.Last, p.Offset, p.Limit, p.Prev, p.Next, p.Window
rows := db.Query("… LIMIT ? OFFSET ?", p.Limit, p.Offset) // fetch only the page
page := paginate.Items(all, p) // or slice a list you already have
current,[1, Last]aralığına çekilir.Newasla başarısız olmaz. Bu yüzden bir sayfanın aralığın dışında kaldığına karar vermek handler'ın işidir.- Boş bir listing tek bir boş sayfadır.
Last1 olur veItemsboş, nil olmayan bir slice döner. - Window, ilk ve son sayfayı, bir de geçerli sayfanın iki yanındaki ikişer sayfayı tutar.
p.WithWindow(edges, around)bunu değiştirir. - 1'den küçük
perPagepanic eder. Bu bir programlama hatasıdır, girdi değildir.
Static export'un yazabileceği bir listing'i sayfalamak
Bir page'in locale başına tek bir path pattern'i vardır. Bu yüzden tek bir page hem /blog hem de /blog/page/{n} adresine cevap veremez. Sayfalanmış bir listing, fragment'ini paylaşan iki page'dir. Biri 1. sayfayı listing'in kendi path'inde sunar, diğeri geri kalanını sunar.
func listing(ctx context.Context, rc *collage.RenderContext) (BlogList, []string, error) {
total, err := posts.Count(ctx, rc.Locale) // the same count StaticParams uses
if err != nil {
return BlogList{}, nil, err
}
last := paginate.New(total, perPage, 1).Last
n := 1
if rc.Param("n") != "" {
if n, err = paginate.FromPath(rc, last); err != nil {
return BlogList{}, nil, err // wraps collage.ErrNotFound: a 404
}
}
p := paginate.New(total, perPage, n)
links, err := paginate.PathNamed(rc, "blog", "blog-page")
if err != nil {
return BlogList{}, nil, err
}
items, err := posts.List(ctx, p.Limit, p.Offset)
return BlogList{Posts: items, Pager: p, Links: links.For(p)}, []string{"posts"}, err
}
list := func(name string) *collage.Fragment {
return collage.NewFragment(name, "blog/list.html").WithData(collage.LoadTagged(listing)).Required().Build()
}
app.RegisterPage(collage.NewPage("blog").
WithContent(list("blog-list")).
WithPath("en", "/blog").
Static(). // a page with a data handler is dynamic unless it says otherwise
Build())
app.RegisterPage(collage.NewPage("blog-page").
WithContent(list("blog-page-list")).
WithPath("en", "/blog/page/{n}").
WithStaticParams(paginate.StaticParams(posts.Count, perPage)).
Static().
Build())
- İki page de
Static()olur (ya daIncremental). Data handler'ı olan bir page varsayılan olarak dynamic'tir ve static export dynamic page'leri atlar. StaticParams, 2…Last sayfalarını listeler. Bu liste export için ve sitemap'in okuduğuPageURLsiçin kullanılır. 1. sayfa listelenmez, çünkü o/blogadresidir. Ona handler'ın kullandığı sayıyı verin. İkisi uyuşmazsa export, handler'ın 404 ile cevapladığı sayfaları yazar.- Her sayfanın tek bir yazımı vardır.
FromPath,StaticParams'ın yazdığı{n}path parametresini okur ve yalnızca kanonik biçimde yazılmış, 2 ilelastarasındaki bir sayfa numarasını kabul eder./blog/page/1,/blog/page/02, bir işaret, ASCII rakam olmayan her şey ve aralığın dışındaki her sayı bulunamaz. Hatacollage.ErrNotFound'ı sarar. Bu yüzden Required bir fragment, page'in not-found page'ini 404 ile render eder. PathNamed, link'leri page'lerin adlarıyla kurar. Böylece locale prefix'leri doğru çıkar (/tr/blog/page/2). Request'in diğer path parametreleri iki adrese de girer. Bu yüzden/tag/{tag}ile/tag/{tag}/page/{n}, kendi tag'i içinde link verir. İki adı da baştan kontrol eder, yani yanlış yazılmış bir ad boş bir link yerine hata olur. Bir tag listing'inin export'u için static param'ları kendiniz yazın: her tag ve her 2…paginate.New(count(t), perPage, 1).Lastsayfası için bir{"tag": t, "n": k}. Locale yoksapaginate.Path("/blog", "/blog/page/{n}")aynı işi sabit path'lerle yapar.
Query ile sayfalamak
Yalnızca bir sunucunun cevaplayabileceği bir listing, örneğin bir arama, query string ile sayfalanır:
n := paginate.FromQuery(rc, "page", last) // anything invalid is page 1
links := paginate.Query(rc, "page").For(paginate.New(total, perPage, n))
- Request'in diğer parametreleri kalır. 1. sayfa key'i düşürür, yani adresi key'siz olandır.
- Cache'lenen bir page, key'i cache parametreleri arasında belirtmelidir:
WithCacheParams("q", "page"). Bu olmazsa bütün sayfalar tek bir cache entry'sini paylaşır. - Static export bu page'leri sunamaz. Static host,
/search?page=2isteğine/searchdosyasıyla cevap verir. Export de query parametresi okuyan page'ler için uyarı verir.
Template'te
Links düz bir struct'tır. Bu yüzden fragment'in data'sına girer ve template checker .Links.Next ile diğerlerini görür:
<nav class="pager" aria-label="Pages">
{{with .Links.Prev}}<a href="{{.}}" rel="prev">Previous</a>{{end}}
{{range .Links.Window}}
{{if .Gap}}<span>…</span>
{{else if .Current}}<span aria-current="page">{{.N}}</span>
{{else}}<a href="{{.URL}}">{{.N}}</a>{{end}}
{{end}}
{{with .Links.Next}}<a href="{{.}}" rel="next">Next</a>{{end}}
</nav>
rel="prev" ve rel="next" değerlerini head'e koymak için bunları data handler'dan hoist edin. Layout, {{hoist "head"}} yazdığı yere yerleştirir:
if l := links.For(p); l.Next != "" {
rc.Hoist("head", "pager-next", template.HTML(`<link rel="next" href="`+template.HTMLEscapeString(l.Next)+`">`))
}
Sayfa toplamları bilinmelidir. Cursor tabanlı sayfalama ve sonsuz kaydırma kapsam dışındadır.
Build seçenekleri
| Alan | Anlamı |
|---|---|
OutDir | Dosyaların yazılacağı yer. Zorunludur. |
Clean | Önce OutDir'in içeriğini siler (dizinin kendisini değil); yalnızca dizini daha önce bir build oluşturduysa (aşağıda). |
Locales | Yalnızca bu locale'leri build eder. Boş bırakılırsa page'lerin tanımladığı bütün locale'ler build edilir. |
Concurrency | Aynı anda kaç page'in render edilip yazılacağı. 0 ya da 1 verilirse page'ler tek tek işlenir. Rapor her iki durumda da aynı sıradadır. |
AllowDegraded | Render sırasında bir fragment'i hata veren page'leri de yazar. |
Builder, dosya sisteminin köküne çıkan bir OutDir'i, Clean olsun olmasın, reddeder (collage.ErrDangerousOutDir).
Güvenlik
-clean (BuildOptions.Clean) yalnızca bu programın bir build'inin yaptığını siler. Bir build, oluşturduğu ya da boş bulduğu bir output dizinine .collage-export dosyasını bırakır ve Clean bir dizini yalnızca bu işaret orada varsa boşaltır (işaretin kendisi kalır). Aksi hâlde hiçbir şey silinmeden ya da yazılmadan collage.ErrDangerousOutDir ile başarısız olur:
- projenin kendi dizini ve üstündeki her dizin (
-out .. -clean); - bir repository'nin kökü, çalışma dizini ya da module kökü;
- işareti olmayan, boş olmayan bir dizin, örneğin
static/(-out static -clean).
İşaretin olmadığı bir dönemde export edilmiş bir dist/ için bir kez tek komut gerekir:
touch dist/.collage-export
Bundan sonra collage export -clean onu eskisi gibi boşaltır. CI runner'ı gibi taze bir dizin işaretini ilk build'den alır.
Export'ta plugin'ler
Export, sunucuyla aynı durumda render eder. Build önce uygulamayı başlatır ve page'ler listelenmeden önce her plugin'in Init'ini çalıştırır. Böylece bir plugin'in register ettiği document de, bir plugin'in yüklediği veriye dayanan WithStaticParams da build edilir ve plugin'ler aynı config'i okur.
OnBeforeRender, OnAfterRender ve OnDocumentRendered her page ve document için tetiklenir. Yani bir minifier ya da structured data plugin'i sunulan bir page'e ne yapıyorsa dosyaya da onu yapar. OnBuildFinished, her dosya yazıldıktan sonra bir kez çalışır. Build'i bir bütün olarak denetleyen plugin'ler içindir.
Böyle bir plugin register edilmişse build önce App.Handler() üzerinden her dosyanın header'larını yakalar Bunlar request'tir: middleware ve OnRequest onları görür, page de OnBeforeRender ve OnAfterRender ile yeniden render edilir. Bu sırada ev.Static false'tur. Trafiği sayan ya da sınırlayan bir plugin de, bir render hook'undan dosya yazan bir plugin de collage.IsCapture(ctx) true olduğunda bu request'leri atlar. Bkz. Plugin kullanmak.
Raporu okumak
collage.PrintBuildReport, build'in ne yaptığını yazdırır. collage new ile scaffold edilen projede çıktı şöyle görünür:
✓ 8 files written
dist/404.html
dist/index.html
dist/static/app.3a3663df973f06fb.js
dist/static/app.7050c2518057f5c5.css
dist/static/app.css
dist/static/app.js
dist/static/favicon.936907e03c8c09ad.svg
dist/static/favicon.svg
▲ 3 skipped
hello page uses the dynamic render strategy, which cannot be built statically
features (en) page carries {{csrfToken}}; a form needs a server to submit to, so it is served rather than exported
health document uses the dynamic render strategy, which cannot be built statically
8 written · 3 skipped · 0 failed · 2.5ms
Yazılan dosyalar on taneyi geçince özetlenir. Üç yüz dosya yazan bir build, atladığı tek page'i bu listenin altına gömmemelidir. Atlananlar, uyarılar ve hatalar hiçbir zaman kısaltılmaz. Son satırda bütün sayılar yer alır ve satır, aralarındaki en kötü duruma göre renklendirilir. Atlananlar route olarak sayılır, yani page'ler ve document'lar birlikte sayılır. Bu yüzden çıktıda 3 pages skipped değil, 3 skipped yazar.
Raporu kodda kullanmak için report.Skipped, report.Warnings, report.Findings ve report.Errors alanlarını kendiniz okuyun. Her atlama bir collage.SkipRecord'dur. Bu kayıtta route'un adı Name, Locale'i ve okuyan kişi için bir Reason bulunur. errors.Is ile eşleştirebileceğiniz bir Err de bulunur. Bkz. Hatalar. Test yazmak sayfası bunu bir teste dönüştürür.
Renkler ve ✓ ▲ ◆ ✗ işaretleri yalnızca terminalde görünür. NO_COLOR tanımlıysa terminalde de görünmez. CI log'larında bu işaretler düz ASCII olarak yazılır (+ ! * x).
Finding'ler
Çıktıyı denetleyen bir plugin, örneğin elagoht/htmlcheck, bulduklarını finding olarak raporlar. rapor bunları ilgili oldukları page'in altında, önce error'lar gelecek şekilde listeler:
◆ 2 findings
/about
error img-alt <img src="/team.jpg"> has no alt elagoht/htmlcheck
warning heading-order <h4> follows <h2> elagoht/htmlcheck
Bir warning hiçbir şeyi durdurmaz. Error seviyesindeki bir finding build'i collage.ErrBuildFindings ile başarısız kılar. Böylece main sıfırdan farklı bir kodla çıkar ve CI başarısız olur, ama her page yine yazılır. Finding'ler report.Findings içindedir; her biri bir collage.Finding'dir. Bir plugin'in finding'i nasıl raporladığı Plugin yazmak sayfasında anlatılır.
Header yakalama da bulduklarını burada raporlar. Bunlar build'in geneline ait uyarılardır ve build'i asla başarısız kılmaz: unstable-header, capture-status, capture-failed, capture-dev-mode ve capture-personal. Bkz. Header'lar ve redirect'ler.
Örnek: bir blogu export etmek
Export'a en uygun site türlerinden biri blogdur: yazılar okuyucuya göre değil, biri yayımladığında değişir. Bu blogda bir home page, bir /blog listesi, her yazı için bir page, her tag için bir page, bir arama page'i ve bir iletişim form'u var. Yanlarında da Document'lar sayfasındaki feed ve sitemap duruyor. Export'un ne yapacağını belirleyen route'lar:
app.RegisterPage(collage.NewPage("blog-post").
WithLayouts(layout).
WithContent(post).
WithPath("en", "/blog/{slug}").
WithStaticParams(func(ctx context.Context, _ string) ([]map[string]string, error) {
slugs, err := posts.Slugs(ctx)
if err != nil {
return nil, err
}
params := make([]map[string]string, 0, len(slugs))
for _, slug := range slugs {
params = append(params, map[string]string{"slug": slug})
}
return params, nil
}).
Static().
Build())
app.RegisterPage(collage.NewPage("tag").
WithLayouts(layout).
WithContent(tagList).
WithPath("en", "/tag/{tag}").
Static(). // no WithStaticParams yet
Build())
app.RegisterPage(collage.NewPage("search").
WithLayouts(layout).
WithContent(results). // reads the q query parameter
WithPath("en", "/search").
WithCacheParams("q").
Static().
Build())
app.RegisterPage(collage.NewPage("contact").
WithLayouts(layout).
WithContent(contactForm). // its <form> carries {{csrfToken}}
WithPath("en", "/contact").
WithAction("POST", sendMessage).
Build())
app.RegisterDocument(FeedDocument(app, posts))
app.RegisterDocument(SitemapDocument(app, posts))
Üç yazı, bir not-found page ve layout'un {{asset}} ile link verdiği bir stylesheet ile collage export -clean şunu yazdırır:
✓ 11 files written
dist/404.html
dist/blog/hello-world/index.html
dist/blog/index.html
dist/blog/static-files/index.html
dist/blog/tags-and-feeds/index.html
dist/feed.xml
dist/index.html
dist/search/index.html
dist/sitemap.xml
dist/static/app.2708d73bf31c36cd.css
… and 1 more
▲ 2 skipped
tag (en) collage: a path pattern with a {param} needs WithStaticParams to be built
contact (en) page carries {{csrfToken}}; a form needs a server to submit to, so it is served rather than exported
▲ 1 warning
search reads the query parameters q, and a static file has no query string: only the version without them was written
11 written · 2 skipped · 0 failed · 1 warning · 5.8ms
Satır satır:
- Her yazı bir dosyadır.
WithStaticParamsüç slug döndürdü, bu yüzdendist/blog/altında üçindex.htmlvar. Raporun adını verdiği on dosyadan sonra gelen on birinci dosya, hash'li kopyasının yanındakidist/static/app.css'tir. - Feed ve sitemap yazılır. Feed
Static(), sitemap iseIncremental(time.Hour)olduğu için ikisi de birebir kendi path'lerine dosya olarak yazılır. Strateji tanımlanmasaydı handler'ları onları dynamic yapardı ve atlanırlardı. - Tag page'leri yok.
/tag/{tag}'in bir tag listesi olmadığı içincollage.ErrDynamicPathUnresolvedile atlanır. Her tag için bir{"tag": t}döndüren birWithStaticParamsbu page'leri yazar. - İletişim page'i yok. Page render edildi ve render'ı form'un token'ını içerdiği için yazılmadı; atlamanın
Err'icollage.ErrUnresolvedToken'dır. Bir form'un post edeceği bir sunucuya ihtiyacı vardır.collage serve, çoğu static host gibi,/contactisteğine404.htmlile cevap verir. - Arama page'i var, ama arama yapmaz. Bir dosyanın query string'i yoktur. Bu yüzden
/search?q=feedsisteği de/searchile aynıdist/search/index.htmldosyasını alır: page'in query olmadan render edilmiş hâlini. Uyarının söylediği budur.
Bunların hiçbiri build'i başarısız kılmaz, dolayısıyla program sıfır koduyla çıkar. Arama page'inin export'ta hiç yer almaması gerekiyorsa onu Dynamic() olarak tanımlayın: o zaman boş yazılmak yerine atlanır ve raporda adıyla listelenir. Arama kutusu ve iletişim form'u yalnızca bir sunucuda çalışır; bkz. Deployment.
Göz atmak: collage serve
dist/index.html'i tarayıcıda doğrudan açmak işe yaramaz. Bir file:// sayfasının kökü yoktur, bu yüzden bütün mutlak link'ler ve stylesheet'ler kırılır. collage serve, export çıktısını bir static host'un sunduğu şekilde sunar:
collage serve # http://localhost:4000
collage serve -dir public -port 8000
/aboutisteğineabout/index.htmlile cevap verilir.index.htmliçermeyen bir dizin 404 döner. Dizin listelemesi yapılmaz.- Bilinmeyen bir path, 404 status'uyla
404.htmldöner. - Hiçbir şey cache'lenmez. Yeniden export alıp sayfayı yenilediğinizde yeni çıktıyı görürsünüz.
Flag'leri -dir (varsayılan dist), -host (varsayılan localhost) ve -port'tur. -port'un varsayılanı 4000'dir, 6060 değildir. Böylece ikisini karşılaştırırken collage dev ile yan yana çalışabilir. collage serve yalnızca dosya sunar, projenizi çalıştırmaz.
Hosting
Çıktı, mutlak link'ler içeren düz dosyalardan oluşur. Bu yüzden herhangi bir static host onu sunabilir. Hangi host'u kullanırsanız kullanın üç şeyi kontrol edin:
- Site, domain'in kökünde olmalıdır. Link'ler ve asset URL'leri
/ile başlar ve collage'ın bir base path ayarı yoktur. Bu yüzden bir alt path altında yayımlanan bir sitenin link'leri kırılır.user.github.io/project/adresindeki bir GitHub project page'i buna örnektir. Custom bir domain kullanın ya da siteye kendi domain'ini veren bir host seçin. 404.htmlköktedir. Çoğu host bu dosyayı hiçbir config gerekmeden bu adla bulur.TrailingSlashaçık olmalıdır. Bir page<path>/index.htmlolarak yazılır. Host onu/about/adresinde sunar ve/about'u oraya redirect eder. Bu ayar açıkken collage'ın ürettiği her link doğrudan host'un cevap verdiği adres olur, oraya giden bir redirect olmaz.
Header'lar ve redirect'ler
Bir sunucu her page ile birlikte header gönderir ve redirect'leri kendisi cevaplar. Static bir host ise kendi config dosyalarında ne yazıyorsa onu gönderir: Netlify'ın _headers ve _redirects dosyaları, Vercel'in vercel.json'ı gibi. build, sunucunun söyleyeceklerini de taşır; bu dosyaları bir plugin yazar. Collage bunların hiçbirini kendisi yazmaz.
Header'lar yakalanır.BuildFinishedHook implement eden bir plugin register edilmişse build, yazdığı her dosyanın path'ini uygulamanın kendi handler'ına iki kez sorar. Bu, process içinde ve ağ olmadan olur. Gelen cevap dosyaya BuiltFile.Status ve BuiltFile.Headers olarak kaydedilir. Böyle bir plugin yoksa hiçbir şey sorulmaz.
Request'ler Config.BaseURL'in host'unu taşır ve scheme'i https ise HTTPS üzerinden gelir. Böylece yalnızca HTTPS'te gönderilen Strict-Transport-Security gibi bir header da yakalanır. Middleware'lerinizin ve plugin'lerinizin set ettiği her şey (Cache-Control, Content-Security-Policy, X-Frame-Options) yeniden tanımlanmadan gelir. Dışarıda kalanlar:
- dosyaya değil tek bir response'a ait header'lar:
Date,ETag,Last-Modified,Content-Length,Set-Cookie,Vary,Content-Encoding,Transfer-Encoding,Connection,AgeveX-Collage-Render-Time; - iki cevap arasında değeri değişen bir header, örneğin bir CSP nonce'ı. Bir dosya her okuyucu için yenisini taşıyamaz;
- build'in kendisinin ürettiği
404.htmlpage'leri.BuiltFile.Capturedbunlar için false'tur. Build'in sorduğu her dosya için ise true'dur; yakalaması başarısız olan bir dosya da buna dahildir ve onunStatus'u 0 kalır. Home page'in kökteki kopyası sorulmaz, çünkü uygulama/'yi redirect eder. Ama bu kopya,Captureddahil, home page'in yakalama sonucunu taşır.
Yakalamanın bulduğu şeyler build'in finding'lerinde uyarı olarak raporlanır:
| Kural | Anlamı |
|---|---|
unstable-header | Bir header, iki cevap arasında değiştiği için dışarıda bırakıldı. Her header adı için bir kez, path sayısıyla birlikte verilir. |
capture-status | Bir dosya 2xx dışında bir status ile ya da iki farklı status ile cevaplandı. |
capture-failed | Bir path cevaplanmadı (her request'in bir süre sınırı vardır) ya da yakalama hiç çalışmadı. |
capture-dev-mode | Build development modunda çalıştı. Bu moddaki header'lar (Cache-Control: no-store) deploy edilecek header'lar değildir. |
capture-personal | Bazı page'ler, cevaplar arasında değişen bir header'ın yanında Cache-Controlprivate ya da no-store ile cevaplandı. O header dışarıda bırakıldığı için dosya artık kişiye özel değildir; Cache-Control yalnızca host'un onu cache'lemesini engeller. Bir PersonaliseHook buna yol açamaz ve bir development build'i bunu vermez. |
Personal set eden bir PersonaliseHook, örneğin elagoht/secure'un CSP nonce'ı, yakalamanın private, no-store ile cevaplanmasına yol açmaz. Yakalama hook'u çalıştırır ama Personal'ı bir kenara koyar. Böylece export edilen bir nonce page'i, strateji'sinin verdiği Cache-Control'ü alır (incremental bir page için public, max-age=…). Okuyucunun request'i değişmez. Bir development build'i capture-personal vermez: onun no-store'u zaten capture-dev-mode'un uyardığı şeydir.
Middleware yakalama request'lerini görür. Trafiği sayan ya da sınırlayan bir middleware (analytics, bir rate limiter, bir ban listesi), collage.IsCapture(r.Context()) true olduğunda request'i dokunmadan geçirir. Header set eden middleware ise onu atlamamalıdır: onun set ettiği şey, deploy edilen dosyanın hangi header'larla sunulacağıdır.
Redirect'ler build hook'una ulaşır.BuildFinishedEvent.Redirects, sitenin tanımladığı her redirect'i status'u ve nereden geldiğiyle birlikte taşır: her page'in WithRedirect ve WithPermanentRedirect redirect'leri, her document'ınkiler ve collage.RedirectSource implement eden her plugin'in kuralları. Bunlardan ikisi aynı path'ten geliyorsa ya da biri yazılmış bir dosyanın üstüne düşüyorsa build başarısız olur.
Host'un dosyalarını elagoht/deploy yazar. Host'u belirtin; plugin yakalanan header'ları ve redirect'leri o host'un okuduğu dosyalara dönüştürür ve host'un taşıyamadığı her şey için uyarı verir:
{ "elagoht/deploy": { "target": "netlify" } }
target | Yazdıkları |
|---|---|
netlify | _headers ve _redirects |
cloudflare | _headers ve _redirects |
vercel | vercel.json |
github-pages | her redirect için bir meta-refresh page'i ve .nojekyll; header yok |
GitHub Pages
Bu site, testleri çalıştıran, export alan ve dist/'i yükleyen bir workflow ile yayımlanır:
name: pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.26'
- run: go test ./...
- run: go run . -collage-build -out dist -clean
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with:
path: dist
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4
Export adımı programı collage export üzerinden değil, doğrudan çalıştırır. Böylece runner'a collage CLI'ı kurmanız gerekmez. Repository'nin Pages kaynağını GitHub Actions olarak ayarlayın. user.github.io repository'niz değilse ona custom bir domain de verin.
GitHub Pages custom header kabul etmez. elagoht/deploy'un github-pages target'ı ile her sabit redirect, tarayıcıyı yeni adrese gönderen bir page'e dönüşür. Uyarılar da kaç header'ın kaybolduğunu söyler.
Cloudflare Pages
CI'da export'u aynı şekilde alın ve dizini Wrangler ile yükleyin:
go run . -collage-build -out dist -clean
npx wrangler pages deploy dist --project-name mysite
Kökte bir 404.html varsa Cloudflare Pages bilinmeyen path'ler için onu sunar. Sitenin bir not-found page'i varsa export bu dosyayı her zaman yazar. elagoht/deploy'un cloudflare target'ı onun _headers ve _redirects dosyalarını yazar.
Diğerleri
Netlify, CloudFront arkasındaki S3 ya da bir nginx dizini fark etmez. Hepsinin ihtiyacı yalnızca dist/'in içeriğidir. Host bunu kendiliğinden yapmıyorsa 404.html'i error page olarak ayarlamanız da gerekir. elagoht/deploy'un bir netlify target'ı, bir de vercel target'ı vardır. vercel'in yazdığı vercel.json yalnızca output dizini proje olarak deploy edildiğinde (vercel deploy dist) okunur. Site form'lara, preview'lara ya da her request'te render edilen page'lere ihtiyaç duyuyorsa bir sunucuya ihtiyacı vardır. Bkz. Deployment.