npm package: @paroicms/markdown-to-tiptap-json
Description: Convert Markdown to Tiptap JSON
Author: Paroi Team
Latest version: 0.2.11

# @paroicms/markdown-to-tiptap-json

A lightweight JavaScript/TypeScript library for converting Markdown to Tiptap JSON format **without loading the Tiptap editor**. This package uses `markdown-it` for parsing, making it efficient and suitable for server-side operations where you need to convert Markdown to Tiptap JSON without the overhead of loading the full editor.

## Installation

```bash
npm install @paroicms/markdown-to-tiptap-json
```

## Usage

```typescript
import { convertMarkdownToTiptap } from "@paroicms/markdown-to-tiptap-json";

const markdown = `# Hello World

This is a paragraph with **bold** and *italic* text.

- List item 1
- List item 2
- List item 3`;

const { result, issues } = convertMarkdownToTiptap(markdown);

console.log(JSON.stringify(result, null, 2));
// {
//   "type": "doc",
//   "content": [
//     {
//       "type": "heading",
//       "attrs": { "level": 1 },
//       "content": [{ "type": "text", "text": "Hello World" }]
//     },
//     {
//       "type": "paragraph",
//       "content": [
//         { "type": "text", "text": "This is a paragraph with " },
//         { "type": "text", "text": "bold", "marks": [{ "type": "bold" }] },
//         { "type": "text", "text": " and " },
//         { "type": "text", "text": "italic", "marks": [{ "type": "italic" }] },
//         { "type": "text", "text": " text." }
//       ]
//     },
//     {
//       "type": "bulletList",
//       "content": [
//         { "type": "listItem", "content": [...] },
//         { "type": "listItem", "content": [...] },
//         { "type": "listItem", "content": [...] }
//       ]
//     }
//   ]
// }

// Check for any issues during conversion
if (issues) {
  console.warn("Conversion issues:", issues);
}
```

## API

### `convertMarkdownToTiptap(markdown: string): ConversionResult`

Converts a Markdown string to Tiptap JSON format.

**Parameters:**

- `markdown`: The Markdown string to convert

**Returns:** `ConversionResult` object containing:

- `result`: The Tiptap JSON document (type `TiptapJsonValue`)
- `issues` (optional): Array of warning messages for skipped or problematic content

## Supported Markdown Features

### Block Elements

- **Headings**: `# H1` through `###### H6`
- **Paragraphs**: Regular text blocks
- **Blockquotes**: `> Quote text`
- **Code blocks**: Fenced (` ``` `) and indented
- **Horizontal rules**: `---`, `***`, or `___`
- **Lists**: Bullet (`-`, `*`, `+`) and ordered (`1.`, `2.`, etc.)
- **Nested lists**: Multi-level list structures
- **Tables**: GitHub-flavored markdown tables

### Inline Elements

- **Bold**: `**bold**` or `__bold__`
- **Italic**: `*italic*` or `_italic_`
- **Strikethrough**: `~~strikethrough~~`
- **Inline code**: `` `code` ``
- **Links**: `[text](url)`
- **Images**: `![alt](url)`
- **Hard breaks**: Two spaces at end of line

### Special Handling

- **HTML blocks and inline HTML**: Skipped with warnings in `issues` array
- **Empty documents**: Returns empty doc with no issues
- **Malformed markdown**: Returns minimal valid doc with error in `issues`

## License

MIT

## Related Packages

This package can be used as a standalone library. It's also part of the ParoiCMS ecosystem. For more information, visit the [ParoiCMS repository](https://gitlab.com/paroi/opensource/paroicms).