seo 0.13.2 → 0.14.0

package/site-kit/starter/src/lib/parks.ts

@@ -0,0 +1,84 @@
+import parksData from '../data/parks.json'
+import sourcesData from '../data/sources.json'
+
+export type Park = {
+  slug: string
+  name: string
+  region: string
+  areaHectares: number
+  opened: number
+  toilets: boolean
+  cafe: boolean
+  playground: boolean
+  dogs: 'yes' | 'on leads' | 'no'
+  // null means the register does not say. 0 means no parking.
+  parkingSpaces: number | null
+  source: string
+}
+
+export type Source = {
+  id: string
+  name: string
+  url: string
+  checked: string
+}
+
+export const parks = (parksData as Park[])
+  .slice()
+  .sort((a, b) => a.name.localeCompare(b.name))
+const sources = sourcesData as Source[]
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+export function sourceFor(park: Park): Source {
+  const source = sources.find((entry) => entry.id === park.source)
+  if (!source) throw new Error(`${park.slug}: unknown source ${park.source}`)
+  return source
+}
+
+export type Region = { name: string; slug: string; parks: Park[] }
+
+export const regions: Region[] = [...new Set(parks.map((park) => park.region))]
+  .sort((a, b) => a.localeCompare(b))
+  .map((name) => ({
+    name,
+    slug: slugify(name),
+    parks: parks.filter((park) => park.region === name),
+  }))
+
+export function regionFor(park: Park): Region {
+  const region = regions.find((entry) => entry.name === park.region)
+  if (!region) throw new Error(`${park.slug}: unknown region`)
+  return region
+}
+
+export function formatHectares(value: number): string {
+  return `${value.toLocaleString('en-GB', { maximumFractionDigits: 1 })} hectares`
+}
+
+export function formatDate(iso: string): string {
+  return new Date(`${iso}T00:00:00Z`).toLocaleDateString('en-GB', {
+    day: 'numeric',
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC',
+  })
+}
+
+export function facilities(park: Park): string[] {
+  return [
+    park.toilets ? 'toilets' : '',
+    park.cafe ? 'a cafe' : '',
+    park.playground ? 'a playground' : '',
+  ].filter(Boolean)
+}
+
+export function listText(items: string[]): string {
+  if (items.length <= 1) return items.join('')
+  return `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`
+}

package/site-kit/starter/src/lib/seo.ts

@@ -0,0 +1,97 @@
+import {
+  assembleGraph,
+  buildBreadcrumbList,
+  buildPiece,
+  buildWebPage,
+  buildWebSite,
+  type GraphEntity,
+  makeIds,
+} from '@iannuttall/seo-graph-core'
+import { absoluteUrl, site } from '../site'
+
+export type Breadcrumb = { name: string; path: string }
+export type Faq = { question: string; answer: string }
+
+const ids = makeIds({ siteUrl: site.url })
+const organisationId = ids.organization('site')
+
+// One JSON-LD graph per page. Mark up only what the page shows.
+export function pageGraph(input: {
+  name: string
+  description: string
+  path: string
+  breadcrumbs: Breadcrumb[]
+  faqs?: Faq[]
+}) {
+  const url = absoluteUrl(input.path)
+  const faqId = input.faqs?.length ? `${url}#faq` : null
+  // A breadcrumb trail needs two steps. The home page has none.
+  const crumbs = input.breadcrumbs.length > 1
+  const pieces: GraphEntity[] = [
+    buildPiece({
+      '@type': 'Organization',
+      '@id': organisationId,
+      name: site.name,
+      url: absoluteUrl('/'),
+    }),
+    buildWebSite(
+      {
+        url: absoluteUrl('/'),
+        name: site.name,
+        description: site.description,
+        publisher: { '@id': organisationId },
+        inLanguage: site.language,
+      },
+      ids,
+    ),
+    buildWebPage(
+      {
+        url,
+        name: input.name,
+        description: input.description,
+        isPartOf: { '@id': ids.website },
+        ...(crumbs ? { breadcrumb: { '@id': ids.breadcrumb(url) } } : {}),
+        inLanguage: site.language,
+        ...(faqId ? { mainEntity: [{ '@id': faqId }] } : {}),
+      },
+      ids,
+    ),
+  ]
+  if (crumbs) {
+    pieces.push(
+      buildBreadcrumbList(
+        {
+          url,
+          items: input.breadcrumbs.map((item) => ({
+            name: item.name,
+            url: absoluteUrl(item.path),
+          })),
+        },
+        ids,
+      ),
+    )
+  }
+  if (faqId && input.faqs) {
+    pieces.push(
+      buildPiece({
+        '@type': 'FAQPage',
+        '@id': faqId,
+        isPartOf: { '@id': ids.webPage(url) },
+        mainEntity: input.faqs.map((faq) => ({
+          '@type': 'Question',
+          name: faq.question,
+          acceptedAnswer: { '@type': 'Answer', text: faq.answer },
+        })),
+      }),
+    )
+  }
+  return assembleGraph(pieces)
+}
+
+// Safe inside an inline script element.
+export function serializeGraph(graph: unknown): string {
+  return JSON.stringify(graph)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}

