Site kurmak11 dk okuma

Head ve SEO

Title'ları, meta tag'leri, stylesheet'leri ve structured data'yı onları bilen fragment tanımlar, layout yerleştirir.

Bir page'in title'ını bilen fragment, <head>'i yazan fragment'le nadiren aynıdır. Post kendi title'ını ve özetini bilir. Gallery, gallery.css'e ihtiyacı olduğunu bilir. Layout ise <head>'i bunlar render edilmeden önce yazmıştır; ikisini de bilmez.

collage bu sorunu hoisting ile çözer. Fragment, page içinde nerede durursa dursun head'e neyin gireceğini tanımlar. Tanımların nereye yerleşeceğini ise layout belirler.

Nereye yerleşir

Layout, <head>'inin içine bir marker koyar:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="{{asset "/static/app.css"}}">
  {{hoist "head"}}
</head>
<body>
  {{slot "content"}}
</body>
</html>

{{hoist "head"}} içerik yazmaz, bir marker yazar. Çünkü o noktada altındaki hiçbir şey henüz render edilmemiştir.

Marker sitenin stylesheet'inden sonra gelir. Böylece bir fragment'in hoist ettiği stylesheet ondan sonra link'lenir ve eşit specificity'deki bir kuralda üstün gelir. collage new'un yazdığı layout'ta marker bu konumdadır. Marker'ı başa koyan bir layout ise son sözü sitenin stylesheet'ine bırakır.

Page'in tamamı bittiğinde collage bu marker'ı, ağacın herhangi bir yerinde "head" alanı için tanımlanmış her şeyle değiştirir. Bu iş tek geçişte yapılır ve konumu yine layout belirler.

Bir blog post page'inde hoisting. Layout, The Wire title'ını tanımlar. İçindeki post, data handler'ından kendi title'ını ve bir description meta'sını tanımlar. Post'un içindeki iki gallery fragment'inin her biri gallery.css ister. Tanımlar her key için tek bir kayıt olarak toplanır: en içteki tanım kazandığı için title post'unkidir, description post'unkidir, iki kez istenen gallery.css bir kez link'lenir. Page'in tamamı render edildikten sonra bu kayıtlar layout'un hoist head marker'ının yerine yazılır.layouttitle: The Wirepostdata handlertitle: post'unkimeta:descriptiongallerygallery.cssgallerygallery.cssher key için bir kayıttitlepost'unki (en içteki)meta:descriptionpost'unkistylesheet:/static/gallery.cssiki istek, tek linkpage render edilincehoist "head" marker'ı dolar
Her fragment bildiğini, bulunduğu yerden tanımlar: layout varsayılan bir title'ı, post kendi title'ını ve bir description'ı, her gallery ihtiyaç duyduğu stylesheet'i. Tanımlar her key için tek bir kayıt olarak toplanır. Bir key'in en içteki tanımı kazandığı için post'un title'ı layout'unkinin yerine geçer, gallery.css için gelen iki istek de tek bir link olur. Page'in tamamı render edildikten sonra bu kayıtlar, her key'in ilk tanımının sırasıyla layout'un {{hoist "head"}} marker'ının yerine yazılır.

Marker yoksa tanımlar hiçbir yere yerleşmez. Bir title ya da bir plugin'in çıktısı eksikse ilk kontrol etmeniz gereken şey budur.

Handler olmadan bir title

Program başlarken bilinen bir title, örneğin layout'taki site adı ya da "Hakkında" page'inin adı, hiç kod gerektirmez. WithTitle onu fragment üzerinde tanımlar:

layout := collage.NewFragment("layout", "layouts/master.html").
	WithTitle("The Wire").
	Build()

Bu, rc.HoistTitle'ın yaptığı tanımın aynısıdır. Bu yüzden aşağıdaki kurallara uyar: en içteki kazanır ve aynı fragment'in data handler'ının hoist ettiği bir title onun yerine geçer. Handler'ın aksine, strateji tanımlamayan bir page'i static bırakır. Bkz. Caching.

Data handler'dan tanımlamak

Geri kalan her şey, yani içerikten gelen bir title, bir description ya da bir stylesheet, RenderContext üzerindeki helper'larla tanımlanır. Bunları bir data handler'dan çağırın:

