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
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ packages/comark/
│ │ ├── heading-links.ts # Links headings to their own `id`
│ │ ├── headings.ts # Deprecated alias → title-description (remove next major)
│ │ ├── json-render.ts # `json-render` spec fences expanded into nodes
│ │ ├── linkify.ts # Bare URL autolinks via linkify-it 6 (default via registerDefaultPlugins; linkify-it options, fuzzyLink opt-in)
│ │ ├── punctuation.ts # Smart quotes and dashes
│ │ ├── shiki.ts # Shiki with bundled default theme + language loaders (peer: shiki)
│ │ ├── shiki/core.ts # Shiki without default theme/language imports
Expand Down Expand Up @@ -532,6 +533,7 @@ import titleDescription from 'comark/plugins/title-description'
import headingLinks from 'comark/plugins/heading-links'
import punctuation from 'comark/plugins/punctuation'
import jsonRender from 'comark/plugins/json-render'
import linkify from 'comark/plugins/linkify' // default via registerDefaultPlugins; add explicitly with comark/core
import security from 'comark/plugins/security'
import summary from 'comark/plugins/summary'
import taskList from 'comark/plugins/task-list' // default via registerDefaultPlugins
Expand Down Expand Up @@ -653,7 +655,8 @@ const result = await parseMarkdown(markdownContent, {
autoUnwrap: true, // Remove <p> wrappers from single-paragraph containers
autoClose: true, // Auto-close incomplete syntax; also accepts (markdown) => string
unwrap: 'p', // Strip top-level wrapper tags (MDC unwrap); merges paragraphs
registerDefaultPlugins: true, // frontmatter, html, alert, task-list, components, attributes; false to disable
registerDefaultPlugins: true, // linkify, frontmatter, html, alert, task-list, components, attributes; false to disable
// linkify: false // deprecated (warns): use registerDefaultPlugins: false + linkify()
})

result.nodes // Node[]
Expand Down Expand Up @@ -894,6 +897,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup and the example-app wor
1. Token processing is in `packages/comark/src/internal/parse/token-processor.ts`
2. Test with `packages/comark/test/index.test.ts` (loads the `SPEC/` fixtures; `SPEC=SPEC/COMARK/foo.md pnpm vitest run test/index.test.ts` runs one)
3. Check streaming still works with `packages/comark/test/streaming.test.ts`
4. Import from `markdown-exit/core`, never `markdown-exit`: the root entry pulls in linkify-it, which `parse.ts` loads lazily only for parsers with `linkify` on
5. Decode attribute values with `decodeHTMLAttribute` from `src/internal/entities.ts`, not `entities`: it reads the `character-entities` table markdown-exit already ships, so bundles hold one table

### Adding component features

Expand Down
26 changes: 21 additions & 5 deletions docs/app/components/Playground.vue
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,13 @@ import titleDescription from '@comark/nuxt/plugins/title-description'
import toc from '@comark/nuxt/plugins/toc'
import summary from '@comark/nuxt/plugins/summary'
import security from '@comark/nuxt/plugins/security'
import linkify from '@comark/nuxt/plugins/linkify'
import frontmatter from '@comark/nuxt/plugins/frontmatter'
import html from '@comark/nuxt/plugins/html'
import alert from '@comark/nuxt/plugins/alert'
import taskList from '@comark/nuxt/plugins/task-list'
import components from '@comark/nuxt/plugins/components'
import attributes from '@comark/nuxt/plugins/attributes'

import { renderMarkdown } from 'comark/render'
import { Splitpanes, Pane } from 'splitpanes'
Expand Down Expand Up @@ -209,11 +216,19 @@ const parseOptionDefs = [
},
] as const

const activePlugins = computed<ComarkPlugin[]>(() =>
pluginDefs
// The other defaults always run; registering them explicitly lets linkify be toggled on its own.
const activePlugins = computed<ComarkPlugin[]>(() => [
...(parseOptions.value.linkify ? [linkify()] : []),
frontmatter(),
html(),
alert(),
taskList(),
components(),
attributes(),
...pluginDefs
.filter((p) => pluginToggles.value[p.key as keyof typeof pluginToggles.value])
.map((p) => p.factory() as ComarkPlugin)
)
.map((p) => p.factory() as ComarkPlugin),
])

