docs: SEO and AEO pass (positioning, titles, llms.txt, use cases, comparisons)

AGENTS.md

@@ -35,7 +35,7 @@ This is a **monorepo** containing the Comark Markdown parser, document model, pl
 │   ├── 3.cli/            # CLI examples (ANSI output, prompts, perf tracing)
 │   ├── 3.plugins/        # Plugin examples (math, mermaid, highlight, rangi, footnotes, ...)
 │   └── 4.ai/             # AI streaming examples (Nuxt + AI SDK)
-├── docs/                 # Documentation site (comark-docs layer)
+├── docs/                 # Documentation site (comark-docs layer; llms topic files in docs/server/routes/llms-*.txt.get.ts)
 ├── playground/           # Nuxt playground (`pnpm dev:playground`)
 ├── benchmarks/           # mitata benchmarks for parse/render/plugins
 ├── scripts/              # Build/sync/release scripts
@@ -684,7 +684,7 @@ Example:
 // Output:
 {
   nodes: [
-    ['h1', { id: 'hello' }, 'Hello ', ['strong', {}, 'World']]
+    ['h1', { id: 'hello-world' }, 'Hello ', ['strong', {}, 'World']]
   ],
   frontmatter: {},
   meta: {}
@@ -979,6 +979,8 @@ chore: update dependencies           # No version bump
    - `3.rendering/` — Vue/React/Svelte/Angular/HTML/ANSI renderer changes
    - `4.plugins/` — Plugin changes
    - `5.reference/` — Public API and options changes
+   - `10.use-cases/` — Task guides (AI chat streaming, generative UI, CMS, CLI, email/RSS)
+   - `11.compare/` — Comparisons with other libraries (facts must be sourced; no unverified numbers)
 
 ### Documentation Checklist
 

docs/app/app.config.ts

@@ -13,9 +13,10 @@ export default defineAppConfig({
     nav: [
       {
         label: 'Documentation',
-        sections: ['getting-started', 'syntax', 'rendering', 'reference', 'compare', 'kb'],
+        sections: ['getting-started', 'syntax', 'rendering', 'reference', 'kb'],
       },
       { label: 'Plugins', sections: ['plugins'], link: 'section' as const },
+      { label: 'Use cases', sections: ['use-cases', 'compare'], link: 'section' as const },
       { label: 'Examples', sections: ['examples'], link: 'section' as const },
       { label: 'Playground', to: '/play' },
       { label: 'Ecosystem', sections: ['ecosystem'], link: 'section' as const },
@@ -51,21 +52,25 @@ export default defineAppConfig({
   docs: {
     ogImage: {
       mark: 'comark' as const,
-      tagline: 'Parse and render Markdown anywhere',
+      tagline: 'The Markdown parser and renderer for everything',
     },
     llms: {
       description:
-        'Parse and render Markdown anywhere with one JavaScript library for HTML, ANSI, Vue, React, Svelte and Angular, plus plugins and streaming.',
+        'Comark is an open-source Markdown parser and renderer with components, attributes and plugins. It streams AI output to React, Vue, Svelte, Angular, HTML and the terminal.',
     },
     schemaOrg: {
       description:
-        'Parse and render Markdown anywhere with one JavaScript library for HTML, ANSI, Vue, React, Svelte and Angular, plus plugins and streaming.',
+        'Comark is an open-source Markdown parser and renderer with components, attributes and plugins. It streams AI output to React, Vue, Svelte, Angular, HTML and the terminal.',
       applicationCategory: 'DeveloperApplication',
       operatingSystem: 'Any',
       offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
       license: 'https://github.com/comarkdown/comark/blob/main/LICENSE',
-      sameAs: ['https://github.com/comarkdown/comark', 'https://comark.dev'],
+      sameAs: ['https://github.com/comarkdown/comark', 'https://www.npmjs.com/package/comark'],
       programmingLanguage: 'TypeScript',
+      organization: {
+        url: 'https://comark.dev',
+        sameAs: ['https://github.com/comarkdown', 'https://www.npmjs.com/org/comark'],
+      },
     },
   },
 

docs/app/pages/play/index.vue

@@ -2,9 +2,9 @@
 definePageMeta({
   footer: false,
 })
-const title = 'Playground - Comark'
+const title = 'Markdown Playground'
 const description =
-  'Try Comark live in the browser. Edit markdown with component syntax and see the rendered output in real-time.'
+  'Try Comark live in the browser. Edit Markdown with component syntax and see the rendered output as you type.'
 useSeoMeta({
   title,
   description,

docs/app/pages/stream.vue

@@ -8,7 +8,7 @@ import landingMD from '~~/content/index.md?raw'
 definePageMeta({
   footer: false,
 })
-const title = 'Streaming Demo - Comark'
+const title = 'Streaming Markdown Demo'
 const description =
   'See Comark streaming in action. Watch markdown content parse and render in real-time as it arrives.'
 useSeoMeta({

docs/content/1.getting-started/0.introduction.md

@@ -1,6 +1,8 @@
 ---
-title: Introduction
-description: Parse and render CommonMark and GFM anywhere with Comark, a JavaScript library for HTML, ANSI, Vue, React, Svelte, Angular, plugins, and streaming.
+title: 'What Is Comark? Markdown Parser and Renderer'
+description: 'Comark is an open-source Markdown parser and renderer with components, attributes and plugins. It streams AI output to React, Vue, Svelte, Angular, HTML and the terminal.'
+navigation:
+  title: Introduction
 links:
   - label: Installation
     to: /getting-started/installation
@@ -15,9 +17,7 @@ links:
     variant: soft
 ---
 
-## What is Comark?
-
-**Comark** is a JavaScript library for parsing and rendering Markdown anywhere. Give it standard CommonMark or GitHub Flavored Markdown (GFM), then render the same source to HTML, ANSI, Vue, React, Svelte, or Angular.
+**Comark** is an open-source Markdown parser and renderer with components, attributes and plugins. It streams AI output to React, Vue, Svelte, Angular, HTML and the terminal. Give it standard CommonMark or GitHub Flavored Markdown (GFM), and render the same source to any of these targets.
 
 Parsing and rendering are decoupled through a compact, serializable [`MarkdownDocument`](/getting-started/document-model). Parse on the server, in the browser, in a worker, during a build, or as content streams in. You can then inspect, transform, cache, serialize, or render the document without tying your content to one output target.
 
@@ -214,6 +214,6 @@ For detailed, honest comparisons, see [Comark vs MDX](/compare/comark-vs-mdx), [
   :::
 
   :::accordion-item{label="Do I have to use components?"}
-  No. Comark is a superset of CommonMark and GFM, so plain Markdown parses unchanged. Components and [attributes](/syntax/attributes) are opt-in syntax.
+  No. Plain CommonMark and GFM parse as standard Markdown, with a few [documented differences](/syntax/markdown#differences-from-commonmark-and-gfm). Components and [attributes](/syntax/attributes) are opt-in syntax.
   :::
 ::

docs/content/10.use-cases/.navigation.yml

@@ -0,0 +1,2 @@
+title: Use cases
+icon: i-lucide-lightbulb