package/site-kit/starter/src/pages/404.astro

@@ -0,0 +1,30 @@
+---
+import '../styles/globals.css'
+import Button from '../components/Button.astro'
+import Footer from '../components/Footer.astro'
+import Header from '../components/Header.astro'
+import PageHeader from '../components/PageHeader.astro'
+import { site } from '../site'
+---
+
+<!doctype html>
+<html lang={site.language}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Page not found | {site.name}</title>
+    <meta name="robots" content="noindex" />
+    <meta name="color-scheme" content="light dark" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body class="min-h-screen bg-background text-foreground antialiased">
+    <div class="flex min-h-screen flex-col">
+      <Header />
+      <main id="main" class="site-frame flex-1 py-10">
+        <PageHeader title="Page not found" description="This page does not exist. Every park is listed on the home page." />
+        <Button href="/">Find a park</Button>
+      </main>
+      <Footer />
+    </div>
+  </body>
+</html>

package/site-kit/starter/src/pages/about.astro

@@ -0,0 +1,39 @@
+---
+// The methodology page. Say where each number comes from and how it is
+// worked out, so people can trust and cite the site.
+import sources from '../data/sources.json'
+import PageHeader from '../components/PageHeader.astro'
+import Base from '../layouts/Base.astro'
+import { formatDate } from '../lib/parks'
+import { site } from '../site'
+---
+
+<Base
+  title="Where the data comes from"
+  description={`The sources behind ${site.name}, when each one was last checked, and how the comparisons on every park page are worked out.`}
+  breadcrumbs={[{ name: 'About the data', path: '/about' }]}
+>
+  <PageHeader
+    title="Where the data comes from"
+    description={`Every fact on ${site.name} comes from a public register. Each page shows the source and the date it was last checked, and the site is rebuilt when a source changes.`}
+  />
+
+  <article class="site-prose">
+    <h2>Sources</h2>
+    <ul>
+      {
+        sources.map((source) => (
+          <li>
+            <a href={source.url} rel="noreferrer" target="_blank">{source.name}</a>, checked {formatDate(source.checked)}
+          </li>
+        ))
+      }
+    </ul>
+    <h2>How the comparisons are worked out</h2>
+    <p>
+      Sizes are compared with the other parks in the same region. A park is called larger or smaller only when the
+      difference is at least half again, and the page leaves the comparison out when the gap is smaller.
+    </p>
+    <p>When the register does not list a fact, such as parking, the page says so and never guesses a value.</p>
+  </article>
+</Base>

package/site-kit/starter/src/pages/index.astro

@@ -0,0 +1,52 @@
+---
+import { Location01Icon, Tree02Icon } from '@hugeicons/core-free-icons'
+import Card from '../components/Card.astro'
+import PageHeader from '../components/PageHeader.astro'
+import SectionHeading from '../components/SectionHeading.astro'
+import Base from '../layouts/Base.astro'
+import { formatHectares, parks, regions } from '../lib/parks'
+import { site } from '../site'
+
+const largest = [...parks].sort((a, b) => b.areaHectares - a.areaHectares).slice(0, 4)
+---
+
+<Base title={site.name} description={site.description}>
+  <PageHeader
+    title="Parks in the example parks register"
+    description={`The register lists ${parks.length} parks across ${regions.length} regions. Each page gives the size, the year the park opened, its toilets, cafe and playground, the dog rules and the car park, with the source and the date it was checked.`}
+  />
+
+  <section class="mt-16" aria-labelledby="regions">
+    <SectionHeading id="regions" title="Find a park by region" text="Every region has its own page with all of its parks side by side." />
+    <div class="grid grid-cols-1 gap-2 sm:grid-cols-2">
+      {
+        regions.map((region) => (
+          <Card
+            icon={Location01Icon}
+            title={region.name}
+            text={`${region.parks.length} parks, ${formatHectares(region.parks.reduce((sum, park) => sum + park.areaHectares, 0))} in total.`}
+            href={`/regions/${region.slug}`}
+            link={`Parks in ${region.name}`}
+          />
+        ))
+      }
+    </div>
+  </section>
+
+  <section class="mt-16" aria-labelledby="largest">
+    <SectionHeading id="largest" title="The largest parks" text="The biggest parks in the register by area." />
+    <div class="grid grid-cols-1 gap-2 sm:grid-cols-2">
+      {
+        largest.map((park) => (
+          <Card
+            icon={Tree02Icon}
+            title={park.name}
+            text={`${formatHectares(park.areaHectares)} in ${park.region}, opened in ${park.opened}.`}
+            href={`/parks/${park.slug}`}
+            link={`${park.name} facts`}
+          />
+        ))
+      }
+    </div>
+  </section>
+</Base>

