diff --git a/AGENTS.md b/AGENTS.md index a795bc4f7..b72ca8d34 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -903,7 +903,7 @@ pnpm stub # Point every package's dist/ at src/ for local dev (runs on p pnpm test # Run all package tests pnpm test:spec # Run the SPEC fixtures only pnpm bench # Run the CodSpeed Vitest benches (benchmarks/*.bench.ts; wall-clock locally) -pnpm lint # oxlint + oxfmt --check +pnpm lint # oxlint + oxfmt --check + comark-lint on docs/content pnpm lint:fix # oxlint --fix + oxfmt (write) pnpm typecheck # tsc --noEmit against the root tsconfig pnpm verify # Run lint + test + typecheck @@ -915,6 +915,10 @@ Linting and formatting use [oxlint](https://oxc.rs/docs/guide/usage/linter) and `.oxfmtrc.json` (no semicolons, single quotes, 120 columns, ES5 trailing commas). There is no ESLint or Prettier config. +The docs content is linted with [comark-linter](https://comark-ui.onmax.me/lint/) (`pnpm --filter comark-docs-site lint`): +unknown components, unclosed blocks, and broken links and anchors. `docs/comark-lint.config.ts` extends the +comark-docs layer's preset with the site's own `app/components/prose/` components and its Vue pages. + Utility scripts: ```bash diff --git a/docs/app/utils/components-manifest.ts b/docs/app/utils/components-manifest.ts index 3793913ca..961a00f11 100644 --- a/docs/app/utils/components-manifest.ts +++ b/docs/app/utils/components-manifest.ts @@ -26,6 +26,8 @@ const components: Record Promise> = { Timeline: () => import('@nuxt/ui/components/Timeline.vue'), User: () => import('@nuxt/ui/components/User.vue'), PageHero: () => import('@nuxt/ui/components/PageHero.vue'), + // `::landing-hero` in content/index.md, which the comark-docs layer maps to PageHero on its landing page. + LandingHero: () => import('@nuxt/ui/components/PageHero.vue'), PageAnchors: () => import('@nuxt/ui/components/PageAnchors.vue'), PageSection: () => import('@nuxt/ui/components/PageSection.vue'), PageHeader: () => import('@nuxt/ui/components/PageHeader.vue'), diff --git a/docs/comark-lint.config.ts b/docs/comark-lint.config.ts new file mode 100644 index 000000000..af48e4260 --- /dev/null +++ b/docs/comark-lint.config.ts @@ -0,0 +1,17 @@ +import { readdirSync } from 'node:fs' +import preset from 'comark-docs/lint.mjs' + +// The site's own Markdown components: @comark/nuxt registers app/components/prose/ globally. +const prose = readdirSync('app/components/prose').map((file) => + file.replace(/\.vue$/, '').replace(/[A-Z]/g, (c, i) => (i ? '-' : '') + c.toLowerCase()) +) + +export default { + ...preset, + components: [...preset.components, ...prose], + links: { + ...preset.links, + // Vue pages, not Markdown. + routes: (path: string) => ['/play', '/stream'].includes(path) || preset.links.routes(path), + }, +} diff --git a/docs/content/1.getting-started/1.installation.md b/docs/content/1.getting-started/1.installation.md index da9c64331..a410a3a21 100644 --- a/docs/content/1.getting-started/1.installation.md +++ b/docs/content/1.getting-started/1.installation.md @@ -125,8 +125,8 @@ Comark packages share one pipeline. The core parser produces a serializable `Mar Use these when you need to render Markdown as an interactive document in Vue, React, Nuxt, Svelte, or Angular. -::tabs{class="gap-0"} - ::tab-item{label="Vue" icon="i-logos-vue"} +::tabs + ::tabs-item{label="Vue" icon="i-logos-vue"} ::code-group ```bash [pnpm] pnpm add @comark/vue @@ -142,7 +142,7 @@ Use these when you need to render Markdown as an interactive document in Vue, Re ``` :: :: - ::tab-item{label="React" icon="i-logos-react"} + ::tabs-item{label="React" icon="i-logos-react"} ::code-group ```bash [pnpm] pnpm add @comark/react @@ -158,12 +158,12 @@ Use these when you need to render Markdown as an interactive document in Vue, Re ``` :: :: - ::tab-item{label="Nuxt" icon="i-logos-nuxt-icon"} + ::tabs-item{label="Nuxt" icon="i-logos-nuxt-icon"} ```bash [Terminal] npx nuxt add comark ``` :: - ::tab-item{label="Svelte" icon="i-logos-svelte-icon"} + ::tabs-item{label="Svelte" icon="i-logos-svelte-icon"} ::code-group ```bash [pnpm] pnpm add @comark/svelte @@ -179,7 +179,7 @@ Use these when you need to render Markdown as an interactive document in Vue, Re ``` :: :: - ::tab-item{label="Angular" icon="i-logos-angular-icon"} + ::tabs-item{label="Angular" icon="i-logos-angular-icon"} ::code-group ```bash [pnpm] pnpm add @comark/angular @@ -201,8 +201,8 @@ Use these when you need to render Markdown as an interactive document in Vue, Re Use these when you need a string output with no UI framework involved like server-side HTML generation, static site builds, or CLI tooling. -::tabs{class="gap-0"} - ::tab-item{label="HTML" icon="i-vscode-icons-file-type-html"} +::tabs + ::tabs-item{label="HTML" icon="i-vscode-icons-file-type-html"} ::code-group ```bash [pnpm] pnpm add @comark/html @@ -218,7 +218,7 @@ Use these when you need a string output with no UI framework involved like serve ``` :: :: - ::tab-item{label="ANSI" icon="i-lucide-terminal"} + ::tabs-item{label="ANSI" icon="i-lucide-terminal"} ::code-group ```bash [pnpm] pnpm add @comark/ansi diff --git a/docs/content/10.use-cases/3.vue-ai-chat.md b/docs/content/10.use-cases/3.vue-ai-chat.md index 05d5021a4..71d44726d 100644 --- a/docs/content/10.use-cases/3.vue-ai-chat.md +++ b/docs/content/10.use-cases/3.vue-ai-chat.md @@ -143,7 +143,7 @@ const plugins = [ ::: :::accordion-item{label="Can I render the answer on the server?"} - Chat messages arrive in the browser, so client rendering is enough. For server-rendered content, parse on the server and render with [``](/rendering/vue#code-markdowndocument). + Chat messages arrive in the browser, so client rendering is enough. For server-rendered content, parse on the server and render with [``](/rendering/vue#markdowndocument). ::: :::accordion-item{label="Can the model write Comark components?"} diff --git a/docs/content/10.use-cases/4.svelte-ai-chat.md b/docs/content/10.use-cases/4.svelte-ai-chat.md index c109cf324..9faeefb68 100644 --- a/docs/content/10.use-cases/4.svelte-ai-chat.md +++ b/docs/content/10.use-cases/4.svelte-ai-chat.md @@ -143,11 +143,11 @@ Raw HTML in model output is parsed into nodes by default. Add the [security plug ::: :::accordion-item{label="Why is my Markdown missing from the server HTML?"} - `` renders only in the browser. Parse on the server and use ``, or use the experimental [``](/rendering/svelte#code-markdownasync-code-experimental). + `` renders only in the browser. Parse on the server and use ``, or use the experimental [``](/rendering/svelte#markdownasync-experimental). ::: :::accordion-item{label="How do I map a component to a Svelte component?"} - Pass a `components` map, for example `components={{ alert: Alert }}`. See [Svelte components](/rendering/svelte#code-markdown-props-code-components). + Pass a `components` map, for example `components={{ alert: Alert }}`. See [Svelte components](/rendering/svelte#components). ::: :: diff --git a/docs/content/10.use-cases/5.angular-ai-chat.md b/docs/content/10.use-cases/5.angular-ai-chat.md index 845ba3e30..fa21f4c71 100644 --- a/docs/content/10.use-cases/5.angular-ai-chat.md +++ b/docs/content/10.use-cases/5.angular-ai-chat.md @@ -141,7 +141,7 @@ Comark passes component props as `@Input()` values. The default slot maps to `` with a document from `parseMarkdown()`. It renders the document without a parse step. See [``](/rendering/angular#code-comark-markdown-document). + Use `` with a document from `parseMarkdown()`. It renders the document without a parse step. See [``](/rendering/angular#comark-markdown-document). ::: :: diff --git a/docs/content/10.use-cases/8.cms-runtime-content.md b/docs/content/10.use-cases/8.cms-runtime-content.md index 41cb02483..402897752 100644 --- a/docs/content/10.use-cases/8.cms-runtime-content.md +++ b/docs/content/10.use-cases/8.cms-runtime-content.md @@ -111,7 +111,7 @@ const markdown = await renderMarkdown(document) await savePage(row.slug, markdown) ``` -The output can differ from the original formatting. For example, a component with more than three attributes moves them to a YAML block. See the [`maxInlineAttributes`](/reference/render#options-maxinlineattributes) option. +The output can differ from the original formatting. For example, a component with more than three attributes moves them to a YAML block. See the [`maxInlineAttributes`](/reference/render#maxinlineattributes) option. ## FAQ diff --git a/docs/content/11.compare/11.comark-vs-vue-markdown-render.md b/docs/content/11.compare/11.comark-vs-vue-markdown-render.md index 527552046..437b3c0c7 100644 --- a/docs/content/11.compare/11.comark-vs-vue-markdown-render.md +++ b/docs/content/11.compare/11.comark-vs-vue-markdown-render.md @@ -143,7 +143,7 @@ If you render trusted, static Markdown and don't need components, vue-markdown-r ::: :::accordion-item{label="Why does Comark's Markdown component need Suspense?"} - `` parses asynchronously. To skip parsing in the browser, parse on the server and render the document with ``. It ships no parser to the client. See [`MarkdownDocument`](/rendering/vue#code-markdowndocument). + `` parses asynchronously. To skip parsing in the browser, parse on the server and render the document with ``. It ships no parser to the client. See [`MarkdownDocument`](/rendering/vue#markdowndocument). ::: :::accordion-item{label="Does Comark work with Nuxt and Nuxt UI?"} diff --git a/docs/content/11.compare/9.comark-vs-markdown-to-jsx.md b/docs/content/11.compare/9.comark-vs-markdown-to-jsx.md index 555bc0a42..5cc09bd76 100644 --- a/docs/content/11.compare/9.comark-vs-markdown-to-jsx.md +++ b/docs/content/11.compare/9.comark-vs-markdown-to-jsx.md @@ -117,7 +117,7 @@ const plugins = [security({ blockedTags: ['script', 'iframe', 'object', 'embed', - **Zero dependencies**: Comark's parser bundle is larger, because it includes markdown-exit, a YAML parser, an HTML parser, and entity tables. - **Output targets**: React Native and Solid are outputs that Comark doesn't have. -- **React Server Components**: the `Markdown` component detects RSC and needs no `'use client'` directive. Comark's [`MarkdownDocument`](/rendering/react#code-markdowndocument) also renders in a Server Component. +- **React Server Components**: the `Markdown` component detects RSC and needs no `'use client'` directive. Comark's [`MarkdownDocument`](/rendering/react#markdowndocument) also renders in a Server Component. - **Secure defaults**: the tag filter and raw HTML sanitization need no setup. If you render trusted Markdown with JSX components in React, React Native, or Solid, markdown-to-jsx is a good fit. Choose Comark when you need components with named slots, streaming that completes syntax, or Svelte, Angular, or terminal output. diff --git a/docs/content/3.rendering/2.html.md b/docs/content/3.rendering/2.html.md index 6b54e97db..ed4f34bcb 100644 --- a/docs/content/3.rendering/2.html.md +++ b/docs/content/3.rendering/2.html.md @@ -89,9 +89,9 @@ This is a **bold** statement with a [link](https://example.com). | Option | Type | Default | Description | | --- | --- | --- | --- | -| [`plugins`](#render-options-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins | -| [`components`](#render-options-components) | `Record` | `{}` | Custom component renderers | -| [`data`](#render-options-data) | `Record` | `undefined` | Data passed to component renderers | +| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins | +| [`components`](#components) | `Record` | `{}` | Custom component renderers | +| [`data`](#data) | `Record` | `undefined` | Data passed to component renderers | | `autoClose` | `boolean` | `true` | Close incomplete Markdown and components before parsing | | `autoUnwrap` | `boolean` | `true` | Remove a single paragraph wrapper inside components | | `linkify` | `boolean` | `true` | Convert URL-like text into links | @@ -198,7 +198,7 @@ const html2 = await renderHtml('# Document 2\n\n...') #### Options -Same as [`renderHtml()`](#renderhtml-options). +Same as [`renderHtml()`](#options). --- @@ -237,8 +237,8 @@ const html = await renderHtmlFromDocument(document) | Option | Type | Description | | --- | --- | --- | -| [`components`](#render-options-components) | `Record` | Custom component renderers | -| [`data`](#render-options-data) | `Record` | Data passed to component renderers | +| [`components`](#components) | `Record` | Custom component renderers | +| [`data`](#data) | `Record` | Data passed to component renderers | --- diff --git a/docs/content/3.rendering/3.vue.md b/docs/content/3.rendering/3.vue.md index 118d7b1ff..d4a2e10d7 100644 --- a/docs/content/3.rendering/3.vue.md +++ b/docs/content/3.rendering/3.vue.md @@ -49,7 +49,7 @@ The `` component is the quickest way to render markdown in Vue. It han `` is an **async** component and must always be wrapped in `` :: -For server-side rendering, use the [`MarkdownDocument`](#code-markdowndocument) component combined with parsing on the server instead. +For server-side rendering, use the [`MarkdownDocument`](#markdowndocument) component combined with parsing on the server instead. ```vue [App.vue]