How-to
Website
Describe pages to search engines and link previews
The build writes each page's head — its title, description, canonical link, Open Graph and Twitter tags, JSON-LD and icons — from the page's attributes and the meta settings in webfluent.app.json, so what a search result or a shared link shows is set where the page is declared. This blog has a home page with its own sharing image, a page per post that adds tags of its own, and a thanks page kept out of search:
Needs: src/posts.json and the pictures it names in public/, and meta.site_url in webfluent.app.json, each shown below. It claims / and the name Home: paste it into a new project, or replace the starter's src/pages/Home.wf with it.
type Post { slug: String, title: String, summary: String, cover: String, date: String, body: String }
const SITE = "https://acme.example"
data posts: [Post] = "posts.json"
page Home(path: "/", title: "Acme", description: "Tools for small teams.", image: "/og-default.png", image_alt: "The Acme logo on a blue field") {
Heading("Acme").h1
for p in posts by p.slug {
Link(p.title, to: "/posts/{p.slug}")
}
}
page PostPage(path: "/posts/:slug", slug: String, type: "article", paths: posts.map(p => p.slug),
title: "{posts.find(p => p.slug == slug)?.title ?? slug} — Acme",
description: "{posts.find(p => p.slug == slug)?.summary ?? "A post from the blog."}") {
derived post = posts.find(p => p.slug == slug)
head {
meta(property: "og:image", content: "{SITE}{post?.cover ?? "/og-default.png"}")
meta(property: "article:published_time", content: post?.date ?? "")
}
if let p = post {
Image(src: p.cover, alt: p.title)
Heading(p.title).h1
Text(format(p.date, .date, "long")).muted
Markdown(p.body)
}
}
page Thanks(path: "/thanks", title: "Thanks", description: "Your message reached us.", noindex: true) {
Heading("Thanks").h1
}
The posts are a JSON file the build reads, src/posts.json; a list of one is enough to try it:
[
{
"slug": "hello",
"title": "Hello, world",
"summary": "Why we started Acme, and what we make.",
"cover": "/covers/hello.png",
"date": "2026-03-05",
"body": "We make *tools* for small teams."
}
]
How it works
Put the pictures it names in public/ (public/og-default.png, public/covers/hello.png), and set meta.site_url as the config below does. Built, posts/hello/index.html is titled "Hello, world — Acme", its description is the post's summary, and its og:image is https://acme.example/covers/hello.png.
Each page's title: and description: are its <title> and the snippet a search result shows; image: and image_alt: are its sharing card's picture; type: "article" marks a post; noindex: true keeps a page out of search. The rest comes from meta in webfluent.app.json. A config that fills in every site-wide setting:
{
"meta": {
"title": "Acme",
"description": "Tools for small teams.",
"lang": "en",
"site_url": "https://acme.example",
"site_name": "Acme Inc.",
"owner": "organization",
"same_as": ["https://github.com/acme"],
"image": "/og-default.png",
"image_alt": "The Acme logo on a blue field",
"favicon": "/favicon.svg",
"touch_icon": "/apple-touch-icon.png",
"sitemap": true,
"fonts": ["https://fonts.googleapis.com/css2?family=Inter&display=swap"],
"stylesheets": ["/print.css"]
}
}
What the build writes into each page's head:
<title>and<meta name="description">, from the page'stitle:anddescription:. The description is the snippet a search result shows and a link preview quotes; keep it under about 150 characters.- A canonical link and
og:url, whensite_urlis set. A relative canonical is worse than none, so withoutsite_urlthe build writes none. - Open Graph and Twitter card tags:
og:title,og:description,og:image(the page'simage:or the site's),og:typefromtype:(websiteorarticle),og:site_name, andog:localein the form Open Graph reads —meta.langenisen_US,en-GBisen_GB,arisar_AR— with anog:locale:alternatefor each other locale. - The image's size and description:
og:image:widthandog:image:height, read from the file when the image is inpublic/(one on another origin is not fetched, so its card states no size), andog:image:altandtwitter:image:altfrom the page'simage_alt:, ormeta.image_altfor the site's image. A sharing image is best at 1200×630. - JSON-LD: the site's owner, a
WebSiteit publishes, aWebPageorArticle, and aBreadcrumbListderived from the route's segments. Each breadcrumb is a page a reader can open; a level no route answers is left out. hreflangalternates for the page and each of its translations (translates:), each at its own address and in its ownlang:, withx-defaultfor the one in the site's language (A page in its own language).- The icons:
<link rel="icon">forfavicon(typed, so an SVG is read as one) and<link rel="apple-touch-icon">fortouch_icon. Each is linked from the site's root under thebase_path(/my-site/favicon.svg), so it stays right when the router moves the page to another address. <meta name="robots" content="noindex">, and no sitemap entry, for anoindex: truepage.
Add tags for one page
To add tags of a page's own — an article's cover, its publication date — write them in head { } (Pages and routing). PostPage above sets its own Open Graph image from the post. A link preview fetches the image from another site, so its address must be absolute: {SITE} puts the site's origin in front of the post's site-relative cover. A tag written in head { } takes the place of the one the build would write, so the page carries one og:image.
The title: and description: of a :param page may name its parameters — title: "{slug} — Blog" — and each pre-rendered file, and the live page's tab, has that route's value. The title may also splice an expression over the parameters and the program's constants and data, as PostPage's does, and so may the description. The build works it out for each file, and the router again on each visit. image: is written as it stands, so a picture that depends on the parameter goes in head { }. Anything else the head should say about the entry goes in head { }, as above; the runtime keeps those tags current as the parameter changes.
Say who the site belongs to
The JSON-LD names the site's owner: meta.site_name, published as an Organization unless meta.owner says it is a person. To publish a personal site, name the person, what they do and where else they are:
{
"meta": {
"site_url": "https://ada.example",
"site_name": "Ada Lovelace",
"owner": "person",
"job_title": "Analyst",
"same_as": ["https://github.com/ada", "https://www.linkedin.com/in/ada/"]
}
}
The JSON-LD then holds a Person (@id …/#person) with jobTitle and sameAs. The WebSite's publisher and every WebPage's about point at it. An organisation's WebSite names it as publisher too, and takes same_as for its profiles.
To say anything else schema.org allows about a person or an organisation, add it to meta.owner_details. It is merged into the node as written:
{
"meta": {
"owner_details": {
"alternateName": "Augusta Ada King",
"worksFor": [{ "@type": "Organization", "name": "Analytical Engines" }],
"alumniOf": { "@type": "CollegeOrUniversity", "name": "University of London" },
"knowsAbout": ["Mathematics", "Computing"],
"knowsLanguage": ["en", "fr"]
}
}
}
What the node is — @type, @id, name, url — and what job_title and same_as write come from those settings; setting one in owner_details is E111.
Warning
Structured data has to agree with what the pages show, and the build cannot check that. State in owner_details only what the site says too.
Preload fonts served from the site
A font named by a @font-face in a project .css file is found only once styles.css has arrived and been read. To fetch it with the page instead, list it in meta.preload:
{ "meta": { "preload": ["/fonts/inter-latin.woff2"] } }
/* src/fonts.css */
@font-face {
font-family: "Inter";
font-weight: 400 800;
font-display: swap;
src: url("/fonts/inter-latin.woff2") format("woff2");
}
Each path becomes a <link rel="preload"> in every page's head, ahead of the stylesheets, with as taken from its extension: font, style, script or image. A font preload also carries crossorigin, without which the browser fetches the font twice.
Serving the fonts from public/ instead of a font service also takes a third-party stylesheet and two connections out of the way of the first paint. A path on another origin is E111: the policy the build ships would refuse it.
Keep addresses from redirecting
A static build writes /contact as contact/index.html. Most static hosts — GitHub Pages among them — answer /contact with a 301 redirect to /contact/. A canonical link, a sitemap entry and every link that names /contact then name an address that redirects, which a search engine reads as "not this page". To fix it, set build.clean_urls to one of two values:
{ "build": { "ssg": true, "clean_urls": "file" } }
"file"keeps/contactand writescontact.htmlbesidecontact/index.html, which the host serves for/contactdirectly. The page then addresses its scripts and sheets from the site's root (/app.js, under thebase_path), so the one file reads the same from either address."directory"names every route with its slash: the canonical link,og:url, the sitemap, the breadcrumbs, thehreflangalternates, and everyLink(to:),Sidebar.Item(to:)andnavigate()whose target is one of the site's pages (/contactbecomes/contact/). A file such as/cv.pdf, another origin, or an address worked out whole at run time is left as written.
Unset, the addresses are /contact and the files contact/index.html. That is right for a host that serves the directory without a redirect: Netlify, Cloudflare Pages, and Vercel with cleanUrls.
A checklist for being found
- Set
meta.site_url. Without it there are no canonical links, no sitemap and no absolute sharing URLs. - Give every page a
title:and adescription:of about 150 characters.S01–S03warn when one is missing or too long. - Pre-render with
build.ssg: true, so the text is in the HTML. - Use one
h1per page, with headings in order (A11,A12). - Give every shared page an
image:, or setmeta.imagefor the site — at 1200 × 630 pixels, which suits most previews — inpublic/, so its size is in the card, with animage_alt:(ormeta.image_alt) that says what it shows. - On GitHub Pages and hosts like it, set
build.clean_urls, so the canonical address never redirects. - For a personal site, set
meta.owner: "person", withjob_title,same_asand, for the rest of who they are,owner_details. - Serve web fonts from
public/, named inmeta.preload, instead of a font service's stylesheet. - Set
noindex: trueon pages that should not be found: sign-in, thanks, drafts. - Check the result: view a built page's source, and paste a URL into a link-preview debugger.