From 190ac7c9f22942248781868559ca37f2b8f9ec88 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 16:07:13 +0000 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20backfill=20Sep=2017=E2=80=93?= =?UTF-8?q?19=20site=20and=20navigation=20changes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Antora changelog index entries and detail pages for the skills browser overhaul, Blog/News split, header IA, and Assets crawl routes. Correct the Sep 10 sitemap note now that /blog is a real channel. Co-authored-by: Ryan Johnson --- CHANGELOG.adoc | 12 ++++++ README.adoc | 5 ++- ...26-09-17 - skills-browser-and-docs-ia.adoc | 30 +++++++++++++++ ...6-09-18 - blog-channel-and-header-nav.adoc | 37 ++++++++++++++++++ .../modules/devcentr-org/pages/changelog.adoc | 20 +++++++++- .../explanation/bootstrap-templates.adoc | 2 + .../pages/explanation/news-and-changelog.adoc | 38 ++++++++++++++----- .../pages/explanation/site-architecture.adoc | 38 +++++++++++++++++-- .../pages/help-and-support-plans.adoc | 8 ++-- .../pages/how-to/local-development.adoc | 6 +-- docs/modules/devcentr-org/pages/index.adoc | 3 +- 11 files changed, 175 insertions(+), 24 deletions(-) create mode 100644 docs/modules/devcentr-org/pages/changelog-details/2026-09-17 - skills-browser-and-docs-ia.adoc create mode 100644 docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - blog-channel-and-header-nav.adoc diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index aa9c26d..2ade409 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,5 +1,17 @@ = Changelog +== 2026-09-19 -- Assets routes in crawl list + +* Index `/assets` and `/assets/standards` in prerender, SPA fallback, and sitemap generation. + +== 2026-09-18 -- Blog channel and header navigation + +* Separate Blog from News; new header dropdowns (Assets, Updates, Help, Links) and Assets hub routes. + +== 2026-09-17 -- Skills browser and docs IA + +* Platforms Antora placement, Help contact email, favicon refresh, and `/skills` harness-inventory UX. + == 2026-09-10 -- Public crawlability * Publish `/robots.txt` and a build-generated `/sitemap.xml` from the shared prerender route list. diff --git a/README.adoc b/README.adoc index a609509..fedbff4 100644 --- a/README.adoc +++ b/README.adoc @@ -87,7 +87,7 @@ Site copies live in `public/brand/`. Canonical org-wide assets (including `logo. * **Probes:** link:https://devcentr.org/status[/status] (`/health` redirects here) — client-side checks of public endpoints * **Hosted uptime:** link:https://status.devcentr.org[status.devcentr.org] (Better Stack) — linked from the probe page -* Community surfaces (Help, Status, Slack, …) live under the header **Community** menu +* Header **Help** menu: Help desk, Status, GitHub Discussions. **Links** menu: GitHub org and Slack. === Skills @@ -124,7 +124,8 @@ pnpm dev == Project Structure * `src/` — Source code (scaffolded) -* `content/news/` — AsciiDoc news / blog posts +* `content/news/` — Outward news posts (AsciiDoc) +* `content/blog/` — Inward blog essays (AsciiDoc) * `public/` — Static assets (includes generated feeds under `public/news/` and `public/blog/`) * `src/lib/news-posts.generated.json` / `changelog-entries.generated.json` — build outputs from `pnpm news:build` * `app.config.ts` — SolidStart/Vinxi configuration diff --git a/docs/modules/devcentr-org/pages/changelog-details/2026-09-17 - skills-browser-and-docs-ia.adoc b/docs/modules/devcentr-org/pages/changelog-details/2026-09-17 - skills-browser-and-docs-ia.adoc new file mode 100644 index 0000000..076d897 --- /dev/null +++ b/docs/modules/devcentr-org/pages/changelog-details/2026-09-17 - skills-browser-and-docs-ia.adoc @@ -0,0 +1,30 @@ += 2026-09-17 — Skills browser, brand mark, and Antora placement +:navtitle: 2026-09-17 Skills & docs IA +:page-audience: DevCentr site maintainers +:page-usage-context: Maintaining `/skills` and published Antora pages +:page-orig-author: Auto on behalf of Ryan Johnson +:page-last-author: Auto on behalf of Ryan Johnson + +== Antora module + +This repository's component moved under the shared `platforms` Antora component (`docs/antora.yml`), published at link:https://docs.devcentr.org/platforms/devcentr-org/[docs.devcentr.org/platforms/devcentr-org/]. +Cross-module xrefs were repaired for the online playbook. + +== Help contact + +`support@devcentr.org` appears on `/help` and in the site footer as the interim assisted-support address. + +== Brand favicon + +The concentric two-tone favicon mark uses a transparent background (no dark tile) so small sizes stay legible on light and dark browser chrome. + +== Skills catalog UX + +`/skills` is framed as a *harness inventory*, not a skill storefront: + +* Category tabs switch client-side without a full page reload; the selected category syncs to `?cat=` in the URL. +* Copy actions emit paste-into-agent prompts (including a harness-wide preinstall block), not bare skill names. +* On-page copy distinguishes one-off skill use from installing `dev-centr/agent-rules` as a cohesive harness unit. +* Layout fixes: stable stage height, Bootstrap tab label, full-width option cage, and favicon hub/satellite radius parity in the solar diagram. + +See xref:explanation/bootstrap-templates.adoc[Agent skills] for data flow and SPA fallback. diff --git a/docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - blog-channel-and-header-nav.adoc b/docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - blog-channel-and-header-nav.adoc new file mode 100644 index 0000000..25c8196 --- /dev/null +++ b/docs/modules/devcentr-org/pages/changelog-details/2026-09-18 - blog-channel-and-header-nav.adoc @@ -0,0 +1,37 @@ += 2026-09-18 — Blog channel and header navigation +:navtitle: 2026-09-18 Blog & nav IA +:page-audience: DevCentr site maintainers +:page-usage-context: Authoring updates and adjusting header menus +:page-orig-author: Auto on behalf of Ryan Johnson +:page-last-author: Auto on behalf of Ryan Johnson + +== News and Blog split + +`/blog` is a real channel, not an alias of `/news`: + +* Authored AsciiDoc lives in `content/blog/` (essays, investigations, inward craft). +* `scripts/build-news.mjs` writes `src/lib/blog-posts.generated.json` and syndication feeds under `public/blog/`. +* Routes live under `src/routes/blog/`; prerender and SPA fallback include `/blog` and each post slug. + +News (`content/news/`) remains the outward shared record (releases, partnerships, openings). +See xref:explanation/news-and-changelog.adoc[News & changelog pipeline]. + +== Header information architecture + +The former single **Community** menu became structured dropdowns: + +* **Assets** — tree: Assets hub (`/assets`), Apps (`/apps`), Skills (`/skills`), Standards (`/assets/standards`). Legacy `/apps/standards` redirects to `/assets/standards`. +* **Updates** — News, Blog, Changelog, and external Docs (`docs.devcentr.org`). +* **Help** — Help desk (`/help`), Status probes (`/status`), GitHub Discussions. +* **Links** — GitHub org and Slack (`SLACK_INVITE_URL` in `src/lib/site-links.ts`). + +Implementation: `src/components/site-header.tsx`, `help-nav.tsx`, `links-nav.tsx`, `nav-dropdown.tsx`. + +== Blog launch content + +* New essay: what a good install actually is (installation norms orientation). +* Editorial title pass on existing blog posts; PlayTime diagram CI test targets the blog article path. + +== CI note + +Stack Advisor catalog markup and the D language toolchain package name (`dax` replacing deprecated `dax-sh`) were fixed so production builds stay green. diff --git a/docs/modules/devcentr-org/pages/changelog.adoc b/docs/modules/devcentr-org/pages/changelog.adoc index 2c81faa..1a4be38 100644 --- a/docs/modules/devcentr-org/pages/changelog.adoc +++ b/docs/modules/devcentr-org/pages/changelog.adoc @@ -2,10 +2,28 @@ Timeline of notable documentation and site changes in the devcentr.org repository. +== 2026-09-19 — Assets routes in crawl list + +* Add `/assets` and `/assets/standards` to `scripts/site-routes.mjs` so prerender, SPA fallback, and `sitemap.xml` cover the Assets hub and Standards catalogue. + +== 2026-09-18 — Blog channel and header navigation + +* Split News and Blog into separate channels (`content/blog/`, dedicated feeds and routes). +* Replace the Community header menu with Assets, Updates, Help, and Links dropdowns; introduce `/assets` gate and `/assets/standards`. +* Ship installation-norms blog essay; editorial title pass on blog posts. +* See xref:changelog-details/2026-09-18 - blog-channel-and-header-nav.adoc[Detailed changelog]. + +== 2026-09-17 — Skills browser, brand, and Antora placement + +* Move this component under the shared `platforms` Antora module; repair online xrefs. +* Surface `support@devcentr.org` on Help and in the footer. +* Refresh favicon mark; overhaul `/skills` UX (harness framing, agent prompts, client-side category tabs). +* See xref:changelog-details/2026-09-17 - skills-browser-and-docs-ia.adoc[Detailed changelog]. + == 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 probe routes `/health` and `/status` only. == 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..b008fd5 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 is a **harness inventory**, not a storefront: copy actions emit paste-into-agent prompts (including a harness-wide preinstall block), and on-page copy explains installing `dev-centr/agent-rules` as one cohesive unit versus one-off skill picks. Category tabs update `?cat=` in the URL without a full page reload. + 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..535c257 100644 --- a/docs/modules/devcentr-org/pages/explanation/news-and-changelog.adoc +++ b/docs/modules/devcentr-org/pages/explanation/news-and-changelog.adoc @@ -1,13 +1,14 @@ = News and changelog pipeline :navtitle: News & changelog -:description: How authored news posts and mirrored Antora changelogs are built for devcentr.org. +:description: How authored news and blog posts plus mirrored Antora changelogs are built for devcentr.org. -devcentr.org separates **narrative news** from **shipping notes**: +devcentr.org separates **channels** from **shipping notes**: -* **News** (`/news`) — outward-facing essays and announcements authored in this repo. +* **News** (`/news`) — outward-facing essays and announcements in `content/news/`. +* **Blog** (`/blog`) — inward craft, investigations, and orientations in `content/blog/`. * **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) @@ -22,12 +23,12 @@ Each post should set: = Post title :description: One-line summary for feeds and meta :revdate: 2026-08-10 -:keywords: news, blog, optional-topic +:keywords: news, optional-topic ---- === Authoring options -* **Pages CMS** — GitHub-connected editor; config in `.pages.yml` at the repo root. +* **Pages CMS** — GitHub-connected editor; config in `.pages.yml` at the repo root (`news` collection). * **Git / PR** — create or edit files under `content/news/`, run `pnpm news:build`, open a PR. Voice and checklist: see `content/news/README.adoc` in the repository (conversational, scene-driven; changelog bullets belong elsewhere). @@ -39,7 +40,26 @@ 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 fields as news (omit `:keywords:` values that imply the wrong channel). + +=== Authoring options + +* **Pages CMS** — `blog` collection in `.pages.yml`. +* **Git / PR** — edit `content/blog/`, run `pnpm news:build`. + +=== Build output + +* `src/lib/blog-posts.generated.json` +* `public/blog/rss.xml` and `public/blog/atom.xml` +* Routes under `src/routes/blog/` + +Blog and news posts are deduplicated by slug across channels at build time (a slug cannot appear in both trees). == Changelog (mirrored) @@ -77,5 +97,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`, has `:revdate:`, and the slug is not duplicated in the other channel. +* **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..901700e 100644 --- a/docs/modules/devcentr-org/pages/explanation/site-architecture.adoc +++ b/docs/modules/devcentr-org/pages/explanation/site-architecture.adoc @@ -21,12 +21,18 @@ 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 blog index and posts (`content/blog/` — not a News alias) | `/changelog` | Changelog mirror from Antora sibling repos +| `/assets`, `/assets/standards` +| Assets hub; Apps vs Standards entry points (`/apps/standards` redirects to `/assets/standards`) + | `/help`, `/support` | Help hub (`/support` redirects to `/help#support`) @@ -34,7 +40,7 @@ devcentr.org is a **static** SolidStart (Vinxi) application. | Client-side endpoint probes (`/health` redirects to `/status`) | `/apps`, `/apps/products`, `/apps/services`, `/apps/standards` -| Apps catalogue (data in `src/lib/apps-catalog.ts`) +| Apps catalogue (data in `src/lib/apps-catalog.ts`; `/apps/standards` redirects to `/assets/standards`) | `/ideas/:slug` | Idea pages for catalogue entries with `ideaSlug` @@ -51,6 +57,17 @@ 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-level menus in `src/components/site-header.tsx`: + +* **Assets** — `/assets` hub, `/apps`, `/skills`, `/assets/standards` (tree layout in the dropdown). +* **Updates** — `/news`, `/blog`, `/changelog`, plus external Docs. +* **Help** — `/help`, `/status`, GitHub Discussions (`help-nav.tsx`). +* **Links** — GitHub org and Slack (`links-nav.tsx`, `SLACK_INVITE_URL`). + +The legacy **Community** label was removed; `community-nav.tsx` re-exports `HelpNav` for compatibility. + == Build pipeline `pnpm run build` runs, in order: @@ -78,6 +95,19 @@ 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/` — outward news (`content/blog/` for the blog channel; 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 + +== Public crawlability + +`scripts/site-routes.mjs` is the single source of indexable paths. +`getPrerenderRoutes()` feeds: + +* Vinxi prerender configuration (static HTML shells where applicable) +* `scripts/spa-fallback.mjs` — copies the enhanced SPA `index.html` into each route directory under `.output/public` +* `scripts/write-crawlability.mjs` — writes `sitemap.xml` and `robots.txt` (called from postbuild) + +The sitemap excludes operational probe routes `/health` and `/status` only. +News, blog, changelog, assets, and app routes are included when listed in `site-routes.mjs` or derived from generated post JSON / idea slugs. +`injectHtmlFallback` adds title, description, and a noscript block to the app shell for crawlers without JavaScript. diff --git a/docs/modules/devcentr-org/pages/help-and-support-plans.adoc b/docs/modules/devcentr-org/pages/help-and-support-plans.adoc index 07126b1..9337836 100644 --- a/docs/modules/devcentr-org/pages/help-and-support-plans.adoc +++ b/docs/modules/devcentr-org/pages/help-and-support-plans.adoc @@ -18,9 +18,9 @@ Do not make docs the top-level support page. Docs are one choice on `/help`. * `/help` landing with docs (live) and contact-support (coming soon). * Interim contact: `support@devcentr.org`. * Public triage still via GitHub Issues and Discussions. -* Community menu (header): Help, Status, Better Stack uptime, Slack, Discussions. -* Live probe page at `/status`; hosted incidents/uptime at `https://status.devcentr.org` (Better Stack). -* Slack: public invite in `src/lib/site-links.ts` (`SLACK_INVITE_URL`). +* Header **Help** menu: Help desk (`/help`), Status probes (`/status`), GitHub Discussions. +* Header **Links** menu: GitHub org and Slack (`SLACK_INVITE_URL`). +* Hosted uptime and incidents: `https://status.devcentr.org` (Better Stack), linked from `/status`. == Near-term product goals @@ -58,7 +58,7 @@ When volume or paid plans justify an operator queue: == Related surfaces -* Site: `src/routes/help.tsx`, `src/routes/support.tsx`, `src/components/community-nav.tsx` +* Site: `src/routes/help.tsx`, `src/routes/support.tsx`, `src/components/help-nav.tsx`, `src/components/links-nav.tsx`, `src/components/site-header.tsx` * Links: `src/lib/site-links.ts` * Docs hub: https://docs.devcentr.org * Status (probes): `/status` diff --git a/docs/modules/devcentr-org/pages/how-to/local-development.adoc b/docs/modules/devcentr-org/pages/how-to/local-development.adoc index c3d4944..33727a5 100644 --- a/docs/modules/devcentr-org/pages/how-to/local-development.adoc +++ b/docs/modules/devcentr-org/pages/how-to/local-development.adoc @@ -17,7 +17,7 @@ pnpm install pnpm dev ---- -`predev` runs `scripts/build-news.mjs`, which needs news posts under `content/news/` (always present in the repo). +`predev` runs `scripts/build-news.mjs`, which compiles news and blog posts under `content/news/` and `content/blog/` (always present in the repo). Open the URL printed by Vinxi (typically `http://localhost:3000`). @@ -55,7 +55,7 @@ Without siblings, news still builds; changelog ingest logs `changelog skip (miss | Production static build to `.output/public` | `pnpm news:build` -| Regenerate news JSON, changelog JSON, RSS, and Atom +| Regenerate news and blog JSON, changelog JSON, RSS, and Atom | `pnpm sync-advisor` | Copy and compile stack-advisor SDL → `public/catalog/` @@ -74,7 +74,7 @@ See xref:walkthrough-vscode-and-ci.adoc[VS Code & CI walkthrough] for rationale. == Troubleshooting -* **Stale news or changelog** — run `pnpm news:build` after editing `content/news/` or after pulling sibling changelog files. +* **Stale news, blog, or changelog** — run `pnpm news:build` after editing `content/news/`, `content/blog/`, or after pulling sibling changelog files. * **Advisor page empty** — run `pnpm sync-advisor` with `stack-advisor` checked out; verify `public/catalog/advisor.json` exists. * **Skills / bootstrap selector empty** — run `pnpm sync-bootstrap-profiles` with `agent-rules` checked out; verify `public/catalog/bootstrap-profiles.json` exists (gitignored, not committed). * **CI fails `skills/index.html`** — Vinxi does not emit a directory index for client-only routes; `scripts/spa-fallback.mjs` must copy the SPA shell into `.output/public/skills/`. diff --git a/docs/modules/devcentr-org/pages/index.adoc b/docs/modules/devcentr-org/pages/index.adoc index 182355d..b7e32e7 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 & links** — Help hub (`/help`), status probes (`/status`), GitHub Discussions, Slack, and GitHub org links in the header menus. +* **Assets** — Catalogue hub at `/assets` (Apps and Standards panes); Skills and Apps also appear under the Assets menu. * **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