docs(seo): full SEO + standards cleanup (consolidated) by Komsomol · Pull Request #263 · Fliplet/fliplet-cli

Komsomol · 2026-05-06T09:12:53Z

Summary

Consolidated PR — supersedes #260, #261, #262 (now closed). Full SEO + standards cleanup against master.

Four logical layers in commit history:

Tier 1 — SEO meta tags: activates jekyll-seo-tag, emits canonical / og:* / twitter:card / JSON-LD on every page. Rewrites canonical to no-extension form to match sitemap.
Tier 2 — URL canonicalisation: strips .html from 122 internal hrefs in the layout, overrides jekyll-sitemap output to emit clean URLs, updates robots.txt, mass-rewrites .md link targets in markdown source (code blocks preserved).
Tier 3 — content polish: noindex on 5 stub pages, ?source=hero removed from hero buttons, alt text on 5 images, second H1 → H2 on coding-standards.
Tier 4 — standards cleanup: HSTS / X-Frame / Permissions-Policy in _headers, SRI on every CDN asset, jQuery 3.3.1→3.7.1 (closes 3 CVEs), FontAwesome 5.5.0→5.15.4, animate.css 3.7.0→3.7.2, removes dead UA-35892004-23 tracking, fixes 5 long-standing HTML validity bugs, semantic HTML5 (<main>, <nav>), loading="lazy" on flagged images, custom /404 page, declared favicon link.

Coverage of Ahrefs audit

Of the original 1,681 issues, ~94% addressed in this PR (1,575+). Remaining ~6%:

~70 from the Cloudflare cdn-cgi/l/email-protection 404s — needs a CF dashboard toggle (Scrape Shield → Email Address Obfuscation off), not a code change. Tony to action.
~32 per-page meta-description rewrites (too short / too long) — content task per page, deferred.

Out of scope (separate PRs / actions)

GDPR cookie-consent banner — Lisa raising
CSP — needs careful policy with all our 3rd-party CDN scripts; own PR
instantsearch.js v2 → v4 + docsearch.js v2 → v3 — search-flow rewrites; own PR
FontAwesome 5 → 6, animate.css 3 → 4 — major-version icon/class breaks; own PR

Preview URL

CF Pages auto-builds this branch. Use this URL for Ahrefs re-crawl + Lighthouse + securityheaders.com:

https://docs-seo-standards-cleanup.fliplet-cli.pages.dev

Build verification (Docker, Ruby 2.7, github-pages 232 stack)

✅ jQuery 3.7.1 in built output
✅ 8 SRI hashes on CDN assets
✅ 0 references to UA-35892004-23 / analytics.js / gtag/js
✅ 2 GTM references preserved (head + noscript iframe)
✅ 0 stray </a> / 0 missing </a> in layout
✅ Favicon <link> emitted
✅ _site/404.html built with noindex + proper title
✅ <main>, <nav id="poc">, <nav aria-label="Site"> all present
✅ 5 loading="lazy" images
✅ Canonical points to clean (no-.html) URL
✅ 0 Liquid errors
✅ Agent-index pipeline runs clean (17 docs, 404 excluded)
✅ 87/87 unit tests pass
✅ All 5 security headers live on preview

Pre-merge retest matrix

Run against https://docs-seo-standards-cleanup.fliplet-cli.pages.dev:

Tool	Expected outcome
Ahrefs Site Audit (re-crawl)	Health 49 → ~90+, ~94% issue reduction
`securityheaders.com`	Grade A or A+ (all 5 headers present)
Lighthouse (Chrome DevTools)	Performance 90+, Accessibility 95+, SEO 100, Best Practices 100
W3C Nu HTML validator	the 5 layout HTML-validity bugs are gone
Manual smoke: nav, sidebar, search, hero buttons, code blocks, mobile	nothing visually regressed

🤖 Generated with Claude Code

cloudflare-workers-and-pages · 2026-05-06T09:13:29Z

Deploying fliplet-cli with Cloudflare Pages

Latest commit:	`cf37989`
Status:	✅ Deploy successful!
Preview URL:	https://dc287a04.fliplet-cli.pages.dev
Branch Preview URL:	https://docs-seo-standards-cleanup.fliplet-cli.pages.dev

View logs

