Building a site13 min read

Head and SEO

Titles, meta tags, stylesheets and structured data declared by the fragment that knows them, placed by the layout.

The fragment that knows a page's title is rarely the one that writes <head>. The post knows its own title and summary; the gallery knows it needs gallery.css; the layout, which wrote <head> before either of them rendered, knows neither.

collage solves this by hoisting: a fragment declares what belongs in the head, from wherever it sits in the page, and the layout says where declarations land.

Where it lands

The layout places a marker in its <head>:

<!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"}} writes a marker, not content — nothing below it has rendered yet.

The marker comes after the site's stylesheet, so a stylesheet a fragment hoists is linked after it and wins a rule of equal specificity; the layout collage new writes has it there. A layout of yours that puts the marker first gives the site's stylesheet the last word instead.

When the whole page is finished, collage replaces the marker with everything that was declared for the "head" area, anywhere in the tree. One pass, and the layout still decides the position.

Hoisting on a blog post page. The layout declares the title The Wire. The post, inside it, declares its own title and a description meta from its data handler. Two gallery fragments inside the post each ask for gallery.css. The declarations are collected one entry per key: the title is the post's, because the innermost declaration wins; the description is the post's; gallery.css was asked for twice and is linked once. Once the whole page has rendered, the entries replace the layout's hoist head marker.layouttitle: The Wirepostdata handlertitle: the post'smeta:descriptiongallerygallery.cssgallerygallery.cssone entry per keytitlethe post's: inner winsmeta:descriptionthe post'sstylesheet:/static/gallery.cssasked twice, one linkonce the page has renderedhoist "head" marker filled
Every fragment declares what it knows, from wherever it sits: the layout a default title, the post its own title and a description, each gallery the stylesheet it needs. The declarations are collected one entry per key. The post's title replaces the layout's because the innermost declaration of a key wins, and two requests for gallery.css become one link. Once the whole page has rendered, the entries replace the layout's {{hoist "head"}} marker, in the order of each key's first declaration.

Without the marker, declarations go nowhere. That is the first thing to check when a title or a plugin's output is missing.

A title without a handler

A title known when the program starts — the site's name on its layout, the name of an about page — needs no code. WithTitle declares it on the fragment:

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

It is the same declaration rc.HoistTitle makes, so it follows the same rules below: the innermost one wins, and a title the same fragment's data handler hoists replaces it. Unlike a handler, it leaves a page that declares no strategy static — see Caching.

Declaring from a data handler

Everything else — a title that comes from the content, a description, a stylesheet — is declared by the helpers on RenderContext. Call them from a data handler:

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
}
CallEmitsKey
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)<link rel="stylesheet" href="…"> at the file's content-addressed URLstylesheet:<path>

Every helper escapes what it is given, so a title built from a post's name is safe whatever the post is called.

HoistStylesheet takes the file's mounted path and returns an error when no mount has that file — a page linking a stylesheet that does not exist is a broken page, and it should say so.

Call them synchronously, from the data handler's own goroutine. A declaration made from a goroutine the handler started has no position in the page.

From a template

A fragment's template can ask for a stylesheet itself:

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

{{stylesheet}} renders nothing where it stands; it does what HoistStylesheet does. The gallery's CSS travels with the gallery, onto whichever page it is on.

Keys, and the innermost wins

Every declaration has a key, and the key decides what counts as the same thing:

  • Different keys all appear, each at its earliest declaration in page order.
  • The same key declared twice keeps the innermost declaration.

That one rule does two jobs. A stylesheet is keyed by its path, so five fragments asking for gallery.css produce one <link>, and different stylesheets accumulate. A title has one key, so a more specific fragment's title replaces a less specific one's. That makes defaults easy — declare them in the layout, and let any page override them:

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()

A post nested inside that layout declares its own title and description, and those are the ones on the page. A page that declares nothing keeps the layout's.

Do not also write a literal <title> in the layout's template — it would sit beside the hoisted one, and a page with two titles has one a browser ignores. The layout collage new scaffolds names the site with WithTitle, so a page's own title replaces it.

A handler on the layout is a handler on every page, so the description above makes every page that declares no strategy dynamic. A site that wants them cached says Static() or Incremental(ttl) on its pages, or leaves the layout with WithTitle alone.

Four details, so they are not a surprise:

  • Position comes from the first declaration, not the winning one. The head does not reorder itself depending on whether something nested happened to override a title.
  • At equal depth, the one later in the page wins. Two sibling fragments declaring one key is a real conflict, and it is settled by their order in the page — within a slot the one bound later, between slots the one the template renders later — not by slot name, and not by whose data handler finished first, which would make the head change from request to request.
  • What never renders hoists nothing. A fragment behind a slot its template never renders adds nothing to the page — no title, no meta, no tags — even though its handler ran. A fragment that failed takes its hoists with its markup, so an optional fragment's fallback is not rendered under the failed fragment's title. The failed fragment's tags stay, since they say what the page depended on.
  • The order is the page's, not the clock's. Sibling data handlers run concurrently, but a key is placed by where the fragment that first declares it sits in the page, then by the order that fragment declared in — so the head is the same on every render, stylesheets that override one another included.

Anything else: rc.Hoist

The helpers are built on one method:

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

It inserts htmlexactly as written, under key, into area. That is what it is for — markup the helpers do not cover — and it means escaping is your job. Build the markup from values you control, or escape them:

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

The same key rules apply, so choose a key that says what the thing is: one per thing that should appear once, one per value for things that accumulate.

