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
FlagVarsayılanAnlamı
-out dirdistDosyaların yazılacağı dizin.
-cleankapalıÖ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 her route türüyle ne yaptığı. dist içine yazılanlar: static ya da incremental bir page path/index.html olarak; param pattern'li bir page, StaticParams'ın döndürdüğü her map için bir index.html olarak; static bir document birebir kendi path'ine; not-found page her locale için 404.html olarak; mount edilen dosyalar kendi adlarıyla ve link verilen hash'li adlarla; PrefixDefault açıkken /en/ home page'inin kopyası index.html olarak. Atlanıp raporda adı geçenler: dynamic bir page ya da document, StaticParams'ı olmayan bir param pattern'i, guard'lı bir page ve render'ı csrfToken içeren bir page. Action'lar, bir page'in fragment path'leri ve app.Handle handler'ları page değildir: export edilmez, raporda da yer almaz. Her dosya yazıldıktan sonra redirect'ler birbirine ve dosyalara karşı denetlenir; BuildFinishedHook plugin'i varsa header'lar yakalanır ve OnBuildFinished çalışır; error seviyesindeki bir finding build'i ErrBuildFindings ile başarısız kılar.collage exportroutedist/ içindeStatic/Incremental page<path>/index.html{param} + StaticParamsmap başına bir index.htmlstatic documentbirebir kendi path'inot-found pageher locale için 404.htmlmount edilen dosyalaraynı adlar, artı linkverilen hash'li adlarhome, PrefixDefaultindex.html: /en/ kopyasıDynamic page/document{param}, StaticParams yokguard'lı page{{csrfToken}} içeren pageatlanırraporda nedenive bir Err ilelisteleniraction, fragment pathapp.Handleexport edilmez,raporda yer almazher dosya yazıldıktan sonra:redirect'ler birbirine ve dosyalara karşı denetlenirBuildFinishedHook plugin'iyle: header'lar yakalanır,ardından OnBuildFinished çalışır;error seviyesindeki finding build'i başarısız kılar
Her route türü ve 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.
NeNereye
Static ya da incremental bir page: Static(), Incremental(ttl) ya da stratejisi ve data handler'ı olmayan bir pagedist/<path>/index.html; / için dist/index.html
Aynı page'in varsayılan olmayan bir locale'deki hâliLocale'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 documentBirebir kendi path'ine: /sitemap.xml için dist/sitemap.xml
Aynı document'ın varsayılan olmayan bir locale'deki hâliLocale'in prefix'i altına: dist/tr/sitemap.xml
AtRoot ile kurulan bir documentHer config'de prefix'siz path'ine: dist/robots.txt
PrefixDefault açıkken varsayılan locale'deki bir page ya da documentBunlar 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 pagedist/404.html, ayrıca diğer her locale için dist/<locale>/404.html
Mount edilen her static dosya sistemiKendi 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çin Static() ç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 bilerek Static() yapılmış olabilir, yani cache'lenir ve post ettiği action tarafından invalidate edilir. Bu durumda da export edilmez, sunucudan sunulur. Scaffold'daki /features page'i buna bir örnektir.
  • Guard'lı page'ler. Layout zincirinde ya da content fragment'inde bir guard bulunan page, stratejisi ne olursa olsun collage.ErrGuarded ile 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 ve collage.ErrDynamicPathUnresolved ile 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.ErrDegradedRender ile 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 iyiyse BuildOptions.AllowDegraded ayarı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.Build upstream'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 bir index.html hiç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 bir WithStaticParams ya da bir page'in index.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. Build OutDir'e dokunmadan durur: hiçbir şey temizlenmez ya da yazılmaz, 404.html ya da mount edilen dosya kopyalanmaz ve BuildFinishedHook çağrılmaz. Document'ların WithStaticParams'ı 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: /About ile /about macOS 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). /old ile /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.html yanındaki /about ya da /about/, docs/intro/index.html yanındaki /docs/{rest...} buna örnektir. /{slug} gibi placeholder'lı bir From, 404.html dahil 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%A9llo değ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.ErrRouteParams ile 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 ../about gibi 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ında x\..\..\about baş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.ErrBuildPanic olarak 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 doc gibi Static() ya da Incremental(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.New asla 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.Last 1 olur ve Items boş, 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 perPage panic 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 da Incremental). 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ğu PageURLs için kullanılır. 1. sayfa listelenmez, çünkü o /blog adresidir. 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 ile last arası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. Hata collage.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).Last sayfası için bir {"tag": t, "n": k}. Locale yoksa paginate.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=2 isteğine /search dosyası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

AlanAnlamı
OutDirDosyaları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).
LocalesYalnızca bu locale'leri build eder. Boş bırakılırsa page'lerin tanımladığı bütün locale'ler build edilir.
ConcurrencyAynı 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.
AllowDegradedRender 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üzden dist/blog/ altında üç index.html var. Raporun adını verdiği on dosyadan sonra gelen on birinci dosya, hash'li kopyasının yanındaki dist/static/app.css'tir.
  • Feed ve sitemap yazılır. Feed Static(), sitemap ise Incremental(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çin collage.ErrDynamicPathUnresolved ile atlanır. Her tag için bir {"tag": t} döndüren bir WithStaticParams bu 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'i collage.ErrUnresolvedToken'dır. Bir form'un post edeceği bir sunucuya ihtiyacı vardır. collage serve, çoğu static host gibi, /contact isteğine 404.html ile cevap verir.
  • Arama page'i var, ama arama yapmaz. Bir dosyanın query string'i yoktur. Bu yüzden /search?q=feeds isteği de /search ile aynı dist/search/index.html dosyası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
  • /about isteğine about/index.html ile cevap verilir.
  • index.html içermeyen bir dizin 404 döner. Dizin listelemesi yapılmaz.
  • Bilinmeyen bir path, 404 status'uyla 404.html dö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.html köktedir. Çoğu host bu dosyayı hiçbir config gerekmeden bu adla bulur.
  • TrailingSlash açık olmalıdır. Bir page <path>/index.html olarak 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, Age ve X-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.html page'leri. BuiltFile.Captured bunlar 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 onun Status'u 0 kalır. Home page'in kökteki kopyası sorulmaz, çünkü uygulama /'yi redirect eder. Ama bu kopya, Captured dahil, home page'in yakalama sonucunu taşır.

Yakalamanın bulduğu şeyler build'in finding'lerinde uyarı olarak raporlanır:

KuralAnlamı
unstable-headerBir 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-statusBir dosya 2xx dışında bir status ile ya da iki farklı status ile cevaplandı.
capture-failedBir path cevaplanmadı (her request'in bir süre sınırı vardır) ya da yakalama hiç çalışmadı.
capture-dev-modeBuild development modunda çalıştı. Bu moddaki header'lar (Cache-Control: no-store) deploy edilecek header'lar değildir.
capture-personalBazı 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" } }
targetYazdıkları
netlify_headers ve _redirects
cloudflare_headers ve _redirects
vercelvercel.json
github-pagesher 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.