Activates jekyll-seo-tag (already bundled with github-pages) to emit canonical, og:*, twitter:card, and JSON-LD on every page. - _config.yml: add site-level title, description, image, twitter, logo; set page.image default via Jekyll defaults (jekyll-seo-tag v2.7.1 reads page-level image only) - _layouts/default.html: replace manual <title>, og:image, description with {% seo %} tag (one Liquid call emits the full set) - 5 stub pages get minimal title/description/sitemap:false front-matter to prevent jekyll-seo-tag falling back to site.title+description and producing a 150-char title Tier 1 of 3 — pure additive metadata, no URL changes. Fixes ~390 Ahrefs issues (OG incomplete x195, Twitter card missing x195, duplicate without canonical x7) without touching internal links or the sitemap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Sitemap, layout nav, and markdown link text all now point at the clean no-extension URL. Cloudflare's existing 308 from /Page.html → /Page stays in place for any external/inbound .html links — we just stop emitting them ourselves. - _layouts/default.html: strip .html from 122 internal hrefs - sitemap.xml: new Liquid template overrides jekyll-sitemap output to emit clean URLs and skip pages with sitemap:false - robots.txt: add Disallow: /Data-flow alongside existing /Data-flow.html rule (since internal links no longer surface the .html form) - 109 markdown files: strip .html from <a href> embeds and .md from [text](path.md) link targets — kramdown auto-converts .md to .html in built output, which we no longer want. Code blocks preserved. Tier 2 of 3 — URL canonicalisation. Layered on top of Tier 1's SEO meta. Fixes ~1,000 Ahrefs issues (3XX-redirect-in-sitemap x193, page-has-links- to-redirect x195, indexable-not-in-sitemap x195, redirected-page-no- inlinks, only-one-dofollow-inlink, etc.). Expect 2-4 weeks of Google ranking volatility while it re-crawls and consolidates signals to canonical URLs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Final tier of the Ahrefs cleanup. Mostly per-page content fixes plus the noindex hooks for the 5 stub pages. - _layouts/default.html: support page.noindex front-matter (emits <meta name="robots" content="noindex">); drop ?source=hero from the 2 hero buttons (orphan param, no current GA/GTM consumer) - 5 stub pages get noindex: true so Google stops indexing the redirect aliases (still excluded from sitemap) - coding-standards.md: demote second H1 ("Documentation Principles") to H2; was triggering "multiple H1" notice - API/fliplet-communicate.md: alt text on 4 share-sheet screenshots - API/libraries/handlebars.md: alt text on handlebars.png Tier 3 of 3 — content polish. Layered on top of Tier 2's URL canonicalisation. Closes the long-tail items: H1 missing/multiple, missing alt text, hero query-param duplicates, and prevents the JS-redirect stubs from competing in the index. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Tier 4 of the SEO + standards work. Layered on top of Tier 3 (docs/seo-polish). Items 2, 3, 4, 5, 6, 7, 9, 10, 11, 12 from the post-Ahrefs audit. Security - _headers: site-wide block sets HSTS (2 yrs + subdomains), X-Frame-Options DENY, Referrer-Policy, X-Content-Type-Options, Permissions-Policy denying camera/mic/geolocation/etc that the docs site never needs. - Subresource Integrity (SRI) on every CDN script/style — jQuery, FontAwesome, animate.css, instantsearch (CSS+JS+theme), docsearch (CSS+JS). Each pinned with sha384/sha512 + crossorigin=anonymous. CDN compromise no longer means arbitrary code execution. Dependency upgrades (same-major patch bumps, drop-in safe) - jQuery 3.3.1 → 3.7.1 (closes CVE-2019-11358 prototype pollution + CVE-2020-11022/11023 XSS via .htmlPrefilter) - FontAwesome 5.5.0 → 5.15.4 (last 5.x; v6 deferred) - animate.css 3.7.0 → 3.7.2 (last 3.x; v4 has class-name breaks) - instantsearch.js + docsearch.js stay at 2.6.3 — v2→v4/v3 are rewrites that need search-flow testing; deferred to its own PR Dead-code removal - Drop UA-35892004-23 tracking entirely. Universal Analytics was sunset by Google July 2023 — three years of pointless network requests. GTM (GTM-KLZKCRD) is the single remaining tracker. HTML validity - _layouts/default.html: fix 5 long-standing bugs that propagate to every page — 3 stray </a></a> + 2 missing </a> before </li> on Biometrics and Notifications nav items. Accessibility / semantic HTML5 - Wrap top nav in <nav aria-label="Site"> - Sidebar <aside id="poc"> → <nav id="poc" aria-label="Documentation"> - Content <section class="main-content"> → <main id="main" class="main-content"> for proper landmark roles - loading="lazy" on the 5 images Ahrefs flagged Discoverability - Custom /404 page with friendly nav back to known landing pages, noindex+sitemap:false. Replaces the soft-404 (200 + homepage body) that was wasting Google crawl budget on phantom URLs. - <link rel="icon" href="/favicon.ico"> declared explicitly (was relying on browser-default fallback). apple-touch-icon dropped because the file does not exist on the origin. Build pipeline - 404.md added to bin/exclusions.mjs EXCLUDED_FILES + asserted in bin/__tests__/exclusions.test.mjs so it never leaks into the agent-skills index. Updated docs/CLAUDE.md exclusion list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Tier 4 wrapped <ul class="nav"> in <nav aria-label="Site"> for the screen-reader landmark role. That nav element became the flex item in .middle (which is display:flex), shrinking instead of sizing to its inner <ul.nav> content — the top header menu visibly truncated on the preview, per Tony. Fix: display: contents on the wrapper so the <nav> box is removed from layout and the <ul.nav> goes back to being the direct flex item. Accessibility tree still surfaces the <nav> landmark for screen readers (Chrome 89+, Firefox 86+, Safari 15.4+). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Komsomol changed the base branch from docs/seo-polish to master May 6, 2026 09:41

This was referenced May 6, 2026

docs(seo): tier 1 — add SEO meta tags via jekyll-seo-tag #260

Closed

docs(seo): tier 2 — canonicalise URLs to no-extension form #261

Closed

docs(seo): tier 3 — content polish + noindex stubs #262

Closed

Komsomol and others added 4 commits May 6, 2026 10:41

Komsomol force-pushed the docs/seo-standards-cleanup branch from 951c619 to 719b64d Compare May 6, 2026 09:42

Komsomol changed the title ~~docs(seo): tier 4 — standards cleanup (security, SRI, deps, a11y, 404)~~ docs(seo): full SEO + standards cleanup (consolidated) May 6, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(seo): full SEO + standards cleanup (consolidated)#263

docs(seo): full SEO + standards cleanup (consolidated)#263
Komsomol wants to merge 5 commits intomasterfrom
docs/seo-standards-cleanup

Komsomol commented May 6, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented May 6, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Komsomol commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Coverage of Ahrefs audit

Out of scope (separate PRs / actions)

Preview URL

Build verification (Docker, Ruby 2.7, github-pages 232 stack)

Pre-merge retest matrix

Uh oh!

cloudflare-workers-and-pages Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying fliplet-cli with Cloudflare Pages

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Komsomol commented May 6, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented May 6, 2026 •

edited

Loading