package/site-kit/starter/src/pages/parks/[slug].astro

@@ -0,0 +1,95 @@
+---
+// The golden page. Every park page comes from this one template, and each
+// block shows only when the data has something to say.
+import { Tree02Icon } from '@hugeicons/core-free-icons'
+import Card from '../../components/Card.astro'
+import FactTable from '../../components/FactTable.astro'
+import FaqAccordion from '../../components/FaqAccordion.astro'
+import PageHeader from '../../components/PageHeader.astro'
+import Base from '../../layouts/Base.astro'
+import { answer, faqs, story } from '../../lib/narrative'
+import { formatHectares, type Park, parks, regionFor, sourceFor } from '../../lib/parks'
+
+export function getStaticPaths() {
+  return parks.map((park) => ({ params: { slug: park.slug }, props: { park } }))
+}
+
+const { park } = Astro.props as { park: Park }
+const region = regionFor(park)
+const source = sourceFor(park)
+const questions = faqs(park)
+const nearby = region.parks.filter((entry) => entry.slug !== park.slug).slice(0, 4)
+const yesNo = (value: boolean) => (value ? 'Yes' : 'No')
+const rows = [
+  { label: 'Size', value: formatHectares(park.areaHectares) },
+  { label: 'Opened', value: String(park.opened) },
+  { label: 'Toilets', value: yesNo(park.toilets) },
+  { label: 'Cafe', value: yesNo(park.cafe) },
+  { label: 'Playground', value: yesNo(park.playground) },
+  {
+    label: 'Dogs',
+    value: park.dogs === 'yes' ? 'Allowed' : park.dogs === 'on leads' ? 'On leads' : 'Not allowed',
+  },
+  {
+    label: 'Car park',
+    value:
+      park.parkingSpaces === null
+        ? 'Not listed'
+        : park.parkingSpaces === 0
+          ? 'None'
+          : `${park.parkingSpaces} spaces`,
+  },
+]
+const title = `${park.name}, ${park.region}`
+const description = `Size, opening year, toilets, parking and dog rules for ${park.name} in ${park.region}, from the parks register with the date it was checked.`
+---
+
+<Base
+  title={title}
+  description={description}
+  breadcrumbs={[
+    { name: region.name, path: `/regions/${region.slug}` },
+    { name: park.name, path: `/parks/${park.slug}` },
+  ]}
+  faqs={questions}
+>
+  <PageHeader title={park.name} description={answer(park)} />
+
+  <FactTable heading={`${park.name} at a glance`} rows={rows} source={source} />
+
+  <article class="site-prose mt-12">
+    <h2>How {park.name} compares</h2>
+    {story(park).map((sentence) => <p>{sentence}</p>)}
+  </article>
+
+  <section class="mt-12" aria-labelledby="visiting">
+    <h2 id="visiting" class="mb-4 text-xl/7 font-medium text-foreground">Visiting {park.name}</h2>
+    <FaqAccordion items={questions} />
+  </section>
+
+  {
+    nearby.length > 0 && (
+      <section class="mt-12" aria-labelledby="nearby">
+        <h2 id="nearby" class="mb-4 text-xl/7 font-medium text-foreground">Other parks in {region.name}</h2>
+        <div class="grid grid-cols-1 gap-2 sm:grid-cols-2">
+          {nearby.map((entry) => (
+            <Card
+              icon={Tree02Icon}
+              title={entry.name}
+              text={`${formatHectares(entry.areaHectares)}, opened in ${entry.opened}.`}
+              href={`/parks/${entry.slug}`}
+              link={`${entry.name} facts`}
+            />
+          ))}
+        </div>
+        <p class="mt-4 text-base text-foreground-muted">
+          See{' '}
+          <a class="text-primary underline underline-offset-4 hover:text-primary-hover" href={`/regions/${region.slug}`}>
+            every park in {region.name}
+          </a>
+          .
+        </p>
+      </section>
+    )
+  }
+</Base>

