# SEO Checklist + Best Practices

A working reference for arpartsfinder.com (site-ng). Two jobs:

1. **Checklist.** What we have, what's still to do, in rough priority
   order. Tick boxes as items land.
2. **Best-practices source.** New pages, new routes, new features
   should look at the principles below before merging, so we don't
   keep paying down the same gaps in future cleanups.

Companion docs:
[style.md](style.md) (voice and writing rules) ·
[cutover-checklist.md](cutover-checklist.md) (prod-migration only) ·
[end-state-ux.md](end-state-ux.md) (journey + features).

Last reviewed: 2026-06-02 (bucket reconciliation pass — found that
the 2026-05-31 SEO sprint shipped robots.txt + sitemap.xml + per-type
browse meta descriptions but the doc never marked them done; the
Bucket II/III groupings below are now updated to reflect actual code
state, not stale "to do" claims).

---

## Work buckets — the right next chunks to tackle

Three coherent groupings of the unchecked items below. Per-section
item references map to the detailed checklist further down.

### ✅ Bucket I — quick wins, no decisions, no new copy (COMPLETED 2026-06-02)

* A.2 `<link rel="canonical">` site-wide — already at base.html
* A.3 image `alt` on product thumbnails — wired 2026-06-02
* A.4 `<html lang="en">` — already in place
* A.5 no empty `<title>`/h1 fallbacks — audited, all child templates
  set their own
* D.4 (informal) `og:site_name=ARPartsFinder` — already site-wide
* E.5 `loading="lazy"` on thumbnails — already in place
* F.3 (partial) basic Organization JSON-LD — already in base.html;
  founder/logo/sameAs enhancements move to Bucket III

### ✅ Bucket II — site-wide infrastructure (LARGELY COMPLETED 2026-05-31, except as noted)

Originally framed as the next coherent commit. Verification on
2026-06-02 found that most of it was already shipped in a 2026-05-31
SEO sprint that didn't tick the underlying checkboxes. Updated
status:

* D.1 ✅ **`robots.txt`** — shipped via `ngsite/views/seo.py` (route
  `/robots.txt`). Verified live (HTTP 200 on staging).
* D.2 ✅ **`sitemap.xml`** auto-generator — shipped via the same
  blueprint. Enumerates home + static content + /browse?type=<each>
  + every public `/b/<code>` saved build. Verified live (~5 KB on
  staging).
* A.1 ✅ **Hand-written `<meta name="description">`** — fully shipped
  in the 2026-05-31 SEO sprint:
  * Per-page descriptions for home, /faq, /terms, /changelog —
    commit 125afde (one hand-written ~150-char block per template,
    page-specific content).
  * Per-type `/browse?type=X` descriptions — commit 81cde22
    (`TYPE_META_DESCRIPTIONS` dict in `ngsite/labels.py`, all 26
    type codes).
  * `/resources` had its own block from earlier work.
* H.1 ⏳ **Submit sitemap to Google Search Console** — Mike action only;
  agent can prep the sitemap URL but can't do the GSC submit.

**Remaining Bucket II work:** H.1 GSC submit (Mike action). Nothing
left in code.

### ⏳ Bucket III — needs copy decisions, your voice required (separate sessions)

Each item is its own conversation; not one commit.

* C.1 + C.2 ✅ **Per-type browse landing-page meta descriptions** —
  shipped 2026-05-31 via commit 81cde22 (`TYPE_META_DESCRIPTIONS`
  in `ngsite/labels.py`, all 26 type codes). Worth eyeballing each
  for voice + keyword fit since they were drafted in one batch — a
  per-type audit pass could lift quality without changing the
  scaffold.
* F.1 **About page** — real one, first-person, 13-year-track-record
  framing per [[site-core-purpose-restock-latency]]. Needs Mike's
  voice; no boilerplate. Mention panic-buying origin story.
* F.3 (enhancements) **Organization JSON-LD founder/logo/sameAs** —
  needs Mike's data: founder name (Person object), sameAs URLs
  (any social/forum presence), logo URL (file doesn't yet exist
  in static/, needs creation).
* G.* **Keyword strategy / positioning audit** — copy review across
  home / browse / build pages for AR-15+AR-10 framing, no stuffing,
  "search engine for in-stock AR parts" positioning consistency per
  [[positioning-comparison-engine-not-retailer]].

---

## Principles

The five things that drive almost every SEO decision for a site like
ours. When in doubt, work backwards from one of these.

1. **Every URL must be uniquely identifiable from its content.**
   The path, title, h1, and on-page content should all tell the
   same story. Google reads them together. A URL that says
   `/b/abc123` carries no signal on its own; one that says
   `/b/abc123/my-first-ar15-build` carries a lot.

