Skip to content

docs(roadmap): mdx-content-system phase + GSC-validated content paths - #500

Draft
bntvllnt wants to merge 6 commits into
mainfrom
worktree-guides-ai-ui-pillar
Draft

docs(roadmap): mdx-content-system phase + GSC-validated content paths#500
bntvllnt wants to merge 6 commits into
mainfrom
worktree-guides-ai-ui-pillar

Conversation

@bntvllnt

@bntvllnt bntvllnt commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Localized guide foundation

Related to #469. This implements the repository-owned localized guide foundation; the broader external SEO/GEO outcome remains open in #469.

Changes

  • Adds locale-paired MDX guides for AI UI, streaming UI, and semantic design tokens.
  • Adds /guides discovery and allowlisted localized guide routes, canonical/hreflang metadata, and TechArticle JSON-LD.
  • Adds localized sitemap entries and EN/FR route, content-safety, and SEO E2E coverage.
  • Stabilizes guide discovery by resolving sitemap slugs once and running independent locale guide assertions concurrently.

Current-head validation (b7399c3)

This draft awaits independent review and verification at the current commit before any readiness or merge action.

@bntvllnt
docs(roadmap): record GSC-validated SEO paths + component gaps
ab64099 
90d GSC analysis (sc-domain:ui.vllnt.ai/.com) of real search demand:

- seo-content-engine: SYNC note with the highest-impact CAPTURE paths
  the data proves and that don't exist yet (/alternatives/radix,
  /alternatives/mui, a /react/{component} framework-qualified
  namespace), plus the honest finding that "AI UI development" has
  zero head-term demand today — a recall/GEO bet, not a capture play.
- Later: multiselect + filter-bar component gaps (GSC demand exists,
  no component in the registry today).

Planning/analysis only — no page built (per direction).
@vllnt-pilot
vllnt-pilot Bot deployed to Preview · pr-500 (ntk) July 13, 2026 12:23 Active
@vllnt-pilot

vllnt-pilot Bot commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown

ntk preview

App Status Preview
ui-registry Failed: build ui-registry: build failed: exit status 1 —
storybook Skipped (preview cell not configured) —

Built from b7399c31 · public + no-index (ADR-082) · torn down on close

@bntvllnt
docs(roadmap): add mdx-content-system phase + GSC-validated content p…
04312ea 
…aths

Adds the full MDX-max plan and the GSC-validated SEO paths as roadmap
work, per the roadmap convention.

New phase `mdx-content-system` [PLANNED] (7 tasks, sequenced before
seo-content-engine):
- Shared MDX component map, extended frontmatter schema (JSON-LD from
  frontmatter), generic /guides|/vs|/react [slug] shells, sitemap via
  content glob, an author guard for the MDX evaluate() bracket hazard,
  and migration of the 3 shipped TSX /vs pages onto the MDX shell.
- Outcome: a new content page = one .mdx file drop (no TSX, no sitemap
  edit), i18n-ready via fr.mdx with zero code change.

seo-content-engine: +7 tasks (.9-.15) for the GSC-proven paths —
/vs/radix, /vs/mui, /react/{callout,floating-action-button,code-block},
/guides/ai-ui pillar (+ mobile coming-soon), /guides/streaming-ui +
/guides/design-tokens, and the assistant-ui namespace migration.

Namespace decisions recorded: /vs = tools+libs, /alternatives =
direct competitors, /integrations = how-to-use, /guides = evergreen
reference, /blog = dated articles.
@vllnt-pilot
vllnt-pilot Bot deployed to Preview · pr-500 (ntk) July 17, 2026 14:03 Active
@bntvllnt bntvllnt changed the title docs(roadmap): GSC-validated SEO paths + component gaps docs(roadmap): mdx-content-system phase + GSC-validated content paths Jul 17, 2026
@bntvllnt bntvllnt self-assigned this Jul 29, 2026
@bntvllnt

bntvllnt commented Aug 17, 2026

Copy link
Copy Markdown
Collaborator Author

Review disposition: keep draft, bounded rework before ready

Verdict: do not close as stale/superseded. The roadmap direction still fits the current vllnt/ui priorities: issue #469 is still open as the SEO/GEO visibility-track tracker, the current ROADMAP already carries that track, and the PR's mdx-content-system phase is a sensible prerequisite for the planned content-engine paths. Keep this PR as the roadmap update, but it should remain draft until the metadata and stale references below are fixed.

Blocking before ready:

  1. Link the PR to the tracker issue. Live PR metadata still has closingIssuesReferences: [], and the latest Enforce issue-linked PRs check is failing. Add Related to #469 if this PR is just updating the roadmap under the umbrella, or create/link a narrower issue if you want this PR to close a specific task. Remove the placeholder note that says to add a link later.

  2. Refresh the PR body and checks at the current head. The body still says Issue-link CI gate: add Closes #N before merge (kept draft), and the green non-link checks are from July. After the issue link/body update, rerun or push a no-op body-only metadata refresh so the PR shows fresh status before gh pr ready.

  3. Normalize the new verification URLs to the live domain. The added roadmap tasks use https://ui.vllnt.com/... for new content-path checks at ROADMAP.md:261, 263, and 275-287. Current repo context and live site direction are ui.vllnt.ai; keep .com only where the task is explicitly validating stale-domain redirects, otherwise use .ai for future content/sitemap verification commands.

  4. Reconcile the roadmap tracker with the inserted phase. Issue Roadmap: SEO/GEO visibility track (rank for humans + AI agents) #469 currently lists the SEO/GEO track as search-consolidation -> ai-toolchain-registration -> visibility-measurement -> seo-content-engine -> backlink-authority; this PR inserts mdx-content-system between measurement and content. Update the issue body or add a child issue so the canonical tracker and ROADMAP do not disagree.

  5. Either make the new spec refs real or replace them with issue refs. This PR adds docs/specs/mdx-content-system.md and docs/specs/ai-ui-pillar.md references, but docs/specs/ does not exist on this branch. Existing roadmap drift may predate the PR, but newly added dangling refs should not be introduced without a clear follow-up owner.

Verified clean:

  • Diff scope is bounded: one file, ROADMAP.md only (+30/-3).
  • The phase/task structure follows the existing roadmap convention: kebab-case phase slug, stable task IDs, explicit validate/E2E tasks, and preserved history.
  • The implementation premise is plausible from the current tree: MDXContent, enableMDX, removeImportStatements, getPageContent, pageFrontmatterSchema, and lib/jsonld.ts all exist.

Validation evidence:

No merge/release action taken. This is a draft-disposition comment, not an approval.

@bntvllnt bntvllnt mentioned this pull request Sep 7, 2026
Open
12 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@bntvllnt bntvllnt

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bntvllnt