package/site-kit/starter/src/pages/regions/[region].astro

@@ -0,0 +1,58 @@
+---
+// A hub page: a real page with its own data, linking to every child.
+import PageHeader from '../../components/PageHeader.astro'
+import Base from '../../layouts/Base.astro'
+import { facilities, formatHectares, listText, type Region, regions } from '../../lib/parks'
+
+export function getStaticPaths() {
+  return regions.map((region) => ({ params: { region: region.slug }, props: { region } }))
+}
+
+const { region } = Astro.props as { region: Region }
+const total = region.parks.reduce((sum, park) => sum + park.areaHectares, 0)
+const largest = [...region.parks].sort((a, b) => b.areaHectares - a.areaHectares)[0]
+const withToilets = region.parks.filter((park) => park.toilets).length
+const title = `Parks in ${region.name}`
+const description = `The ${region.parks.length} parks in ${region.name}, with their size, opening year, facilities and dog rules, from the parks register.`
+const lead = [
+  `${region.name} has ${region.parks.length} parks covering ${formatHectares(total)} in total.`,
+  largest ? `The largest is ${largest.name} at ${formatHectares(largest.areaHectares)}.` : '',
+  `${withToilets} of them ${withToilets === 1 ? 'has' : 'have'} public toilets.`,
+]
+  .filter(Boolean)
+  .join(' ')
+---
+
+<Base title={title} description={description} breadcrumbs={[{ name: region.name, path: `/regions/${region.slug}` }]}>
+  <PageHeader title={title} description={lead} />
+
+  <article class="site-prose">
+    <h2>Every park in {region.name}</h2>
+    <div class="table-frame">
+      <table>
+        <thead>
+          <tr>
+            <th scope="col">Park</th>
+            <th scope="col">Size</th>
+            <th scope="col">Opened</th>
+            <th scope="col">Facilities</th>
+          </tr>
+        </thead>
+        <tbody>
+          {
+            region.parks.map((park) => (
+              <tr>
+                <td>
+                  <a href={`/parks/${park.slug}`}>{park.name}</a>
+                </td>
+                <td>{formatHectares(park.areaHectares)}</td>
+                <td>{park.opened}</td>
+                <td>{listText(facilities(park)) || 'None listed'}</td>
+              </tr>
+            ))
+          }
+        </tbody>
+      </table>
+    </div>
+  </article>
+</Base>

package/site-kit/starter/src/pages/robots.txt.ts

@@ -0,0 +1,16 @@
+import { absoluteUrl, site } from '../site'
+
+// Open to every crawler. Content-Signal says what the content may be used
+// for: search and AI answers always, AI training only when the site owner
+// chose it in site.config.json.
+export function GET() {
+  const body = [
+    'User-agent: *',
+    'Allow: /',
+    `Content-Signal: search=yes, ai-input=yes, ai-train=${site.aiTraining ? 'yes' : 'no'}`,
+    '',
+    `Sitemap: ${absoluteUrl('/sitemap.xml')}`,
+    '',
+  ].join('\n')
+  return new Response(body, { headers: { 'Content-Type': 'text/plain' } })
+}

package/site-kit/starter/src/site.ts

@@ -0,0 +1,29 @@
+import config from '../site.config.json'
+
+export const site = {
+  ...config,
+  url: `https://${config.domain}`,
+  footerNote:
+    'Facts from public records, each with its source and the date it was checked.',
+}
+
+// The header and footer links. Every page they name must exist.
+export const nav = [
+  { label: 'All parks', href: '/' },
+  { label: 'About the data', href: '/about' },
+]
+
+export const footerLinks = [
+  { label: 'Home', href: '/' },
+  { label: 'About the data', href: '/about' },
+]
+
+// The title tag adds the site name only when the whole title still fits.
+export function pageTitle(title: string): string {
+  const full = `${title} | ${site.name}`
+  return title === site.name || full.length > 60 ? title : full
+}
+
+export function absoluteUrl(path: string): string {
+  return new URL(path, site.url).toString()
+}