2. **Backlinks compound, but only if the destination is set up to
   convert.** Every share on Reddit / forums / Discord is real
   link juice, but it's wasted if the landed page has a generic
   title, no meta description, no Open Graph card, no structured
   data. The on-page setup is what turns a backlink into a ranking.

3. **Brand reinforcement is cumulative.** Every browser tab,
   bookmark, and search snippet that says "ARPartsFinder" is
   building familiarity that pays off in direct traffic, repeat
   visits, and CTR on search results. Don't strip the brand for
   "cleaner" titles. Brand at END of title (`Page · ARPartsFinder`)
   is the modern best practice. See memory:
   [[brand-spelling-arpartsfinder]].

4. **Fresh content + real data is a moat.** Stockometer, retailer
   count, sparklines, /changelog, restock detection are signals
   that this site is alive in a way most affiliate junk isn't.
   Lean into them in titles, meta descriptions, and structured
   data. See memory: [[site-core-purpose-restock-latency]].

5. **Crawlability beats cleverness.** Server-rendered HTML, real
   `<a href>` links, sitemap, robots.txt that points at the
   sitemap. Don't put crawlable content behind JS-only routes.
   The whole site-ng architecture is already aligned with this
   (Flask + Jinja, not an SPA), don't backslide.

---

## What we already do well

Honest baseline, so the checklist below reads as additive rather
than starting from zero.

- [x] Server-rendered HTML (Flask + Jinja, no SPA). Every page is
  fully present in the initial response.
- [x] Mobile-friendly, responsive design.
- [x] HTTPS site-wide (via pair.com).
- [x] Clean canonical URL structure for browse: `/browse?type=...`
  always normalizes to the canonical path.
- [x] Brand in `<title>` site-wide, at the END (`Page · ARPartsFinder`),
  not stripped. See [[brand-spelling-arpartsfinder]].
- [x] Real, dynamic content (live stock, real retailer count,
  sparklines, /changelog). Google rewards fresh + unique data.
- [x] No em-dashes, consistent voice. Reads as human-written. See
  [style.md](style.md) and memory: [[feedback-no-emdash]].
- [x] Single `<h1>` per page, content-matched.
- [x] No login wall on browse or build pages. Crawlable.
- [x] /faq, /resources, /terms — real, original content (not
  boilerplate). Good for E-E-A-T signals.
- [x] /changelog page (just shipped, 2026-05-27). Recurring
  freshness signal both for users and for Google.

---

## Checklist

Grouped by area, rough priority within each.

### A. Per-page basics

For every public, indexable page.

- [x] ~~**Unique `<meta name="description">` on every page.**~~
      Fully shipped in the 2026-05-31 SEO sprint:
      home + /faq + /terms + /changelog all override the default
      block (commit 125afde, hand-written ~150-char page-specific
      strings each). Per-type `/browse?type=X` shipped same sprint
      (commit 81cde22, `TYPE_META_DESCRIPTIONS` for all 26 type
      codes in `ngsite/labels.py`). `/resources` had its own block
      from earlier work.
- [x] ~~**`<link rel="canonical">` on every page.**~~ Done at the
      base.html level — auto-derived from `public_url_root +
      request.path`. Templates can override via `{% block
      canonical_url %}` where needed (e.g. /browse normalizing
      query-param variants).
- [x] ~~**Image `alt` attributes on all product thumbnails.**~~
      Wired 2026-06-02. Both parts_grid and parts_table thumbnails
      (including the hover/click-zoom popup imgs) now carry
      `alt="{{ p.description }}"`. The 4 spots that were `alt=""`
      are populated; uses the full product description rather than
      a truncation — short enough to be useful for screen-readers,
      identical to what assistive tech would announce on the title
      link anyway.
- [x] ~~**`<html lang="en">` on every page.**~~ Verified
      2026-06-02; already set at base.html line 2.
- [x] ~~**No empty `<title>` or h1 fallbacks.**~~ Audited
      2026-06-02 — every child template that extends base.html sets
      its own `{% block title %}`, no template falls through to the
      bare "ARPartsFinder" default.

### B. Build URLs — biggest opportunity

The killer-feature insight: every saved build that gets shared is a
backlink to us. Set up the destination page to convert that backlink
into a ranking. See memory: [[feature-site-share-builds]].

- [ ] **Slugged URLs.** `/b/<code>/<name-slug>` instead of bare
      `/b/<code>`. Bare form still works (301 to slugged form).
      The slug carries the build name into the URL itself.
