SEO and the report
seo in site.config.ts sets the title, description, canonical and JSON-LD on every page, and
the build report checks the result. Never emitted: aggregateRating, review, FAQPage.
seo.templates holds titleTemplate and a title/description pair for home, listing,
category, tag, pseo and blog. Override any pair.
seo: { templates: { titleTemplate: '{title} | {siteName}', category: { title: 'Best {category} {nouns} ({count})', description: 'Compare {count} {category} {nouns}, hand-picked and updated for {year}.', }, },},Placeholders: {title}, {siteName}, {name}, {tagline}, {category}, {tag}, {count},
{noun}, {nouns}, {year} — the last two from routes.listingNoun. Anything else fails
pnpm check:config with unknown placeholder {x}.
site.url is baked into canonicals, the sitemap, the feeds and the OG image URLs at build
time: set your real domain before the first deploy. Page paths end in a trailing slash.
seo.jsonLd.listing picks the listing schema — software, product, organization,
localBusiness or none, defaulting from site.kind. jsonLd.organization,
jsonLd.breadcrumbs and jsonLd.itemList (default true) switch the Organization,
BreadcrumbList and ItemList blocks on and off.
Sitemap and robots
Section titled “Sitemap and robots”The build writes sitemap-index.xml plus sitemap-listings-0.xml (weekly, 0.8),
sitemap-taxonomy-0.xml (weekly, 0.7), sitemap-pseo-0.xml (weekly, 0.6),
sitemap-blog-0.xml (monthly, 0.5) and sitemap-pages-0.xml (/ daily, 1.0). Out of it:
/search/, /404/, every noindex page, anything under a Disallow: prefix, and file
endpoints such as /rss.xml.
/robots.txt is User-agent: *, one Disallow: per prefix, then
Sitemap: <site.url>/sitemap-index.xml. Fixed prefixes: /admin/, /api/, /_actions/,
/submit/, /search/, /login/, /signup/, /dashboard/, /account/, /auth/, plus seo.robots.disallow (default
/out/, /submit/status/) and /out/ when features.clicks is 'redirect'.
The build report
Section titled “The build report”pnpm build prints four lines:
seo-report: scanned N pages; L listings; X noindex; pseo P pages (best-category-for-tag=A, name-alternatives=B)seo-report: categories without pSEO coverage: noneseo-report: sitemap: N urls expected (blog=…, listings=…, pages=…, pseo=…, taxonomy=…) — dist sitemap matchesseo-report: inbound links per listing: min M; orphans (fewer than 2 inbound): 0 [strictLinks=on]The one failure is an orphan (a listing with fewer than 2 inbound pages) under
seo.strictLinks: true; the default false only warns
N orphan listing(s); set seo.strictLinks: true to fail the build on this.
seo-report: 1 orphan listing(s) with fewer than 2 inbound links (seo.strictLinks=true): /tools/my-tool/ (1 from /categories/writing/page/2/)Verify
Section titled “Verify”| Where | You should see | |
|---|---|---|
| Title, canonical, JSON-LD | view-source:https://<your domain>/<listingBase>/<slug>/ |
one <title>; a <link rel="canonical"> on your domain ending in a slash; JSON-LD naming the listing |
| Robots | https://<your domain>/robots.txt |
User-agent: *, the Disallow: lines, Sitemap: https://<your domain>/sitemap-index.xml |
| Sitemap | https://<your domain>/sitemap-index.xml |
one <loc> per chunk; sitemap-listings-0.xml lists your listings |
| The report | the build output | the four seo-report: lines, ending orphans (fewer than 2 inbound): 0 |
Worth knowing
Section titled “Worth knowing”- A
titleTemplateresult over 60 characters falls back to the bare page title, cut to 65 at a word boundary; descriptions cut to 160. noindex,followgoes on/search/,/submit/,/admin/and on a category or tag page with fewer listings thanseo.noindexBelow(default 2): built, but out of the sitemap.features.relatedLinks: falseempties the related block and can push listings under the orphan threshold.listing.relatedCountdefaults to 6.- Lighthouse (
pnpm lhci) runs afterpnpm build, not inside it: any category median — performance, accessibility, best practices, SEO — below 0.95 fails, reports in.lighthouseci/. - The same output prints
pseo:,budget:andzero-js:— Programmatic SEO, Cost and limits.
Configuration
Section titled “Configuration”seo.templates.titleTemplate and the per-kind templates, the four seo.jsonLd switches, seo.noindexBelow, seo.robots.disallow, seo.strictLinks, features.relatedLinks and listing.relatedCount — seo, features, listing.
Directorysrc/
Directorylib/
- seo.ts titles, canonical,
noindex, robots prefixes, sitemap chunks - jsonld.ts the JSON-LD builders
- paths.ts every URL, always with a trailing slash
- seo.ts titles, canonical,
- components/seo/Head.astro the head tags
- pages/robots.txt.ts
/robots.txt - features/related.ts the related-links engine
Directoryintegrations/
- sitemap.ts the chunked sitemap and its drop rules
- seo-report.ts the report and the orphan failure
- lighthouserc.cjs
pnpm lhci