Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/app/utils/components-manifest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ const components: Record<string, () => Promise<unknown>> = {
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'),
Expand Down
17 changes: 17 additions & 0 deletions docs/comark-lint.config.ts
Original file line number Diff line number Diff line change
@@ -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],
Comment thread
atinux marked this conversation as resolved.
Resolved
links: {
...preset.links,
// Vue pages, not Markdown.
routes: (path: string) => ['/play', '/stream'].includes(path) || preset.links.routes(path),
},
}
18 changes: 9 additions & 9 deletions docs/content/1.getting-started/1.installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/content/10.use-cases/3.vue-ai-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 [`<MarkdownDocument>`](/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 [`<MarkdownDocument>`](/rendering/vue#markdowndocument).
:::

:::accordion-item{label="Can the model write Comark components?"}
Expand Down
4 changes: 2 additions & 2 deletions docs/content/10.use-cases/4.svelte-ai-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?"}
`<Markdown>` renders only in the browser. Parse on the server and use `<MarkdownDocument>`, or use the experimental [`<MarkdownAsync>`](/rendering/svelte#code-markdownasync-code-experimental).
`<Markdown>` renders only in the browser. Parse on the server and use `<MarkdownDocument>`, or use the experimental [`<MarkdownAsync>`](/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).
:::
::

Expand Down
2 changes: 1 addition & 1 deletion docs/content/10.use-cases/5.angular-ai-chat.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ Comark passes component props as `@Input()` values. The default slot maps to `<n
:::

:::accordion-item{label="How do I render content that is already parsed?"}
Use `<comark-markdown-document [value]="document" />` with a document from `parseMarkdown()`. It renders the document without a parse step. See [`<comark-markdown-document>`](/rendering/angular#code-comark-markdown-document).
Use `<comark-markdown-document [value]="document" />` with a document from `parseMarkdown()`. It renders the document without a parse step. See [`<comark-markdown-document>`](/rendering/angular#comark-markdown-document).
:::
::

Expand Down
2 changes: 1 addition & 1 deletion docs/content/10.use-cases/8.cms-runtime-content.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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?"}
`<Markdown>` parses asynchronously. To skip parsing in the browser, parse on the server and render the document with `<MarkdownDocument>`. It ships no parser to the client. See [`MarkdownDocument`](/rendering/vue#code-markdowndocument).
`<Markdown>` parses asynchronously. To skip parsing in the browser, parse on the server and render the document with `<MarkdownDocument>`. It ships no parser to the client. See [`MarkdownDocument`](/rendering/vue#markdowndocument).
:::

:::accordion-item{label="Does Comark work with Nuxt and Nuxt UI?"}
Expand Down
2 changes: 1 addition & 1 deletion docs/content/11.compare/9.comark-vs-markdown-to-jsx.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
12 changes: 6 additions & 6 deletions docs/content/3.rendering/2.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, fn>` | `{}` | Custom component renderers |
| [`data`](#render-options-data) | `Record<string, any>` | `undefined` | Data passed to component renderers |
| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`components`](#components) | `Record<string, fn>` | `{}` | Custom component renderers |
| [`data`](#data) | `Record<string, any>` | `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 |
Expand Down Expand Up @@ -198,7 +198,7 @@ const html2 = await renderHtml('# Document 2\n\n...')

#### Options

Same as [`renderHtml()`](#renderhtml-options).
Same as [`renderHtml()`](#options).

---

Expand Down Expand Up @@ -237,8 +237,8 @@ const html = await renderHtmlFromDocument(document)

| Option | Type | Description |
| --- | --- | --- |
| [`components`](#render-options-components) | `Record<string, fn>` | Custom component renderers |
| [`data`](#render-options-data) | `Record<string, any>` | Data passed to component renderers |
| [`components`](#components) | `Record<string, fn>` | Custom component renderers |
| [`data`](#data) | `Record<string, any>` | Data passed to component renderers |

---

Expand Down
34 changes: 17 additions & 17 deletions docs/content/3.rendering/3.vue.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ The `<Markdown>` component is the quickest way to render markdown in Vue. It han
`<Markdown>` is an **async** component and must always be wrapped in `<Suspense>`
::

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]
<script setup lang="ts">
Expand Down Expand Up @@ -101,23 +101,23 @@ defineProps<{ document: MarkdownDocument }>()
::

::callout{icon="i-lucide-package" color="warning"}
Passing a document to `<Markdown>` skips parsing at runtime, but the **parser is still bundled** because `Markdown` imports it. To keep the client bundle free of the parser, use [`<MarkdownDocument>`](#code-markdowndocument) instead.
Passing a document to `<Markdown>` skips parsing at runtime, but the **parser is still bundled** because `Markdown` imports it. To keep the client bundle free of the parser, use [`<MarkdownDocument>`](#markdowndocument) instead.
::

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string \| MarkdownDocument` | `undefined` | Markdown string or pre-parsed document (alternative to default slot) |
| [`options`](#code-markdown-props-code-options) | `ParserOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
| [`plugins`](#code-markdown-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`options`](#options) | `ParserOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, for example `"ul li"` |
| [`components`](#code-markdown-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`componentsManifest`](#code-markdown-props-code-componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
| [`components`](#components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`componentsManifest`](#componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
| [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
| `summary` | `boolean` | `false` | Only render content before `<!-- more -->` |
| [`caret`](#streaming-caret) | `boolean \| { class: string }` | `false` | Append caret to last text node |
| [`data`](#code-markdown-props-code-data) | `Record<string, unknown>` | `{}` | Runtime values referenced from markdown via `:prop="data.path"` |
| [`caret`](#caret) | `boolean \| { class: string }` | `false` | Append caret to last text node |
| [`data`](#data) | `Record<string, unknown>` | `{}` | Runtime values referenced from markdown via `:prop="data.path"` |

#### `options`

Expand Down Expand Up @@ -344,14 +344,14 @@ import { AppMarkdown } from './markdown'

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| [`extends`](#code-markdown-code-definemarkdowncomponent-code-extends) | `ReturnType<typeof defineMarkdownComponent>` | `undefined` | Inherit plugins and components from another component |
| [`extends`](#extends) | `ReturnType<typeof defineMarkdownComponent>` | `undefined` | Inherit plugins and components from another component |
| `name` | `string` | `undefined` | Component name for debugging |
| `autoUnwrap` | `boolean` | `true` | Automatically unwrap single block elements |
| `autoClose` | `boolean` | `true` | Auto-close incomplete markdown syntax |
| `linkify` | `boolean` | `true` | Auto-convert URL-like text into links |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| [`plugins`](#code-markdown-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`components`](#code-markdown-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`components`](#components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| `class` | `string` | `undefined` | Additional CSS classes for the wrapper div |

#### `extends`
Expand Down Expand Up @@ -447,11 +447,11 @@ const document = await res.json()
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `MarkdownDocument` | — | **Required.** The parsed document returned by `parseMarkdown()` |
| [`components`](#code-markdown-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`componentsManifest`](#code-markdown-props-code-componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver for lazy-loaded components |
| [`components`](#components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`componentsManifest`](#componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver for lazy-loaded components |
| [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
| [`caret`](#streaming-caret) | `boolean \| { class: string }` | `false` | Append a blinking caret to the last text node |
| [`data`](#code-markdown-props-code-data) | `Record<string, unknown>` | `{}` | Runtime values referenced from markdown via `:prop="data.path"` |
| [`caret`](#caret) | `boolean \| { class: string }` | `false` | Append a blinking caret to the last text node |
| [`data`](#data) | `Record<string, unknown>` | `{}` | Runtime values referenced from markdown via `:prop="data.path"` |

### `defineMarkdownDocumentComponent`

Expand Down Expand Up @@ -500,9 +500,9 @@ const document = await res.json()

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| [`extends`](#code-markdowndocument-code-definemarkdowndocumentcomponent-inheritance) | `ReturnType<typeof defineMarkdownDocumentComponent>` | `undefined` | Inherit component mappings from another renderer |
| [`extends`](#inheritance) | `ReturnType<typeof defineMarkdownDocumentComponent>` | `undefined` | Inherit component mappings from another renderer |
| `name` | `string` | `undefined` | Component name for debugging |
| [`components`](#code-markdown-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`components`](#components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| `class` | `string` | `undefined` | Additional CSS classes for the wrapper div |

#### Inheritance
Expand Down
10 changes: 5 additions & 5 deletions docs/content/3.rendering/4.nuxt.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,14 +97,14 @@ Pass markdown via the default slot or the `value` prop:
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string \| MarkdownDocument` | `undefined` | Markdown string or pre-parsed document (alternative to default slot) |
| [`options`](#code-markdown-props-code-options) | `ParserOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
| [`plugins`](#code-markdown-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`options`](#options) | `ParserOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, for example `"ul li"` |
| [`components`](#code-markdown-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`componentsManifest`](#code-markdown-props-code-componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
| [`components`](#components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`componentsManifest`](#componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
| [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
| `summary` | `boolean` | `false` | Only render content before `<!-- more -->` |
| [`caret`](#streaming-caret) | `boolean \| { class: string }` | `false` | Append caret to last text node |
| [`caret`](#caret) | `boolean \| { class: string }` | `false` | Append caret to last text node |

#### `options`

Expand Down
Loading
Loading