@scribe-platform/cli 0.9.1 → 0.11.0

package/skills/scribe-site-builder/recipes/seo.md

@@ -0,0 +1,193 @@
+# Recipe: being found
+
+> **The commands below are yours to run, not hers to read.** If she's asking
+> what this is or how to do it, answer it the way *Who you're talking to* in
+> [`../SKILL.md`](../SKILL.md) says to: what it is, what she'd say to get it,
+> what's her call, and an offer to do it now.
+
+Everything `scribe site seo <site>` checks, and how to make each one pass. Build
+a site with all of it and the check is a regression guard rather than a list of
+things to go and fix.
+
+**Run `scribe site seo <site>` before `scribe site promote`**, not after. Going
+live is the deadline for being findable, not the starting gun — and `promote`
+refuses on a failure, the same way it already refuses when DNS is not ready.
+
+Three checks (`sitemap`, `canonical`, `indexable`) skip until the site is on the
+client's own domain, because before the cutover those all correctly name
+`*.github.io`. That is expected, not a problem, and not something to fix.
+
+## The four files
+
+Almost everything here comes from four pieces. A site with all four passes all
+eleven checks.
+
+### 1. `site` in `astro.config.mjs`
+
+Nothing else works without it. Astro needs the site's real address to build
+absolute URLs, and a canonical or a sitemap entry that is not absolute is not
+valid.
+
+```js
+import { defineConfig } from 'astro/config';
+import sitemap from '@astrojs/sitemap';
+
+export default defineConfig({
+  // The live address. Set it to the client's domain from the start, even
+  // before the cutover — it is what the sitemap and every canonical are built
+  // from, and it is the one value that cannot be derived from the environment.
+  site: 'https://riversidedental.com',
+  base: process.env.PUBLIC_BASE_PATH || '/',
+  integrations: [sitemap()],
+});
+```
+
+`npm install @astrojs/sitemap` first. The integration writes `sitemap-index.xml`
+and `sitemap-0.xml` into `dist/` on every build, so the page list can never go
+stale the way a hand-written one does.
+
+### 2. `public/robots.txt`
+
+```
+User-agent: *
+Allow: /
+
+Sitemap: https://riversidedental.com/sitemap-index.xml
+```
+
+Three things the check looks for: that the file exists at all, that it does not
+carry a blanket `Disallow: /`, and that it names a `Sitemap:` line. A commented
+`# Sitemap:` does not count.
+
+### 3. A `<SeoHead>` component
+
+One component, used by every layout, so a page cannot be built that forgets
+half of it. This is the piece that covers five of the eleven checks at once.
+
+```astro
+---
+// src/components/SeoHead.astro
+interface Props {
+  title: string;
+  description: string;
+  /** Falls back to the site-wide card image. */
+  image?: string;
+}
+
+const { title, description, image = '/og-card.png' } = Astro.props;
+
+// Astro.site comes from astro.config.mjs. Astro.url.pathname is this page.
+const canonical = new URL(Astro.url.pathname, Astro.site);
+const imageUrl = new URL(image, Astro.site);
+---
+<title>{title}</title>
+<meta name="description" content={description} />
+<link rel="canonical" href={canonical} />
+
+<meta property="og:title" content={title} />
+<meta property="og:description" content={description} />
+<meta property="og:image" content={imageUrl} />
+<meta property="og:url" content={canonical} />
+<meta property="og:type" content="website" />
+```
+
+Then in the layout:
+
+```astro
+---
+import SeoHead from '../components/SeoHead.astro';
+const { title, description } = Astro.props;
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <SeoHead title={title} description={description} />
+  </head>
+  <body><slot /></body>
+</html>
+```
+
+**`lang="en"` on `<html>` is its own check** and is easy to drop when a layout
+gets rewritten.
+
+**Every page passes its own title and description.** Two pages sharing either
+one is a failure, not a warning — it is the normal result of a layout setting a
+default that a page forgets to override, and it cannot be seen by looking at any
+single page.
+
+### 4. The business, in structured data
+
+On the home page only. This is what puts a business in a local result rather
+than a plain blue link.
+
+```astro
+---
+const business = {
+  '@context': 'https://schema.org',
+  '@type': 'LocalBusiness',       // or a more specific type: Dentist, Plumber, HairSalon
+  name: 'Riverside Dental',
+  url: 'https://riversidedental.com',
+  telephone: '+1-717-555-0100',
+  address: {
+    '@type': 'PostalAddress',
+    streetAddress: '14 Market Street',
+    addressLocality: 'Lancaster',
+    addressRegion: 'PA',
+    postalCode: '17602',
+    addressCountry: 'US',
+  },
+  areaServed: 'Lancaster County, PA',
+};
+---
+<script type="application/ld+json" set:html={JSON.stringify(business)} />
+```
+
+`name`, `url` and `telephone` are what the check requires. The address and
+`areaServed` are not checked and are worth having anyway — they are most of what
+a local result is made of.
+
+**A business that does not want its street address public can leave
+`address` out** and keep `areaServed`. Google's own guidance is that a business
+customers do not visit should hide the address and declare a service area.
+
+**Do not mark up reviews you are displaying for yourself.** Google reserves
+review markup for a site reviewing *other* businesses, and a demo's placeholder
+five stars is exactly the thing that gets a site penalised.
+
+## The two smaller ones
+
+**`contactable`** — a phone number on the home page and on any contact page. A
+`tel:` link counts, and so does a plain number in the text. This exists because
+a real site went live with its number on four guide articles and on none of the
+pages anybody lands on.
+
+```astro
+<a href="tel:+17175550100">(717) 555-0100</a>
+```
+
+**`alt`** — every `<img>` needs an `alt` attribute. `alt=""` passes and is the
+correct markup for a decorative image; a *missing* attribute is the failure.
+
+## What the checks will not tell you
+
+Eleven checks are mechanical. The things that actually decide whether a site
+ranks are not, and `scribe site seo` ends by asking about them rather than
+pretending to measure them:
+
+- Does the site say which town and area the business serves, on the pages a
+  visitor lands on? A local business that never names its town is the single
+  most common reason one does not show up.
+- Is there real client proof — a name, a review, a photo of finished work —
+  rather than a placeholder?
+- Is there a page for each main thing they sell, rather than one page with
+  sections? One page cannot rank for six different searches.
+- Does the contact form sit next to a privacy policy, if it collects a name,
+  email or phone?
+- Would someone who has never heard of this business understand what it does
+  from the home page alone?
+- Is the business claimed on Google with the same name, address and phone number
+  as the site?
+
+Ask the client. "Not yet" is a real answer — the point is that it gets said
+before the site goes live, not that every site has all six.