func loadPost(ctx context.Context, rc *collage.RenderContext) (*Post, []string, error) {
	post, err := store.Post(ctx, rc.Param("slug"))
	if err != nil {
		return nil, nil, err
	}

	rc.HoistTitle(post.Title + " — The Wire")
	rc.HoistMeta("description", post.Summary)
	rc.HoistProperty("og:title", post.Title)
	rc.HoistProperty("og:image", post.CoverURL)
	rc.HoistLink("canonical", siteOrigin+"/blog/"+post.Slug)
	if err := rc.HoistStylesheet("/static/post.css"); err != nil {
		return nil, nil, err
	}

	return post, []string{"post:" + post.Slug}, nil
}
ÇağrıÜrettiğiKey
rc.HoistTitle(text)<title>text</title>title
rc.HoistMeta(name, content)<meta name="…" content="…">meta:<name>
rc.HoistProperty(property, content)<meta property="…" content="…"> (Open Graph)property:<property>
rc.HoistLink(rel, href)<link rel="…" href="…">link:<rel>
rc.HoistAlternate(hreflang, href)<link rel="alternate" hreflang="…" href="…">alternate:<hreflang>
rc.HoistStylesheet(path)Dosyanın content-addressed URL'siyle<link rel="stylesheet" href="…">stylesheet:<path>

Her helper kendisine verilen değeri escape eder. Bu yüzden bir post'un adından oluşturulan title, post'un adı ne olursa olsun güvenlidir.

HoistStylesheet, dosyanın mount edilmiş path'ini alır. O dosya hiçbir mount'ta yoksa hata döndürür. Var olmayan bir stylesheet'e link veren page bozuk bir page'dir ve bunu açıkça söylemesi gerekir.

Bu helper'ları senkron olarak, data handler'ın kendi goroutine'inden çağırın. Handler'ın başlattığı başka bir goroutine'den yapılan tanımın page içinde bir konumu yoktur.

Template'ten

Bir fragment'in template'i stylesheet'i kendisi de isteyebilir:

{{stylesheet "/static/gallery.css"}}
<div class="gallery">…</div>

{{stylesheet}} bulunduğu yerde hiçbir şey render etmez, HoistStylesheet ile aynı işi yapar. Böylece gallery'nin CSS'i, gallery hangi page'deyse onunla birlikte oraya gider.

Key'ler ve en içtekinin kazanması

Her tanımın bir key'i vardır. Neyin aynı şey sayılacağını bu key belirler:

  • Farklı key'lerin hepsi görünür. Her biri, page sırasındaki ilk tanımının yerinde durur.
  • Aynı key iki kez tanımlanırsa en içteki tanım kalır.

Bu tek kural iki işi birden görür. Stylesheet'in key'i path'idir. Bu yüzden gallery.css isteyen beş fragment tek bir <link> üretir, farklı stylesheet'ler ise birikir. Title'ın ise tek bir key'i vardır. Bu yüzden daha spesifik bir fragment'in title'ı, daha genel olanın title'ının yerine geçer. Bu da varsayılan değerleri kolaylaştırır. Varsayılanları layout'ta tanımlayın, her page istediğinde onları override etsin:

layout := collage.NewFragment("layout", "layouts/master.html").
	WithTitle("The Wire").
	WithData(collage.Effect(func(_ context.Context, rc *collage.RenderContext) error {
		rc.HoistMeta("description", "News about the sea, and the people who live beside it.")
		return nil
	})).
	Build()

Bu layout'un içindeki bir post kendi title'ını ve description'ını tanımlar. Page'de görünenler de bunlar olur. Hiçbir şey tanımlamayan bir page layout'unkileri korur.

Layout'un template'ine ayrıca elle bir <title> yazmayın. Yazarsanız o title, hoist edilen title'ın yanında durur. İki title'ı olan bir page'de tarayıcı bunlardan birini yok sayar. collage new'un oluşturduğu layout da sitenin adını WithTitle ile verir. Böylece bir page'in kendi title'ı onun yerine geçer.

