From 284979e3b28479dc93ba598468461069cb32645b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 28 Sep 2026 16:03:27 +0000 Subject: [PATCH] docs: backfill Sep site IA and Blog channel maintainer guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update Antora explanation pages for separate News/Blog routes, header menus, Assets hub, and crawlability route list. Changelog index and detail page cover Sep 17–25 functional site changes; fix DevCentr ingest path in the news pipeline doc. Co-authored-by: Ryan Johnson --- CHANGELOG.adoc | 5 +++ ...09-18 - news-blog-split-and-header-ia.adoc | 42 +++++++++++++++++++ .../modules/devcentr-org/pages/changelog.adoc | 26 +++++++++++- .../explanation/bootstrap-templates.adoc | 2 + .../pages/explanation/news-and-changelog.adoc | 37 ++++++++++++---- .../pages/explanation/site-architecture.adoc | 31 +++++++++++--- docs/modules/devcentr-org/pages/index.adoc | 3 +- 7 files changed, 132 insertions(+), 14 deletions(-) create mode 100644 docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - news-blog-split-and-header-ia.adoc diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index aa9c26d..e15aa7c 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,5 +1,10 @@ = Changelog +== 2026-09-28 -- Maintainer docs for Blog channel and header IA + +* Antora changelog backfill (Sep 17–25 site changes); detail page for News/Blog split and header navigation. +* Updated site architecture and news pipeline pages (crawlability maintainer notes, `/assets` routes, corrected DevCentr changelog ingest path). + == 2026-09-10 -- Public crawlability * Publish `/robots.txt` and a build-generated `/sitemap.xml` from the shared prerender route list. diff --git a/docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - news-blog-split-and-header-ia.adoc b/docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - news-blog-split-and-header-ia.adoc new file mode 100644 index 0000000..c0998d9 --- /dev/null +++ b/docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - news-blog-split-and-header-ia.adoc @@ -0,0 +1,42 @@ += 2026-09-18 — News/Blog channels and header IA +:navtitle: 2026-09-18 News, Blog, header IA + +== Summary + +devcentr.org stopped treating `/blog` as a News alias and gave the marketing shell a clearer top navigation: **Assets**, **Updates**, **Help**, and **Links**. + +== News and Blog + +* **News** (`/news`) — outward record: releases, partnerships, openings. Source: `content/news/`. +* **Blog** (`/blog`) — inward craft essays and investigations. Source: `content/blog/`. +* `scripts/build-news.mjs` emits separate JSON catalogs (`news-posts.generated.json`, `blog-posts.generated.json`) and syndication feeds under `public/news/` and `public/blog/`. +* Routes live in `src/routes/news/` and `src/routes/blog/` (no cross-redirect between channels). + +Voice rules stay in `content/news/README.adoc` (news) and editorial title guidance for blog posts under `content/blog/`. + +== Header navigation + +Implemented in `src/components/site-header.tsx`: + +* **Assets** — tree menu: Assets hub (`/assets`), Apps (`/apps`), Skills (`/skills`), Standards (`/assets/standards`). +* **Updates** — News, Blog, Changelog, and external Docs (`https://docs.devcentr.org`). +* **Help** — Help desk (`/help`), Status (`/status`), GitHub Discussions (external). +* **Links** — GitHub org and Slack invite (`src/lib/site-links.ts`). + +The former flat “Community” cluster is folded into **Help**; outbound social links moved to **Links**. + +== Assets hub + +* `/assets` — gate page (Apps vs Standards panes) via `src/routes/assets/index.tsx`. +* `/assets/standards` — standards catalogue entry (Apps catalogue routes unchanged under `/apps/*`). + +== CI and crawlability + +* `scripts/site-routes.mjs` lists `/assets`, `/assets/standards`, `/blog`, and per-post `/blog/{slug}` routes for prerender shells and sitemap generation. +* PlayTime diagram regression test targets a blog article path after the channel split. + +== Knowledge gaps addressed + +* Whether blog posts share the news feed (they do not). +* Where to author inward essays vs outward news. +* How header menus map to routes after the Apps/Standards split. diff --git a/docs/modules/devcentr-org/pages/changelog.adoc b/docs/modules/devcentr-org/pages/changelog.adoc index 233e78e..c9ed62e 100644 --- a/docs/modules/devcentr-org/pages/changelog.adoc +++ b/docs/modules/devcentr-org/pages/changelog.adoc @@ -2,6 +2,30 @@ Timeline of notable documentation and site changes in the devcentr.org repository. +== 2026-09-25 — Blog Git ergonomics essay series + +* Overview (`2026-09-25-why-does-git-suck`), worktree critique, and redesign proposal essays in `content/blog/`. +* Cross-links between the three posts; feeds regenerated after editorial title lock. + +== 2026-09-19 — Assets routes in prerender list + +* `scripts/site-routes.mjs` includes `/assets` and `/assets/standards` so postbuild SPA shells and `sitemap.xml` cover the Assets hub. + +== 2026-09-18 — Header IA (Assets, Updates, Help, Links) + +* Site header: **Assets** tree (Assets hub, Apps, Skills, Standards), **Updates** (News, Blog, Changelog, Docs), **Help** (desk, status, Discussions), **Links** (GitHub, Slack). +* `/assets` gate separates Apps vs Standards; `/assets/standards` for the standards catalogue entry point. + +== 2026-09-18 — News and Blog as separate channels + +* `/blog` is a real channel (essays in `content/blog/`), not an alias of `/news`. +* Separate feeds, JSON catalogs, and routes under `src/routes/blog/`. +* See xref:changelog-details/2026-09-18 - news-blog-split-and-header-ia.adoc[Detailed changelog]. + +== 2026-09-17 — Agent skills catalog UX + +* `/skills` copy clarifies harness-wide install vs one-off skill adoption; Bootstrap tab label and layout cage width fixes; option border clipping and Bootstrap flash on category switch resolved. + == 2026-09-26 - Overview sibling (no wrapper) * `nav.adoc`: articles under `.devcentr.org` are siblings of **Overview**, not children. Forest pattern: platform Overview is a peer start-page leaf (site-nav-tree also unwraps Overview parents defensively). @@ -23,7 +47,7 @@ Timeline of notable documentation and site changes in the devcentr.org repositor == 2026-09-10 — Public crawlability * Publish `/robots.txt` and generate `/sitemap.xml` from the shared prerender route list in postbuild (`spa-fallback`). -* Sitemap omits `/health`, `/status`, and `/blog` aliases of `/news`. +* Sitemap omits `/health` and `/status` probe routes. == 2026-09-08 — Themed PlayTime news diagrams diff --git a/docs/modules/devcentr-org/pages/explanation/bootstrap-templates.adoc b/docs/modules/devcentr-org/pages/explanation/bootstrap-templates.adoc index 7e30bf2..0df8241 100644 --- a/docs/modules/devcentr-org/pages/explanation/bootstrap-templates.adoc +++ b/docs/modules/devcentr-org/pages/explanation/bootstrap-templates.adoc @@ -4,6 +4,8 @@ `/skills` is the public catalog of org Cursor skills. Categories are All, Bootstrap skills, Writing, Docs, Publishing, plus Review and Studio placeholders. `/templates` redirects to `/skills?cat=bootstrap`. +The page intro stresses **harness-wide install** (agent-rules as one cohesive unit with discovery wired through `harness.md` / `AGENT_RULES_PATH`) versus treating skills as unrelated one-offs. Copy blocks in `src/components/AgentSkills.tsx` are the source of that framing. + Bootstrap skills reuse the list-and-detail picker for named SDL profiles in `dev-centr/agent-rules` (`skills/bootstrap-org/profiles/`). JSON is compiled at site build time. The SDL files in agent-rules stay the source of truth; the site does not hand-maintain a duplicate table. diff --git a/docs/modules/devcentr-org/pages/explanation/news-and-changelog.adoc b/docs/modules/devcentr-org/pages/explanation/news-and-changelog.adoc index 2151e37..7789ea4 100644 --- a/docs/modules/devcentr-org/pages/explanation/news-and-changelog.adoc +++ b/docs/modules/devcentr-org/pages/explanation/news-and-changelog.adoc @@ -2,12 +2,13 @@ :navtitle: News & changelog :description: How authored news posts and mirrored Antora changelogs are built for devcentr.org. -devcentr.org separates **narrative news** from **shipping notes**: +devcentr.org separates **channels** by audience and voice: -* **News** (`/news`) — outward-facing essays and announcements authored in this repo. +* **News** (`/news`) — outward-facing announcements and shared record (releases, partnerships, openings). +* **Blog** (`/blog`) — inward craft essays, investigations, and orientations. * **Changelog** (`/changelog`) — day-to-day bullets mirrored from Antora changelogs in sibling repos. -Do not put changelog bullets in news posts, and do not hand-edit the generated JSON catalogs. +Do not put changelog bullets in news or blog posts, and do not hand-edit the generated JSON catalogs. == News (authored) @@ -39,7 +40,29 @@ Voice and checklist: see `content/news/README.adoc` in the repository (conversat * `src/lib/news-posts.generated.json` — post metadata and rendered HTML for Solid routes * `public/news/rss.xml` and `public/news/atom.xml` — syndication feeds -Routes: `src/routes/news/` (and `/blog` alias). +Routes: `src/routes/news/`. + +== Blog (authored) + +=== Source + +AsciiDoc files in `content/blog/YYYY-MM-DD-slug.adoc` with the same front-matter pattern as news (`:description:`, `:revdate:`, optional `:keywords:`). + +=== Authoring options + +* **Pages CMS** — `blog` collection in `.pages.yml`. +* **Git / PR** — edit under `content/blog/`, run `pnpm news:build`. + +=== Build output + +`scripts/build-news.mjs` writes: + +* `src/lib/blog-posts.generated.json` +* `public/blog/rss.xml` and `public/blog/atom.xml` + +Routes: `src/routes/blog/`. + +Blog titles follow org editorial rules (see repository `STYLE.adoc` and `.cursor/rules/editorial-titles.mdc`). == Changelog (mirrored) @@ -52,7 +75,7 @@ At build time, `build-news.mjs` ingests Antora timeline files from sibling check | Source ID | Antora file | `devcentr` -| `devcentr/docs/modules/ROOT/pages/changelog.adoc` +| `devcentr/docs/modules/devcentr/pages/changelog.adoc` | `general-knowledge` | `general-knowledge/docs/modules/ROOT/pages/changelog.adoc` @@ -77,5 +100,5 @@ Rebuild (or push to `main` and let CI regenerate). == Troubleshooting * **Empty `/changelog` locally** — clone `dev-centr/devcentr`, `general-knowledge`, and `docs` as siblings, then `pnpm news:build`. -* **News post missing** — confirm filename ends in `.adoc`, is not `README.adoc`, and has `:revdate:`. -* **Feeds stale** — run `pnpm news:build`; feeds are regenerated from the news JSON, not hand-edited. +* **News or blog post missing** — confirm filename ends in `.adoc`, is not `README.adoc`, and has `:revdate:` in the correct folder (`content/news/` vs `content/blog/`). +* **Feeds stale** — run `pnpm news:build`; feeds are regenerated from the JSON catalogs, not hand-edited. diff --git a/docs/modules/devcentr-org/pages/explanation/site-architecture.adoc b/docs/modules/devcentr-org/pages/explanation/site-architecture.adoc index 81ae7d8..1aa6edf 100644 --- a/docs/modules/devcentr-org/pages/explanation/site-architecture.adoc +++ b/docs/modules/devcentr-org/pages/explanation/site-architecture.adoc @@ -9,7 +9,7 @@ devcentr.org is a **static** SolidStart (Vinxi) application. * **SolidStart + Vinxi** — file-based routes under `src/routes/` * **Tailwind CSS v4** — `src/app.css`, Kobalte primitives for accessible UI -* **AsciiDoc** — news posts (`content/news/`) compiled with `@asciidoctor/core` at build time +* **AsciiDoc** — news (`content/news/`) and blog (`content/blog/`) compiled with `@asciidoctor/core` at build time * **GitHub Actions** — `.github/workflows/ci.yml` builds and deploys on push to `main` == Public routes @@ -21,8 +21,11 @@ devcentr.org is a **static** SolidStart (Vinxi) application. | `/` | Landing — hero, ecosystem copy, toolchain diagram, apps teaser -| `/news`, `/blog` -| News index and posts (`/blog` is an SEO alias) +| `/news` +| Outward news index and posts (`content/news/`) + +| `/blog` +| Inward essays index and posts (`content/blog/`) | `/changelog` | Changelog mirror from Antora sibling repos @@ -33,6 +36,9 @@ devcentr.org is a **static** SolidStart (Vinxi) application. | `/status`, `/health` | Client-side endpoint probes (`/health` redirects to `/status`) +| `/assets`, `/assets/standards` +| Assets hub gate (Apps vs Standards panes); standards entry point beside `/apps` + | `/apps`, `/apps/products`, `/apps/services`, `/apps/standards` | Apps catalogue (data in `src/lib/apps-catalog.ts`) @@ -51,13 +57,28 @@ devcentr.org is a **static** SolidStart (Vinxi) application. Catalogue and nested article pages (`PageTrail`) show the access path as `Section / Child / Current`. Topic tags stay *below* that trail, in the eyebrow style. Outbound links (repo, docs) sit after the intro, not in the trail. +== Header navigation + +Top bar (`src/components/site-header.tsx`): + +* **Assets** — `/assets`, `/apps`, `/skills`, `/assets/standards` (tree menu). +* **Updates** — `/news`, `/blog`, `/changelog`, plus external Docs. +* **Help** — `/help`, `/status`, GitHub Discussions (`src/components/help-nav.tsx`). +* **Links** — GitHub org and Slack invite (`src/components/links-nav.tsx`). + == Build pipeline `pnpm run build` runs, in order: . `prebuild` — `scripts/sync-advisor-catalog.mjs`, `scripts/sync-bootstrap-profiles.mjs`, then `scripts/build-news.mjs` . `vinxi build` — static route artifacts -. `postbuild` — `scripts/spa-fallback.mjs` for client-side routing on Pages +. `postbuild` — `scripts/spa-fallback.mjs` copies the SPA shell for every route in `scripts/site-routes.mjs`, writes `robots.txt` and `sitemap.xml`, and injects no-JS crawl fallback into prerendered HTML (`scripts/write-crawlability.mjs`) + +== Crawlability + +* **Canonical route list** — `getPrerenderRoutes()` in `scripts/site-routes.mjs` (static paths plus news, blog, and idea slugs from generated JSON / `apps-catalog.ts`). +* **Sitemap** — built in postbuild; excludes `/health` and `/status` probes. +* **Maintainers** — when adding a new top-level marketing route, append it to `STATIC_ROUTES` in `site-routes.mjs` so GitHub Pages gets an `index.html` shell and the URL appears in `sitemap.xml`. CI (`.github/workflows/ci.yml`) additionally checks out sibling repos into the workspace root before `build-news.mjs`: @@ -78,6 +99,6 @@ Custom domain `devcentr.org` is configured in the repository's Pages settings. * `src/routes/` — page components * `src/components/` — shared UI (header, footer, diagrams, toolchain browser widget, agent skills catalog) * `src/lib/` — catalog data, changelog loader, theme reveal, site links -* `content/news/` — authored news (see xref:explanation/news-and-changelog.adoc[News & changelog pipeline]) +* `content/news/`, `content/blog/` — authored news and blog (see xref:explanation/news-and-changelog.adoc[News & changelog pipeline]) * `public/brand/` — SVG logo marks (canonical org assets live in `.github` profile repos) * `scripts/` — news/changelog build, advisor and bootstrap-profile sync, SPA fallback, logo rasterize diff --git a/docs/modules/devcentr-org/pages/index.adoc b/docs/modules/devcentr-org/pages/index.adoc index 182355d..fc7221c 100644 --- a/docs/modules/devcentr-org/pages/index.adoc +++ b/docs/modules/devcentr-org/pages/index.adoc @@ -15,7 +15,8 @@ https://devcentr.org * **Marketing home** — Developer ecosystem positioning, apps catalogue, and links to the flagship DOS at link:https://devcentr.app[devcentr.app]. * **News** (`/news`) and **Blog** (`/blog`) — News: narrative AsciiDoc from `content/news/`. Blog: essays from `content/blog/`. * **Changelog** (`/changelog`) — Mirror index of Antora changelogs from sibling repos (built at CI time). -* **Community** — Help hub (`/help`), status probes (`/status`), and toolchain surfaces. +* **Help & status** — Help hub (`/help`), status probes (`/status`), and GitHub Discussions (header **Help** menu). +* **Assets hub** — `/assets` gate for Apps vs Standards; Skills remain in the **Assets** header tree. * **Public tools** — Stack Advisor (`/stack-advisor`; `/toolchain-browser` and `/toolchain-advisor` redirect), agent skills (`/skills`), resting-lanczos demo (`/resting-lanczos`), and apps catalogue (`/apps`). == Documentation map