- [ ] **Per-build `<title>`.** Format like `<name> — AR build with
      <category-1>, <category-2>, ... · ARPartsFinder` (no em-dash;
      use a comma or period per style.md). Drives search-snippet
      text and tab recognition.
- [ ] **Per-build `<meta description>`.** "<N>-part AR build
      including a <type> from <retailer>, total <$X>. Compare to
      similar builds at ARPartsFinder." Hand-built from the build's
      item list.
- [ ] **Open Graph + Twitter Card tags.** `og:title`, `og:description`,
      `og:image` (the first product thumbnail, or a generated kit
      summary card), `og:type=article`, `og:site_name=ARPartsFinder`.
      Drives real CTR from Reddit / Discord / Twitter / forum shares.
- [ ] **JSON-LD ItemList structured data.** Schema.org `ItemList`
      with each build item as a `ListItem` containing the
      `Product`'s name, price, availability, and seller. Eligible
      for richer Google results.
- [ ] **`robots` meta tag deliberate.** Decide and document: do
      we want anonymous, never-revisited drafts indexed? Probably
      not. Add `<meta name="robots" content="noindex">` to public
      pages of builds older than X days with zero updates, OR
      noindex anything that's an obvious throwaway draft. Avoids
      diluting the index with low-value pages.

### C. Browse and category pages

Long-tail keyword opportunity ("AR-15 stripped uppers in stock",
"PSA complete lowers price", "AR-10 BCG comparison", etc.)

- [ ] **Per-type landing-page title.** `/browse?type=strippedupper`
      currently says `Stripped Uppers in stock · ARPartsFinder` (good
      start). Audit each type and refine: "<Label> in stock — N
      retailers, live prices" or similar. Match real search intent.
- [x] ~~**Per-type meta description.** Hand-written, ~150 chars.
      Include the type name and "AR-15 and AR-10" naturally.~~
      Shipped 2026-05-31 (commit 81cde22): `TYPE_META_DESCRIPTIONS`
      dict in `ngsite/labels.py` covers all 26 type codes. Worth
      eyeballing per type for voice + keyword fit since drafted in
      one batch.
- [ ] **Internal linking between related categories.** Stripped
      uppers should link to complete uppers and BCGs. Sidebar
      already does this; consider an in-content "Related" strip
      on browse pages for SEO benefit beyond UX.
- [ ] **Future /product/<id> page.** When built (deferred per
      sparkline / TODO.md note), add Schema.org `Product` markup
      with `Offers` for each retailer carrying it. Eligible for
      Google Shopping-style rich results.

### D. Site-wide infrastructure

- [x] ~~**`robots.txt`.**~~ Shipped 2026-05-31 via
      `ngsite/views/seo.py` `/robots.txt` route. Allows public
      content; blocks `/draft/`, `/admin/`, `/build` working-draft,
      `/login`, user-specific paths; points at sitemap. Verified
      live (HTTP 200 on staging).
- [x] ~~**`sitemap.xml`.**~~ Shipped 2026-05-31 via same blueprint.
      Auto-generates home + static content + /browse?type=<each> +
      every public `/b/<code>` saved build. Verified live (~5 KB on
      staging).
- [ ] **Submit sitemap to Google Search Console.** Mike action; no
      code involved.
- [x] ~~**`og:site_name=ARPartsFinder` site-wide.**~~ Already in
      place at base.html line 24 — along with og:type, og:title,
      og:description, og:url (all defaulting from the page's title
      / meta_description / canonical_url blocks).
- [ ] **`<link rel="alternate">` for any mobile/desktop split URLs.**
      We don't have these today (responsive single URL), but if we
      ever do (AMP, m. subdomain), wire correctly.

### E. Performance

Core Web Vitals are a real ranking signal. Don't ignore them just
because we're a low-traffic site today.

- [ ] **LCP (Largest Contentful Paint) under 2.5s.** Big drivers:
      Tailwind Play CDN currently ships ~3 MB of unused CSS to
      every page. Compile Tailwind for prod (build step) and ship
      ~50 KB of used CSS instead. See [[cutover-checklist]] section
      E.
- [ ] **CLS (Cumulative Layout Shift) under 0.1.** Audit: product
      thumbnails need explicit width/height to prevent shift.
- [ ] **INP (Interaction to Next Paint) under 200ms.** htmx + small
      partial swaps already help. Verify on mobile.
- [ ] **Cache-Control headers** on static assets (favicon, CSS,
      images). Pair.com mod_passenger setup; verify config.