Layout'taki bir handler her page'deki bir handler demektir. Bu yüzden yukarıdaki description, strateji tanımlamayan her page'i dynamic yapar. Page'lerinin cache'lenmesini isteyen bir site, page'lerinde Static() ya da Incremental(ttl) belirtir ya da layout'ta yalnızca WithTitle bırakır.

Sürpriz olmasınlar diye dört ayrıntıyı belirtelim:

  • Konumu kazanan tanım değil, ilk tanım belirler. Head, iç taraftaki bir fragment'in title'ı override edip etmemesine göre kendini yeniden sıralamaz.
  • Aynı derinlikte, page'de daha sonra gelen kazanır. Aynı key'i tanımlayan iki kardeş fragment gerçek bir çakışmadır. Bu çakışma, fragment'lerin page içindeki sırasıyla çözülür: bir slot içinde daha sonra bağlanan, slot'lar arasında template'in daha sonra render ettiği kazanır. Slot adı ya da hangi data handler'ın önce bittiği belirleyici değildir, öyle olsaydı head request'ten request'e değişirdi.
  • Render edilmeyen hiçbir şeyi hoist etmez. Template'inin hiçbir zaman render etmediği bir slot'un arkasındaki fragment, handler'ı çalışmış olsa bile page'e hiçbir şey eklemez: title, meta ya da tag yok. Başarısız olan bir fragment hoist ettiklerini markup'ıyla birlikte götürür; bu yüzden opsiyonel bir fragment'in fallback'i, başarısız fragment'in title'ı altında render edilmez. Başarısız fragment'in tag'leri kalır, çünkü page'in neye dayandığını söylerler.
  • Sırayı saat değil, page belirler. Kardeş data handler'lar eşzamanlı çalışır. Ama bir key, önce onu ilk tanımlayan fragment'in page içindeki yerine, sonra o fragment'in tanımlama sırasına göre yerleştirilir. Böylece head, birbirini override eden stylesheet'ler de dahil olmak üzere her render'da aynı olur.

Geri kalan her şey: rc.Hoist

Helper'ların hepsi tek bir method üzerine kuruludur:

func (rc *RenderContext) Hoist(area, key string, html template.HTML)

Bu method html'i key altında, area'ya tam yazıldığı gibi ekler. Zaten var olma sebebi budur: helper'ların kapsamadığı markup. Bu da escape işinin size düştüğü anlamına gelir. Markup'ı kontrolünüzdeki değerlerden oluşturun ya da değerleri escape edin:

rc.Hoist("head", "preload:hero", template.HTML(
	`<link rel="preload" as="image" href="`+html.EscapeString(post.CoverURL)+`">`))

Aynı key kuralları burada da geçerlidir. Bu yüzden eklediğiniz şeyin ne olduğunu anlatan bir key seçin. Bir kez görünmesi gereken her şey için tek bir key kullanın. Biriken şeyler için ise her değere ayrı bir key verin.

Alanın adı harflerden, rakamlardan, _ ve - karakterlerinden oluşan herhangi bir ad olabilir: {{hoist}} başka her adı reddeder; {{hoist .Area}}'nın script enjekte etmenin bir yoluna dönüşmesini de bu engeller. Bir layout'ta birden fazla marker bulunabilir. Örneğin fragment'lerin ihtiyaç duyduğu script'ler için </body>'den önce bir {{hoist "scripts"}} koyabilirsiniz:

rc.Hoist("scripts", "script:map", template.HTML(`<script src="`+mapJS+`" defer></script>`))

