mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
c7b3f4cacf
> **Updated on current main:** #87 and the #90 cache hotfix are merged. This PR now targets `main`, was rebased onto merge commit `8c5976f`, and has a fresh successful Cloudflare preview plus post-rebase browser smoke evidence. ## What & why (PAP-16980) Improves SEO/AEO on the bundled/optional **per-skill reference pages** (from PAP-16670) by clearly separating the *human-readable catalog summary* (top of page) from the *authoritative full skill definition*. Previously the "Full skill definition" section rendered the `SKILL.md` as **parsed Markdown**, so each skill's own `##` headings, lists, and fenced examples became real page content — competing with the summary, inflating the on-page TOC (e.g. qa-acceptance went from **16 → 6** "On this page" entries), and confusing crawlers/answer engines about the page's true structure. Now each per-skill page shows the **complete, verbatim `SKILL.md`** (frontmatter + body) inline, rendered through the **existing production code-snippet treatment**. ## Changes - **Content (10 per-skill pages):** replaced the old `### Skill frontmatter` bullets + parsed `### Skill instructions` layout with the full `SKILL.md` embedded in a fenced ````markdown skill-source` block. Source bytes were taken verbatim from each skill's authoritative `SKILL.md` at the page's pinned `paperclip_version`, verified against the page's own prior instructions body + frontmatter (name/description) so no content drifted. - **Renderers (`site/build-release.mjs`, `site/app.js`):** a `skill-source` fence renders as `<pre><code class="language-markdown" data-skill-download="SKILL.md">`. Every other code block is delegated to marked's default renderer, so existing snippets are byte-for-byte unchanged. Rendered identically in the crawler-visible build HTML and on client SPA navigation. - **Copy + Download (`site/app.js`, `site/styles.css`):** `decorateCodeBlocks` reuses the existing Copy affordance and adds a **Download `SKILL.md`** control beside it. Both share dimensions, styling, hover/focus visibility, and the copied-success state; both carry accessible labels/titles. - **Readable full-source wrapping (`site/styles.css`):** only the downloadable `SKILL.md` block uses `white-space: pre-wrap` and safe long-token wrapping. Ordinary code snippets retain the existing horizontal-scroll treatment. - **Test:** `scripts/verify-skill-source-blocks.mjs` (`npm run docs:test:skill-source-blocks`) asserts the render contract (single H1, single `<pre>`, frontmatter present, no legacy headings) and that ordinary docs pages emit no `data-skill-download`. ## Scope statement No catalog-page layout, navigation, typography, summary-copy, metadata-card, or information-architecture changes. `paperclip-website` and generated `.site/` output are untouched. `optional/finance/ramp.md` is intentionally excluded — it is a newer summary page with no embedded full-definition section to reformat. The diff is the 10 skill pages + the narrow renderer/Copy-Download support + the test. ## Evidence **1–2. Before/after (desktop, 1280×900) + mobile after (390×844)** — attached to Paperclip issue [PAP-16980](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/3098577a-4f6f-4eb2-9151-a4b61917dffd) (`before-desktop.png`, `after-desktop-controls.png`, `after-controls-zoom.png`, `after-mobile.png`). GitHub cannot render the auth-gated attachment URLs inline, so they live on the issue for reviewers. **4. Raw DOM/HTML (build output, qa-acceptance):** - Article renders exactly **one H1**: `<h1 id="qa-acceptance">QA Acceptance</h1>` - Full source inside a single code block: ```html <pre><code class="language-markdown" data-skill-download="SKILL.md">--- name: qa-acceptance description: Produce QA acceptance criteria and a manual validation plan … key: paperclipai/bundled/quality/qa-acceptance recommendedForRoles: - qa … </code></pre> ``` - Article `<pre>` count: **1** (inner ````` fences stay literal — no breakout). 10/10 skill pages carry the block; 0 non-skill pages do. **5. Copy + Download behavior (Playwright against the built site):** ```json { "downloadFilename": "SKILL.md", "downloadMatchesBlock": true, // downloaded file === code block text, byte-identical "downloadBytes": 3853, "copyShowsSuccess": true, // Copy toggles the existing is-copied success state "accessibleLabels": { "copy": "Copy code", "download": "Download SKILL.md" } } ``` Both controls reach `opacity: 1` on `.code-wrap:hover` and on keyboard `:focus-visible` (verified `matches(':focus-visible') === true` → computed opacity `1`). **H1 audit (every generated route, incl. all skill URLs — requested on the issue):** built the site on current `main` and scanned **all 184 generated `index.html` routes** (16 skill routes among them). **Every route has exactly one `<h1>`.** The skill source's own `#`/`##` headings live *inside* the `<pre><code>` block as literal text, so they do **not** create competing H1s — the SEO/AEO goal. ## Tests Run against current `main` after #87 and #90: ``` docs:build ............................. ok (184 routes) docs:test:static-routes ................ pass (5 routes + 404 + root + subpath) docs:test:skill-source-blocks .......... pass (10 skill pages, 1 control page) H1 audit (all 184 routes) .............. pass (exactly 1 h1 each; 16 skill routes) ``` **Do not merge/deploy** — returning to Dotta/reviewers for approval per PAP-16980. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]>