- [x] ~~**Image lazy-loading (`loading="lazy"`)** on below-the-fold
      product thumbnails.~~ Verified 2026-06-02 — already set on
      both parts_grid and parts_table thumbnail imgs (including
      the popup/zoom imgs).

### F. Trust + E-E-A-T signals

Google's "Experience, Expertise, Authoritativeness, Trustworthiness"
rubric for who to rank above whom. We have a strong story here that
we don't currently surface.

- [ ] **About page.** Real one, not boilerplate. Mike has been
      doing AR parts availability since 2013 — that's a 13-year
      track record Google rewards. First-person, plain language.
      Mention the panic-buying origin story (see memory:
      [[site-core-purpose-restock-latency]]).
- [x] **Privacy policy + Terms.** Done, real and accurate (not
      template).
- [x] **Contact methods.** /faq has them.
- [ ] **Author / organization Schema.org markup.** JSON-LD
      `Organization` block on the home page: founded year, founder
      name, sameAs links to any social presence, logo URL. One
      block at base.html level. PARTIALLY DONE — base.html already
      emits a basic Organization block with `name`, `url`,
      `description`, and `foundingDate=2013`. Still pending and
      needs Mike's data: founder name (Person object), `sameAs`
      array (any social/forum presence URLs), `logo` URL (no logo
      file exists in static/ yet — needs creation).
- [ ] **Public changelog (this is great for E-E-A-T).** Done —
      /changelog signals "this site is being actively worked on."

### G. Content and keyword strategy

Light touch, since aggressive keyword strategy turns into stuffing.

- [ ] **"AR-15 and AR-10" appears naturally in primary copy on
      home, browse, build.** We're not AR-15-only; the dual-platform
      coverage is a real differentiator. See memory:
      [[scope-ar15-and-ar10]].
- [ ] **Avoid keyword stuffing.** If you find yourself repeating
      a keyword 4+ times on a page in non-natural prose, stop.
      Google penalizes this.
- [ ] **Positioning kept clean.** "Search engine for in-stock AR
      parts" beats "shop for AR parts" — be specifically not-a-store
      (see memory: [[positioning-comparison-engine-not-retailer]]).
      Avoids competing for impossible-to-win retail queries and
      wins the comparison/search-tool query.

### H. Measurement

You can't improve what you don't measure.

- [ ] **Google Search Console** set up, verified, sitemap submitted.
- [ ] **Quarterly review** of: which queries land users on the
      site, click-through rate per query, pages with high
      impressions but low CTR (those are titles/descriptions that
      need rewriting).
- [ ] **Track top-10 entry pages.** Make sure the top entry pages
      have the strongest title/description/structured-data setup.
- [ ] **Optional: server log analysis** to see which pages
      Googlebot actually crawls vs which we want it to crawl.

---

## Best practices for future development

Add these checks to the workflow for new pages / routes / features
so we don't keep paying down the same SEO gaps.

**When adding a new public route:**

- Unique `<title>` (with brand at end) and `<meta description>`
  before merging.
- Single `<h1>`, content-matched to the title.
- Add to `sitemap.xml` generator if it should be indexed; explicitly
  noindex if it shouldn't.
- Decide whether it needs canonical handling (does it have query
  param variants?).

**When adding a new feature with shareable URLs:**

- Slug the URL with human-readable content where possible.
- Open Graph + Twitter Card tags so external previews look good.
- JSON-LD if there's structured content (a list, a product, an
  article).
- Stable URLs forever. Use 301 redirects if you must restructure.

**When adding new copy anywhere:**

- Follow [style.md](style.md). No em-dashes, brand spelled
  ARPartsFinder, dual AR-15/AR-10 framing where relevant.
- One keyword per page max as the focus. Don't try to rank a single
  page for everything.

**When refactoring URLs:**

- Never break a URL that's already public. 301 redirect the old
  URL to the new one for at least 12 months.
- Update the sitemap.
- Check internal links: search the codebase for the old URL pattern
  before merging.

**When adding images:**

- Always include an `alt` attribute. Real description, not "image"
  or empty.
- Set explicit `width` and `height` to avoid CLS.
- Use `loading="lazy"` on below-the-fold images.

---

## Open questions / decisions deferred

- Are anonymous, never-claimed draft builds worth indexing at all?
  Probably noindex everything until a build is saved + given a
  name. Revisit when we have data on what's getting shared.
- AMP pages? Probably not. Google deprioritizes AMP now and the
  responsive site is already mobile-friendly.
- Subdomain vs subdirectory for the sister sites? They share
  infrastructure (memory: [[sister-sites-shared-infrastructure]])
  but for SEO each is its own property. Probably keep separate
  domains (handgunfinder.com, etc.).