The area is any name made of letters, digits, _ and -: {{hoist}} refuses any other, which is also what keeps {{hoist .Area}} from becoming a way to inject script. A layout can have more than one marker — a {{hoist "scripts"}} before </body>, say, for scripts a fragment needs:

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

A canonical link tells search engines which URL is the real one when several reach the same content — with and without a tracking query, say. Give it an absolute URL. collage builds paths, not origins, so keep your site's origin in your own configuration and join the two:

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

A site in several languages should also say where each translation is, with one <link rel="alternate" hreflang="…"> per language. HoistLink keeps one link per rel, so it cannot say that; rc.HoistAlternate keys each link by its language instead, so every translation appears once. Declare them from the layout, for whichever page is being rendered, with app.URL:

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()
}

A page whose translation has a different slug — which only its content knows — declares its own rc.HoistAlternate for that language, and, being inner, it replaces the layout's.

The template equivalent, for a layout without a handler — which leaves pages that declare no strategy static — is localeURL, which is empty for a language the page does not exist in:

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

Structured data

Search engines read schema.org structured data from JSON-LD blocks in the head. The elagoht/jsonld plugin writes them for you, from typed values rather than hand-built JSON:

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 hoists into "head", so it needs the same marker as everything else on this page, and it follows the same rules: one key per schema.org type and node Key, the innermost winning.

Registering the plugin (jsonld.New(jsonld.Options{}) in Config.Plugins) adds a site-wide WebSite node when it is configured with a site name. The per-page data always comes from your data handlers, because only they know what the page is about.

Six more plugins cover the rest of what crawlers and search engines are told — the first three what a crawler reads beyond the head:

PluginWhat it does
elagoht/sitemapServes /sitemap.xml from the pages you registered
elagoht/robotsServes /robots.txt
elagoht/feedServes RSS and Atom feeds, and announces them in every page's head
elagoht/metaWrites the Open Graph and Twitter tags, the canonical URL and the hreflang links described on this page, from site-wide defaults and what each page says
elagoht/redirectsServes a migration's old addresses from a file, and hands them to a static build
elagoht/indexnowTells search engines which URLs an invalidation changed

Hoisting and the rest of collage

  • Cached pages keep their head. The marker is replaced before the page is stored, so a cached page is served with everything that was declared.
  • A fragment at its own URL has no head. A fragment served through WithFragmentPath has no layout. What it hoists into an area it placed no marker for comes ahead of its markup, one inert <template data-collage-hoist> per item, for a script to add to the page — see What it hoists.
  • Hoist from data handlers, not from rc.Page.rc.Page is the registered page, shared by every request; writing to it is a data race. What varies per request is declared through rc.

Example: a catalogue product page

A shop's product page at /products/{id} — a smaller version of the one Fragments and slots builds — needs a head that a search engine and a link preview can read. Each thing in it is declared by the fragment that knows it:

In the headDeclared byKey
The title, Brass deck lamp — The ShopThe product's handler, replacing the layout's WithTitletitle
The descriptionThe product's handler, replacing the layout'smeta:description
og:title, og:description, og:imageThe product's handlerproperty:og:…
The canonical linkThe product's handlerlink:canonical
product.css, which only this page needsThe product's handler, with HoistStylesheetstylesheet:/static/product.css
stock.cssThe stock box's template, with {{stylesheet}}stylesheet:/static/stock.css

The layout's template is the one at the top of this page. The layout names the shop and describes it, for any page that says nothing of its own:

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()

The product's handler declares the rest as soon as it knows which product it is. The catalog and inventory packages stand for your own data layer:

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
}

The stock box asks for its own stylesheet, so it has it on whichever page it is rendered:

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

The page opens the box at a URL of its own, for a script that keeps the count fresh:

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()

What the page's head holds

A request for /products/42 answers 200. Its head reads as follows, one element per line here; collage writes the hoisted ones side by side:

<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>
  • The title and the description come first among the hoisted items, where the layout declared them, but they carry the product's values: the position is the first declaration's, the value the innermost one's.
  • The apostrophe in the summary is escaped, as every helper escapes what it is given.
  • Both stylesheets are linked at their content-addressed URLs, the product's before the stock box's, in the order the page declared them. app.css comes before them, because the layout's template writes it above the marker, so a rule in product.css wins over one of equal specificity in app.css.

What the stock box's URL answers

GET /products/42/stock renders the stock box alone, with no layout around it and no marker for "head". What it hoisted comes ahead of its markup, as What it hoists describes:

<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>

Only the box's own declarations travel with it. The product's handler is not part of this render, so there is no title and no Open Graph tag here — the page that fetched the box keeps its own.

The stylesheet carries the key the page's head deduplicated it by. This page linked stock.css on its first render already, so a script has nothing to add. On a page that rendered without the box, this is how the box's stylesheet reaches the client, inert until a script adds it to the head.

The same stock box answered two ways. Inside the product page, a request for /products/42 puts the title, description and Open Graph tags, product.css and the stock box's stock.css in the layout's head, and the stock box in the body. At its own URL, a request for /products/42/stock answers with a template element carrying stock.css, then the stock box's markup, with no layout around it and nothing the product's handler declared.GET /products/42<head>title · meta · og:*product.cssstock.css<body>stock boxGET /products/42/stockresponse body<template>stock.cssstock boxno layout around itno title, no og:*
The same stock box, answered two ways. Inside the product page, its stock.css joins the title, the description, the Open Graph tags and product.css in the layout's head. At its own URL there is no layout: the stylesheet comes first, in an inert <template data-collage-hoist> that names its key, then the box's markup, and nothing the product's handler declared is in the answer.