HTML pages should carry SEO and social meta tags
On this page
Surface a WARN when HTML pages are missing the standard SEO + social meta set:
<meta name="description">- search-result snippet<link rel="canonical">- duplicate-content / pagination signal<meta property="og:title">- link preview title<meta property="og:description">- link preview description<meta property="og:image">- link preview image
These are not technically required, but every one missing degrades how the page appears in search results, Slack/Discord/Teams unfurls, and link cards.
Companion to convention/html-required-meta. That frame catches the indisputably-required tags (charset / viewport / title); this one catches the should-have tags.
What counts as a page#
Only whole documents that search engines index are checked:
- an
.html/.htm/.astrofile with an<html>or<head>tag (fragments get their meta from the page they are loaded into); - not one that opts out with
<meta name="robots" content="noindex">; - not an error page (
404.html,500.html,50x.html,+error.svelte); - not SvelteKit’s
app.htmlshell (%sveltekit.head%is filled per route); - a
.svelteroute only when its own<svelte:head>sets at least one of these tags - one that sets none leaves SEO to its layout, one that sets some must set all.
Files under test-fixture and test-suite folders and under hidden folders
(.superpowers/, .private/; .well-known/ excepted) are skipped.
Site generator templates#
Template fragments of a static site generator are skipped: files under
Hugo’s layouts/ (next to hugo.toml, config.toml or another Hugo config)
and Jekyll’s _layouts/ and _includes/ (next to _config.yml). They are
pieces of a page, not pages; the built output (for example public/) is
checked instead. A layouts/ folder without the generator’s config beside it
is checked as usual.
Fix#
In SvelteKit, template the SEO meta in your root +layout.svelte:
<script lang="ts">
export let data: { title: string; description: string; image?: string };
</script>
<svelte:head>
<title>{data.title}</title>
<meta name="description" content={data.description} />
<link rel="canonical" href={`https://example.com${$page.url.pathname}`} />
<meta property="og:title" content={data.title} />
<meta property="og:description" content={data.description} />
<meta property="og:image" content={data.image ?? 'https://example.com/default-og.png'} />
</svelte:head>
Per-route layouts can override with their own <svelte:head> block - SvelteKit merges them. (This frame doesn’t follow that chain; it judges each file in isolation. A route that overrides only some of the tags, relying on the layout for the rest, can be suppressed with appframes:disable.)
Suppressing intentional cases#
<!-- appframes:disable web/html-seo-meta -->
<!-- SEO meta lives in +layout.svelte; this route inherits. -->
For partial templates, error pages, and other artifacts where SEO meta doesn’t apply, the file-level disable is the right tool.
WARN lets the push through and records the finding. Turn frames on per repo on the dashboard's Policy page - see choosing what the gate checks.
Source on GitHub Live demo How it works Questions: contact@nimblegate.com