` | | `lazyImages` | `boolean` | `true` | Add `loading="lazy"` to all images | | `safeLinks` | `boolean \| object` | `false` | Add `rel="nofollow noopener noreferrer"` + `target="_blank"` to external links. Object: `{ externalRel?, externalTarget?, baseUrl? }` | | `ugc` | `boolean` | `false` | Shorthand: enables `sanitize` + `safeLinks` + disables `allowHtml` | | `blocks` | `BlockRule[]` | — | Selective block rules for tree-shaking (import from `/blocks`) | | `renderer` | `Partial
OK
SafeTitle
Section 1
``` Duplicate headings get suffixed automatically: `intro`, `intro-1`, `intro-2`. ### Copy-Code Plugin Injects a copy-to-clipboard button into every `` code block.
```typescript
import { copyCodePlugin } from '@lpm.dev/neo.markdown/plugins/copy-code'
const html = parse(markdown, {
plugins: [
copyCodePlugin({
buttonText: 'Copy',
buttonClass: 'copy-code-button',
wrapperClass: 'code-block',
})
]
})
```
**Output:**
```html
...
```
## Writing Custom Plugins
A plugin is a function that receives a `PluginBuilder`:
```typescript
import type { MarkdownPlugin } from '@lpm.dev/neo.markdown'
const myPlugin: MarkdownPlugin = (builder) => {
// Override how code blocks render
builder.setRenderer('code', (token) => {
return `${token.text}\n`
})
}
```
### PluginBuilder API
| Method | Description |
|--------|-------------|
| `addBlockRule(rule)` | Add a custom block-level tokenization rule |
| `addInlineRule(rule)` | Add a custom inline tokenization rule |
| `setRenderer(method, fn)` | Override a renderer method (e.g. `'code'`, `'heading'`) |
| `addTokenTransform(fn)` | Transform tokens after tokenization, before rendering |
| `addHtmlTransform(fn)` | Transform the final HTML string |
| `renderInline(tokens)` | Utility: render inline tokens to HTML |
| `renderBlock(tokens)` | Utility: render block tokens to HTML |
| `options` | Read-only access to parser options |
### Custom Block Rule
```typescript
const notePlugin: MarkdownPlugin = (builder) => {
builder.addBlockRule({
name: 'note',
priority: 'before:paragraph',
tokenize(src, options) {
const match = /^:::note\n([\s\S]*?)\n:::(?:\n|$)/.exec(src)
if (!match) return null
return {
token: { type: 'html', raw: match[0], text: `${match[1]}` },
raw: match[0],
}
},
})
}
```
Rules support numeric priority (higher = tried first) or positional constraints: `'before:paragraph'`, `'after:code'`.
### Custom Inline Rule
```typescript
const highlightPlugin: MarkdownPlugin = (builder) => {
builder.addInlineRule({
name: 'highlight',
triggerChars: [61], // '=' char code
tokenize(src) {
const match = /^==(.*?)==/.exec(src)
if (!match) return null
return {
token: { type: 'html', raw: match[0], text: `${match[1]}` },
raw: match[0],
}
},
})
}
```
### Token Transform
```typescript
const removeHr: MarkdownPlugin = (builder) => {
builder.addTokenTransform((tokens) =>
tokens.filter((t) => t.type !== 'hr')
)
}
```
### HTML Transform
```typescript
const addWrapper: MarkdownPlugin = (builder) => {
builder.addHtmlTransform((html) =>
`${html} `
)
}
```
## Supported Syntax
### Block elements
```markdown
# Heading 1
## Heading 2
Paragraph text with **bold**, *italic*, and `code`.
> Blockquote
- Unordered list
- Item two
1. Ordered list
2. Item two
Code block (indented)
```code block (fenced)```
---
| Table | Header |
|-------|--------|
| Cell | Cell |
- [x] Task list item
- [ ] Unchecked item
```
### Inline elements
```markdown
**bold** or __bold__
*italic* or _italic_
~~strikethrough~~
`inline code`
[link text](https://example.com)
```
## Presets
```typescript
// CommonMark preset (strict spec compliance)
import { parse } from '@lpm.dev/neo.markdown/commonmark'
// GFM preset (GitHub Flavored Markdown — tables, task lists, strikethrough)
import { parse } from '@lpm.dev/neo.markdown/gfm'
```
## Sub-path Imports
| Import | Description |
|--------|-------------|
| `@lpm.dev/neo.markdown` | Main entry — `parse()` and `createParser()` |
| `@lpm.dev/neo.markdown/core` | Core classes (Tokenizer, InlineTokenizer, HtmlRenderer, PluginBuilderImpl) |
| `@lpm.dev/neo.markdown/blocks` | Individual block rules for tree-shaking (`heading`, `paragraph`, `code`, `list`, etc.) |
| `@lpm.dev/neo.markdown/inline` | Inline token types and InlineTokenizer |
| `@lpm.dev/neo.markdown/commonmark` | CommonMark preset |
| `@lpm.dev/neo.markdown/gfm` | GFM preset |
| `@lpm.dev/neo.markdown/plugins/highlight` | Syntax highlighting plugin |
| `@lpm.dev/neo.markdown/plugins/embeds` | Embed plugin (YouTube, Vimeo, Twitter, CodeSandbox, CodePen, Gist, Loom) |
| `@lpm.dev/neo.markdown/plugins/embeds/react` | React embed components with IntersectionObserver |
| `@lpm.dev/neo.markdown/plugins/toc` | Table of contents plugin |
| `@lpm.dev/neo.markdown/plugins/copy-code` | Copy-to-clipboard button plugin |
## Migration from marked
```typescript
// Before (marked)
import { marked } from 'marked'
const html = marked('# Hello')
// After (neo.markdown)
import { parse } from '@lpm.dev/neo.markdown'
const html = parse('# Hello')
```
## Migration from markdown-it
```typescript
// Before (markdown-it)
import MarkdownIt from 'markdown-it'
const md = new MarkdownIt()
const html = md.render('# Hello')
// After (neo.markdown)
import { createParser } from '@lpm.dev/neo.markdown'
const parser = createParser()
const html = parser.parse('# Hello')
```
## Migration from rehype-pretty-code + rehype-slug
If you're using the remark/rehype stack for syntax highlighting, heading anchors, and embeds, neo.markdown replaces the entire chain:
```typescript
// Before — remark/rehype stack
import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypePrettyCode from 'rehype-pretty-code' // Shiki ~1MB
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import rehypeStringify from 'rehype-stringify'
const result = await unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkRehype)
.use(rehypePrettyCode, { theme: 'github-dark' })
.use(rehypeSlug)
.use(rehypeAutolinkHeadings)
.use(rehypeStringify)
.process(markdown)
```
```typescript
// After — neo.markdown (one import, one parser, done)
import { createParser } from '@lpm.dev/neo.markdown'
import { highlightPlugin } from '@lpm.dev/neo.markdown/plugins/highlight'
import { tocPlugin } from '@lpm.dev/neo.markdown/plugins/toc'
import { tokenize, renderToHTML, getThemeStylesheet } from '@lpm.dev/neo.highlight'
import { javascript, typescript } from '@lpm.dev/neo.highlight/grammars'
import { githubDark } from '@lpm.dev/neo.highlight/themes/github-dark'
const parser = createParser({
gfm: true,
plugins: [
highlightPlugin({
grammars: [javascript, typescript],
tokenize,
renderToHTML,
getThemeStylesheet,
theme: githubDark,
}),
tocPlugin({ maxDepth: 3 }),
]
})
const html = parser.parse(markdown)
```
**What replaces what:**
| rehype plugin | neo.markdown equivalent |
|--------------|------------------------|
| `rehype-pretty-code` (Shiki) | `highlightPlugin()` with `@lpm.dev/neo.highlight` |
| `rehype-slug` | `tocPlugin({ anchorLinks: false })` |
| `rehype-autolink-headings` | `tocPlugin({ anchorLinks: true })` |
| Custom embed components | `embedPlugin({ youtube: true, twitter: true })` |
| `rehype-raw` + `rehype-sanitize` | `allowHtml: true, sanitize: true` (built-in server-side sanitizer) |
## License
MIT