const enabledPluginCount = computed<number>(() => Object.values(pluginToggles.value).filter(Boolean).length)

Expand Down Expand Up @@ -258,7 +273,7 @@ async function updatePreview(): Promise<void> {
plugins: activePlugins.value,
autoUnwrap: parseOptions.value.autoUnwrap,
autoClose: parseOptions.value.autoClose,
linkify: parseOptions.value.linkify ?? true,
registerDefaultPlugins: false,
})
document.value = result
parseTime.value = Math.round((performance.now() - start) * 10) / 10
Expand Down Expand Up @@ -397,6 +412,7 @@ watch(completion, async (md) => {
plugins: activePlugins.value,
autoUnwrap: parseOptions.value.autoUnwrap,
autoClose: true,
registerDefaultPlugins: false,
})
document.value = result
} catch {
Expand Down
2 changes: 1 addition & 1 deletion docs/content/2.syntax/1.markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ Text nodes in Comark are plain strings, similar to HTML text nodes. To add custo
Add custom attributes to links and images with the [Attributes](/syntax/attributes) syntax: `[Link](url){target="_blank"}`.
::

Bare URLs like `https://example.com` are automatically converted into clickable links. Disable this with the [`linkify`](/reference/parse#options) option (`{ linkify: false }`).
Bare URLs like `https://example.com` are automatically converted into clickable links. Domains without a scheme, like `www.example.com`, need the plugin's `fuzzyLink` option. This comes from the default [linkify plugin](/plugins/defaults/linkify), which is left out with `registerDefaultPlugins: false`.

## Blockquotes

Expand Down
4 changes: 2 additions & 2 deletions docs/content/3.rendering/2.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,8 @@ This is a **bold** statement with a [link](https://example.com).
| [`transformNode`](#transformnode) | `NodeTransform \| NodeTransform[]` | `undefined` | Change the tag or props of element nodes right before they render |
| `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 |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| `unwrap` | `boolean \| string \| string[]` | `false` | Remove selected wrapper tags from the parsed document |

`renderHtml()` accepts all [`ParserOptions`](/reference/parse#options) in addition to the renderer options above.
Expand Down
4 changes: 2 additions & 2 deletions docs/content/3.rendering/3.vue.md
Original file line number Diff line number Diff line change
Expand Up @@ -379,8 +379,8 @@ import { AppMarkdown } from './markdown'
| `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`) |
| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`components`](#components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
| [`transformNode`](#transformnode) | `NodeTransform \| NodeTransform[]` | `undefined` | Node transforms that run before the instance's own `transformNode` |
Expand Down
4 changes: 2 additions & 2 deletions docs/content/3.rendering/5.react.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,8 +337,8 @@ export default function App() {
| `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`) |
| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
| [`components`](#components) | `Record<string, ComponentType>` | `{}` | Custom React component mappings |
| [`transformNode`](#transformnode) | `NodeTransform \| NodeTransform[]` | `undefined` | Node transforms that run before the instance's own `transformNode` |
Expand Down
4 changes: 2 additions & 2 deletions docs/content/3.rendering/8.ansi.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,8 +83,8 @@ This is a bold statement with a link (https://example.com).
| `width` | `number` | `80` | Terminal width for HR and code block headers |
| `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 |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead |
| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) |
| `unwrap` | `boolean \| string \| string[]` | `false` | Remove selected wrapper tags from the parsed document |

*Automatically set to `false` when the `NO_COLOR` env var is present.
Expand Down
68 changes: 68 additions & 0 deletions docs/content/4.plugins/0.defaults/linkify.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
title: Linkify
description: Plugin for converting URL-like text into links.
seo:
title: Linkify Plugin
navigation:
icon: i-lucide-link
links:
- label: Parse API
icon: i-lucide-file-code
to: /reference/parse
color: neutral
variant: soft
---

The `comark/plugins/linkify` plugin converts URLs such as `https://comark.dev` and emails such as `hi@comark.dev` into links, using [linkify-it](https://github.com/markdown-it/linkify-it). Domains without a scheme, such as `www.example.com`, are linked only with [`fuzzyLink`](#options).

The plugin is **enabled by default** via `registerDefaultPlugins`. No installation or registration required.

```typescript
import { parseMarkdown } from 'comark'

await parseMarkdown('Read https://comark.dev')
```

Explicit registration is only needed when default plugins are disabled, or with `comark/core`. List it before markdown-it plugins that call `md.linkify.add()`:

```typescript
import { parseMarkdown } from 'comark'
import linkify from 'comark/plugins/linkify'
import components from 'comark/plugins/components'

const result = await parseMarkdown(content, {
registerDefaultPlugins: false,
plugins: [linkify(), components()],
})
```

## Options

`linkify()` accepts linkify-it's recognition options. Pass a configured `linkify()` in `plugins` to replace the default:

```typescript
import { parseMarkdown } from 'comark'
import linkify from 'comark/plugins/linkify'

await parseMarkdown('Visit www.example.com', {
plugins: [linkify({ fuzzyLink: true })],
})
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `fuzzyLink` | `boolean` | `false` | Link domains without a scheme, such as `www.example.com` or `example.com`. Slower on long text |
| `fuzzyEmail` | `boolean` | `true` | Link emails without `mailto:` |
| `fuzzyIP` | `boolean` | `false` | Allow IP addresses in fuzzy links. Can match version numbers |
| `urlAuth` | `boolean` | `false` | Link URLs that contain credentials, such as `https://user:pass@example.com` |
| `tlds` | `string[]` | linkify-it's list | Top-level domains allowed in fuzzy links. Replaces the default list |
| `maxLength` | `number` | `10000` | Maximum link length |
| `'---'` | `boolean` | `false` | End a link at `---`, treating it as a long dash |

::note
Before linkify-it 6, Comark linked `www.example.com` and `user:pass@` URLs by default. Pass `linkify({ fuzzyLink: true, urlAuth: true })` to keep that behavior.
::

::warning
The `linkify` parser option is **deprecated**. It logs a warning and will be removed in a future major version. Replace `linkify: false` with `registerDefaultPlugins: false`, then register only the default plugins you need.
::
6 changes: 5 additions & 1 deletion docs/content/4.plugins/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ All Comark plugins are part of the core `comark` package, while optional renderi
These plugins are **enabled by default** whenever you call `parseMarkdown()` or `createMarkdownParser()` (or a framework `<Markdown>` component). You do not need to install or register them.

::card-group{cols="2"}
::card{icon="i-lucide-link" title="Linkify" to="/plugins/defaults/linkify"}
Convert URL-like text into links
::

::card{icon="i-lucide-file-spreadsheet" title="Frontmatter" to="/plugins/defaults/frontmatter"}
Parse a leading YAML frontmatter block into `tree.frontmatter`
::
Expand Down Expand Up @@ -49,7 +53,7 @@ Turn them all off with `registerDefaultPlugins: false`:
```typescript
import { parseMarkdown } from 'comark'

// Plain markdown only — no components, attributes, HTML, alerts, or task lists
// Plain markdown only — no autolinks, components, attributes, HTML, alerts, or task lists
const result = await parseMarkdown(content, {
registerDefaultPlugins: false,
})
Expand Down
6 changes: 3 additions & 3 deletions docs/content/5.reference/1.parse.md
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,7 @@ console.timeEnd('createMarkdownParser x1000')

Use `comark/core` when you want to choose every plugin yourself and keep the default plugins out of your bundle. It accepts the same options as `comark`, with two differences:

- Only the plugins in `plugins` run. `registerDefaultPlugins` is not accepted.
- Only the plugins in `plugins` run. `registerDefaultPlugins` is not accepted; add [`linkify()`](/plugins/defaults/linkify) to link bare URLs.
- `autoClose` is a function or `undefined` (the default, which skips auto-closing). Pass `autoCloseMarkdown` from `comark/auto-close` to opt in.

```typescript [core.ts]
Expand Down Expand Up @@ -395,9 +395,9 @@ Both `parseMarkdown()` and `createMarkdownParser()` accept the same `ParserOptio
| `autoClose` | `boolean \| (markdown: string, streaming?: boolean) => string` | `true` | Auto-close incomplete markdown syntax, or use a custom completion function. `streaming` is `true` when the parse was called with `{ streaming: true }`. |
| `unwrap` | `boolean \| string \| string[]` | `false` | Remove wrapper tags from the tree, hoisting their children (MDC `unwrap` behaviour). `true` unwraps `p`; a comma/whitespace-separated string or array unwraps the listed tags; `'*'` matches any tag. Tags apply sequentially (each descends one level), and adjacent text is merged into a single string. |

| `linkify` | `boolean` | `true` | Auto-convert URL-like text into links. Set `false` to disable |
| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) only when needed. Still honored (over `registerDefaultPlugins`) and logs a warning |
| `headingIds` | `boolean \| 'nested' \| 'flat'` | `true` | Auto-generate `id` attributes for `h1`–`h6` from visible heading text (not tag or component names). `true`/`'flat'` uses the heading's own text only (`install`); `'nested'` prefixes each id with its parent heading's id (`setup-install`); `false` disables auto ids. Unicode letters, marks, and numbers are kept (`## Café` → `café`); punctuation and symbols are dropped, and a heading that slugifies to nothing gets no id. Ids are unique per document: duplicates get a `-1`, `-2`, ... suffix (`options`, `options-1`, `options-2`). An explicit `id` attribute wins. See [Headings](/syntax/markdown#headings). |
| `registerDefaultPlugins` | `boolean` | `true` | Register the built-in default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). Set `false` to disable them. |
| `registerDefaultPlugins` | `boolean` | `true` | Register the built-in default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). Set `false` to disable them. |
| `plugins` | `ComarkPlugin[]` | `[]` | Ordered plugins to run after the defaults. A same-name plugin replaces its default; duplicate explicit names keep the first instance. See [Default plugins](/plugins#default-plugins). |
| `tracer` | `ComarkTracer` | `undefined` | Timing recorder for the parse pipeline — see [Timing the parse](#timing-the-parse) |

Expand Down
2 changes: 1 addition & 1 deletion docs/content/5.reference/3.reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -358,7 +358,7 @@ interface ParserOptions {
autoClose?: boolean | AutoCloseFunction // default: true
unwrap?: boolean | string | string[] // strip top-level wrapper tags, e.g. 'p' (default: false)

linkify?: boolean // default: true
linkify?: boolean // deprecated: use registerDefaultPlugins: false + linkify()
headingIds?: boolean | 'nested' | 'flat' // default: true ('flat') — slug from visible text; duplicates get -1, -2, … (keeps Unicode letters/numbers, omits symbol-only ids); explicit id wins
registerDefaultPlugins?: boolean // default: true
plugins?: ComarkPlugin[]
Expand Down
2 changes: 1 addition & 1 deletion packages/comark-angular/test/define-component.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ describe('defineMarkdownComponent', () => {
it('accepts parse options in config', () => {
const Defined = defineMarkdownComponent({
autoClose: true,
linkify: true,
autoUnwrap: false,
})
expect(Defined).toBeDefined()
})
Expand Down
8 changes: 7 additions & 1 deletion packages/comark-react/test/streaming.browser.test.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import React, { act, Component, StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest'
import { parseMarkdown } from 'comark'
import type { ComarkPlugin, MarkdownDocument } from 'comark'
import { MarkdownClient } from '../src/components/MarkdownClient'
import { Markdown } from '../src/components/Markdown'
Expand All @@ -9,6 +10,11 @@ import { defineMarkdownComponent } from '../src/index'

Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true })

// The first parse with linkify loads linkify-it, which settles outside `act`.
beforeAll(async () => {
await parseMarkdown('')
})

let container: HTMLDivElement
let root: ReturnType<typeof createRoot>
beforeEach(() => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@ for (const [name, component] of [
component,
value,
streaming: true,
options: { linkify: false },
options: { registerDefaultPlugins: false },
})
await expect.element(screen.getByText('Tail')).toBeInTheDocument()
expect(screen.container.querySelector('a')).toBeNull()

await screen.rerender({ options: { linkify: true } })
await screen.rerender({ options: { registerDefaultPlugins: true } })
await expect.element(screen.getByRole('link')).toHaveAttribute('href', 'https://example.com')

const plugin: ComarkPlugin = {
Expand Down
4 changes: 3 additions & 1 deletion packages/comark/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,10 @@
"release:dry": "release-it --dry-run"
},
"dependencies": {
"entities": "catalog:",
"character-entities": "catalog:",
"character-entities-legacy": "catalog:",
"js-yaml": "catalog:",
"linkify-it": "catalog:",
"markdown-exit": "catalog:"
},
"devDependencies": {
Expand Down
Loading
Loading