[review] Site critique 2026-07 — top-10 improvement plan

[rufuspollock]

Full review: docs/reviews/site-critique-2026-07.md. Part of #46.

Verdict: content skeleton is genuinely strong; what's missing is everything around the words — visual identity, shown proof, interactivity, trust signals, feedback loops. Scores: thesis/IA 4.5, voice 4, visual identity 1.5, show-don't-tell 2, learner UX 3, trust 2, discovery 3, engagement 1.5.

Top 10 (impact × effort)

• 1. custom.css brand pass — own the palette (adopt the roadmap's green as accent) + typography (S/L)
• 2. /about page + real footer + bylines — currently zero authorship signals on the whole site (S/L)
• 3. OG/social card images, script-generated per page — shares currently render bare (M/L)
• 4. Screenshots for the 4 flagship guides (Notion escape, websites, KB, databases) (M/L)
• 5. Finish tutorial 3 — amber hole in the roadmap spine, blocks job story JS1 (v0.1: Tutorials 3 & 4 — finish or defer #53) (M/L)
• 6. Analytics (Umami?) + Search Console + blog RSS — needs Rufus decision/accounts; site currently measures nothing (S/L)
• 7. 'View the markdown' framing + enable Flowershow backlinks — practice what we preach (S/M)
• 8. Giscus comments on blog + essays (S/M)
• 9. Consolidate kb app-notes into markdown-in-* URLs with redirects, before URLs age (S/M)
• 10. Markdown live playground — the one big feature bet; investigate Flowershow JS options first (L/L)

Also recorded, unprioritized: landing hero rework, comparison pages ('Obsidian vs Notion' genre — highest-intent SEO we have none of), X-❤️-Markdown badges, roadmap progress ticking, demo example sites, early email capture, content license decision (CC-BY?).

[rufuspollock]

Top-10 executed (commit pushed; live-verification in progress):

1. ✅ custom.css — green brand accent via theme variables, styled selection/quotes/tables/hrs
2. ✅ /about (incl. Flowershow disclosure), footer navigation (3 columns), bylines on manifesto/essays, made-by line on landing
3. ✅ Branded OG card generated (Chrome-rendered 1200×630, template in scripts/) + config default — note: custom social images are a Flowershow premium feature; card is in place for when the plan allows
4. ✅ Screenshots embedded in websites/KB/databases/Notion-escape guides — honest ones from existing tutorial assets (live table of the Harry Potter catalog, real Obsidian vault, tutorial-1 result)
5. ✅ Tutorial 3 written in full — branches → PR → review → merge → conflicts, series style; roadmap spine now fully green; learn index updated (only tutorial 4 remains WIP → v0.1: Tutorials 3 & 4 — finish or defer #53)
6. ✅ RSS enabled (enableRss, posts have dates) · ⏳ analytics needs Rufus: pick GA4 or Umami + provide ID
7. ✅ Backlinks confirmed on-by-default (verify visible on live) · view-source framing done on /about
8. 🟡 Comments: Discussions enabled via API, giscus repo/category IDs fetched & configured — one manual step: install the giscus app on the repo (Rufus)
9. ✅ kb app-notes consolidated to markdown-in-google-docs + markdown-in-apple-notes with config redirects
10. ✅ Playground shipped: /playground.html — self-contained live editor+preview (raw-HTML publishing), dependency-free mini-renderer, brand-styled, dark-mode aware; linked from basics/landing/roadmap

Remaining for Rufus: giscus app install (2 min), analytics choice, Search Console (launch checklist), premium check for OG cards. Unprioritized backlog from the critique still open: landing hero rework, comparison pages, badges, progress-ticking, demo sites, email capture, license decision.

[rufuspollock]

Live verification results (post-deploy checks):

• ✅ All new pages 200: /about, /playground.html, /markdown-in-google-docs, /markdown-in-apple-notes, /learn/tutorial-3
• ✅ Redirects working: /kb/google-docs → 307 → /markdown-in-google-docs (etc.)
• ✅ /rss.xml serving (302 → feed)
• ✅ custom.css confirmed inlined into rendered pages (green accent visible on live /about screenshot; older pages pick it up as HTML cache refreshes)
• ✅ Playground screenshot-tested: tables, task lists, quotes, code all render; dark-mode vars in place
• ⚠️ OG card asset serves, but site-wide og:image only takes effect on premium (per Flowershow docs)

Rufus-only steps (blocking the last 10%):

• Install the giscus app on flowershow/wayofmarkdown (~2 min; everything else is configured — comments appear immediately after)
• Analytics: choose GA4 or Umami and provide the ID
• Search Console setup (already on the launch checklist, docs/launch/launch-plan.md)
• Confirm whether the Flowershow plan includes custom social images (for the OG card)

New observation for the backlog: the sidebar is now a long flat alphabetical pile of every root page — legible but noisy. Worth an ordering/grouping pass (contentHide selected pages from sidebar, or restructure) in a future round.

[rufuspollock]

Landing hero rework shipped (the 'unprioritized: landing hero' item + parked inbox idea):

• Native Flowershow hero (showHero + cta frontmatter): 'Own the source. Compose with anything.' headline, two CTAs (roadmap / manifesto); hero height tamed in custom.css
• Raw→rendered before/after demo as the visual hook: reading-list.md as literal plain text beside the same file rendered — the site's thesis as one picture. (Fought the md parser intruding into the raw pane; fixed with entity-encoded line starts)
• Six 'why markdown wins' tiles (the visual awesome-one-pager, delivered in place rather than as a separate page), build-your-X card grid, tightened routing, made-by footer line
• playground.html hidden from sidebar (contentHide)
• Screenshot-verified on live: hero, CTAs, panes, tiles all render; checked at two viewport sizes

Remaining known polish: hero→content gap is theme-determined (moderate, acceptable); raw pane clips by a character at narrow widths; dark-mode eyeball check still worthwhile (Rufus).

[rufuspollock]

Note from Rufus: the site doesn't use dark mode. Playground pinned to light to match; the dark-mode caveats in earlier comments here are moot. (Inert dark-theme variables remain in custom.css — harmless, and ready if that ever changes.)