Canonical link, aynı içeriğe birden fazla URL ulaştığında (örneğin tracking query'siyle ve onsuz) arama motorlarına hangisinin asıl URL olduğunu söyler. Bu link'e mutlak bir URL verin. collage origin değil path üretir. Bu yüzden sitenizin origin'ini kendi config'inizde tutun ve ikisini birleştirin:

rc.HoistLink("canonical", siteOrigin+rc.Request.URL.Path)

Birden fazla dildeki bir site, her çevirinin nerede olduğunu da belirtmelidir. Bunun için her dile bir <link rel="alternate" hreflang="…"> gerekir. HoistLink her rel için tek bir link tuttuğundan bunu ifade edemez. rc.HoistAlternate ise her link'in key'ini diline göre belirler, böylece her çeviri bir kez görünür. Bu link'leri layout'tan, o an hangi page render ediliyorsa onun için, app.URL ile tanımlayın:

func Layout(app *collage.App) *collage.Fragment {
	return collage.NewFragment("layout", "layouts/master.html").
		WithData(collage.Effect(func(_ context.Context, rc *collage.RenderContext) error {
			for _, locale := range []string{"en", "tr"} {
				href, err := app.URL(rc.Page.Name, locale, rc.PathParams)
				if errors.Is(err, collage.ErrNoPathInLocale) {
					continue // not translated into this one
				}
				if err != nil {
					return err
				}
				rc.HoistAlternate(locale, siteOrigin+href)
			}
			return nil
		})).
		Build()
}

Bazı page'lerin çevirisi farklı bir slug kullanır ve bunu yalnızca o page'in içeriği bilir. Böyle bir page, o dil için kendi rc.HoistAlternate çağrısını yapar. Daha içte olduğu için de layout'un tanımının yerine geçer.

Handler'ı olmayan bir layout için template'teki karşılığı localeURL fonksiyonudur. Böyle bir layout, strateji tanımlamayan page'leri static bırakır. localeURL, page'in var olmadığı bir dil için boş döner:

{{with localeURL "tr"}}<link rel="alternate" hreflang="tr" href="https://thewire.example{{.}}">{{end}}

Structured data

Arama motorları schema.org structured data'sını head'deki JSON-LD bloklarından okur. elagoht/jsonld plugin'i bu blokları sizin yerinize yazar. Bunu elle oluşturulmuş JSON'dan değil, tipli değerlerden yapar:

import "github.com/Elagoht/collage-jsonld"

func loadPost(ctx context.Context, rc *collage.RenderContext) (*Post, []string, error) {
	post, err := store.Post(ctx, rc.Param("slug"))
	if err != nil {
		return nil, nil, err
	}
	jsonld.Emit(rc, jsonld.BlogPosting{
		Headline:      post.Title,
		Description:   post.Summary,
		DatePublished: post.PublishedAt,
		AuthorName:    post.Author,
	})
	return post, []string{"post:" + post.Slug}, nil
}

jsonld.Emit, "head" alanına hoist eder. Bu yüzden bu sayfada anlatılan diğer her şeyle aynı marker'a ihtiyaç duyar ve aynı kurallara uyar: her schema.org tipi ve node'un Key'i için bir key vardır ve en içteki kazanır.

Plugin'i register ettiğinizde (Config.Plugins içinde jsonld.New(jsonld.Options{})), plugin bir site adıyla yapılandırılmışsa site genelinde bir WebSite node'u ekler. Page'e özel veri ise her zaman data handler'larınızdan gelir. Çünkü page'in ne hakkında olduğunu yalnızca onlar bilir.

Crawler'lara ve arama motorlarına söylenenlerin geri kalanını altı plugin daha karşılar. İlk üçü, bir crawler'ın head dışında okuduklarıyla ilgilidir:

PluginNe yapar
elagoht/sitemapRegister ettiğiniz page'lerden /sitemap.xml'i sunar
elagoht/robots/robots.txt'yi sunar
elagoht/feedRSS ve Atom feed'leri sunar ve bunları her page'in head'inde duyurur
elagoht/metaBu sayfada anlatılan Open Graph ve Twitter tag'lerini, canonical URL'yi ve hreflang link'lerini site genelindeki varsayılanlardan ve her page'in söylediklerinden yazar
elagoht/redirectsBir taşımadan kalan eski adresleri bir dosyadan okuyup sunar ve bunları static build'e aktarır
elagoht/indexnowBir invalidation'ın hangi URL'leri değiştirdiğini arama motorlarına bildirir

Hoisting ve collage'ın geri kalanı

  • Cache'lenen page'ler head'lerini korur. Marker, page saklanmadan önce değiştirilir. Bu yüzden cache'lenmiş bir page, tanımlanmış her şeyle birlikte sunulur.
  • Kendi URL'sinde sunulan bir fragment'in head'i yoktur.WithFragmentPath ile sunulan bir fragment'in layout'u yoktur. Marker koymadığı bir alana hoist ettiği şeyler markup'ından önce, her öğe için etkisiz bir <template data-collage-hoist> olarak gelir. Bir script bunları page'e ekleyebilir. Bkz. Hoist ettikleri.
  • Hoist işlemini rc.Page üzerinden değil, data handler'lardan yapın.rc.Page register edilmiş page'dir ve her request tarafından paylaşılır. Ona yazmak data race'e yol açar. Request'e göre değişen her şey rc üzerinden tanımlanır.

Örnek: bir katalog ürün page'i

Bir mağazanın /products/{id} adresindeki ürün page'i, yani Fragment'ler ve slot'lar sayfasında kurulanın küçük bir sürümü, bir arama motorunun ve bir link preview'ının okuyabileceği bir head'e ihtiyaç duyar. Head'deki her şeyi, onu bilen fragment tanımlar:

Head'deTanımlayanKey
Title, Brass deck lamp — The ShopÜrünün handler'ı, layout'un WithTitle'ının yerinetitle
DescriptionÜrünün handler'ı, layout'unkinin yerinemeta:description
og:title, og:description, og:imageÜrünün handler'ıproperty:og:…
Canonical linkÜrünün handler'ılink:canonical
Yalnızca bu page'in ihtiyaç duyduğu product.cssÜrünün handler'ı, HoistStylesheet ilestylesheet:/static/product.css
stock.cssStok kutusunun template'i, {{stylesheet}} ilestylesheet:/static/stock.css

Layout'un template'i, bu sayfanın başındaki template'tir. Layout, kendisi hakkında hiçbir şey söylemeyen her page için mağazanın adını ve kısa bir açıklamasını verir:

layout := collage.NewFragment("layout", "layouts/master.html").
	WithTitle("The Shop").
	WithData(collage.Effect(func(_ context.Context, rc *collage.RenderContext) error {
		rc.HoistMeta("description", "Lamps, rope and brass fittings for small boats.")
		return nil
	})).
	Build()

Ürünün handler'ı, hangi ürün olduğunu öğrenir öğrenmez geri kalanını tanımlar. Örnekteki catalog ve inventory paketleri sizin kendi veri katmanınızı temsil eder:

const siteOrigin = "https://shop.example"

type product struct {
	ID       string
	Name     string
	Price    string
	Summary  string
	ImageURL string
}

type stockLevel struct {
	Count int
}

func loadProduct(ctx context.Context, rc *collage.RenderContext) (product, []string, error) {
	id := rc.Param("id")
	p, err := catalog.Product(ctx, id)
	if errors.Is(err, catalog.ErrNoProduct) {
		return product{}, nil, fmt.Errorf("shop: no product %q: %w", id, collage.ErrNotFound)
	}
	if err != nil {
		return product{}, nil, err
	}

	rc.HoistTitle(p.Name + " — The Shop")
	rc.HoistMeta("description", p.Summary)
	rc.HoistProperty("og:title", p.Name)
	rc.HoistProperty("og:description", p.Summary)
	rc.HoistProperty("og:image", p.ImageURL)
	rc.HoistLink("canonical", siteOrigin+"/products/"+id)
	if err := rc.HoistStylesheet("/static/product.css"); err != nil {
		return product{}, nil, err
	}

	return product{ID: p.ID, Name: p.Name, Price: p.Price, Summary: p.Summary, ImageURL: p.ImageURL},
		[]string{"product:" + id}, nil
}

func loadStock(ctx context.Context, rc *collage.RenderContext) (stockLevel, error) {
	n, err := inventory.Count(ctx, rc.Param("id"))
	if err != nil {
		return stockLevel{}, err
	}
	return stockLevel{Count: n}, nil
}

Stok kutusu kendi stylesheet'ini kendisi ister. Böylece hangi page'de render edilirse edilsin stylesheet'i yanında olur:

<!-- templates/fragments/stock.html -->
{{stylesheet "/static/stock.css"}}
<p class="stock">{{.Count}} in stock</p>

Page, sayıyı güncel tutan bir script için kutuyu kendi URL'sinde açar:

stock := collage.NewFragment("product-stock", "fragments/stock.html").
	WithData(collage.Load(loadStock)).
	Build()

content := collage.NewFragment("product", "pages/product.html").
	WithData(collage.LoadTagged(loadProduct)).
	WithSlotFragment("stock", stock).
	Required().
	Build()

page := collage.NewPage("product").
	WithLayouts(layout).
	WithContent(content).
	WithPath("en", "/products/{id}").
	WithFragmentPath("en", "/products/{id}/stock", stock).
	Build()

Page'in head'inde ne var

/products/42 için gelen bir request 200 ile cevaplanır. Head'i aşağıdaki gibidir. Burada her element ayrı bir satırda; collage ise hoist edilenleri yan yana yazar:

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="/static/app.2708d73bf31c36cd.css">
  <title>Brass deck lamp — The Shop</title>
  <meta name="description" content="A lamp for a boat&#39;s chart table.">
  <meta property="og:title" content="Brass deck lamp">
  <meta property="og:description" content="A lamp for a boat&#39;s chart table.">
  <meta property="og:image" content="https://shop.example/img/lamp.jpg">
  <link rel="canonical" href="https://shop.example/products/42">
  <link rel="stylesheet" href="/static/product.ab1d57cf7f5ec545.css">
  <link rel="stylesheet" href="/static/stock.1d101be0b97db6e6.css">
</head>
  • Hoist edilenler arasında title ve description en başta durur. Layout'un onları tanımladığı yerdedirler ama ürünün değerlerini taşırlar: konum ilk tanımın, değer en içteki tanımındır.
  • Özetteki kesme işareti escape edilir. Her helper kendisine verileni escape eder.
  • İki stylesheet de content-addressed URL'leriyle link'lenir. Page onları hangi sırayla tanımladıysa o sırayla, önce ürününki, sonra stok kutusununki gelir. app.css onlardan önce gelir, çünkü layout'un template'i onu marker'ın üstüne yazar. Böylece product.css'teki bir kural, app.css'teki eşit specificity'deki bir kurala üstün gelir.

Stok kutusunun URL'si ne döner

GET /products/42/stock stok kutusunu tek başına render eder. Etrafında layout yoktur, "head" için bir marker da yoktur. Hoist ettikleri, Hoist ettikleri bölümünde anlatıldığı gibi markup'ından önce gelir:

<template data-collage-hoist="head" data-collage-key="stylesheet:/static/stock.css"><link rel="stylesheet" href="/static/stock.1d101be0b97db6e6.css"></template>
<p class="stock">12 in stock</p>

Kutuyla birlikte yalnızca kendi tanımları gelir. Ürünün handler'ı bu render'a dahil değildir. Bu yüzden burada ne title ne de bir Open Graph tag'i vardır; kutuyu çeken page kendi head'ini korur.

Stylesheet, page'in head'inin onu tekilleştirdiği key'i taşır. Bu page stock.css'i ilk render'ında zaten link'lemiştir, yani bir script'in ekleyeceği bir şey yoktur. Kutu olmadan render edilmiş bir page'de ise kutunun stylesheet'i client'a bu yolla gelir ve bir script onu head'e ekleyene kadar etkisiz kalır.

Aynı stok kutusu, iki farklı cevap. Ürün page'inin içinde, /products/42 için gelen bir request title'ı, description'ı, Open Graph tag'lerini, product.css'i ve stok kutusunun stock.css'ini layout'un head'ine, stok kutusunu da body'ye koyar. Kendi URL'sinde, /products/42/stock için gelen bir request önce stock.css'i taşıyan bir template elementi, sonra stok kutusunun markup'ıyla cevaplanır; etrafında layout yoktur ve ürünün handler'ının tanımladığı hiçbir şey yoktur.GET /products/42<head>title · meta · og:*product.cssstock.css<body>stok kutusuGET /products/42/stockresponse body<template>stock.cssstok kutusuetrafında layout yoktitle yok, og:* yok
Aynı stok kutusu, iki farklı cevap. Ürün page'inin içinde kutunun stock.css'i; title, description, Open Graph tag'leri ve product.css ile birlikte layout'un head'ine katılır. Kendi URL'sinde layout yoktur: önce stylesheet, key'ini belirten etkisiz bir <template data-collage-hoist> içinde gelir, sonra kutunun markup'ı. Ürünün handler'ının tanımladığı hiçbir şey cevapta yer almaz.