Milkdown

https://milkdown.dev/docs/
Admin
Milkdown is a headless rich text editor framework built on top of ProseMirror and remark, providing...
Tokens:92,693
Snippets:847
Trust Score:8.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Highlight Plugin

Source: https://milkdown.dev/docs/guide/code-highlighting

Install the highlight plugin using npm.

```bash
npm install @milkdown/plugin-highlight
```

--------------------------------

### Plugin Example

Source: https://milkdown.dev/docs/api/ctx

Demonstrates the structure of a Milkdown plugin, including setup, run, and optional cleanup phases. Plugins can be synchronous or asynchronous.

```typescript
// A full plugin example
const plugin1 = (ctx: Ctx) => {
  // setup
  return async () => {
    // run
    return async () => {
      // cleanup
    }
  }
}

// A plugin doesn't need to return a cleanup function
const plugin2 = (ctx: Ctx) => {
  // setup
  return async () => {
    // run
  }
}

// A plugin doesn't need to be async
const plugin3 = (ctx: Ctx) => {
  // setup
  return () => {
    // run
  }
}
```

--------------------------------

### Example Plugin Lifecycle

Source: https://milkdown.dev/docs/guide/architecture-overview

Shows the typical lifecycle of a Milkdown plugin, including setup, initialization, runtime, and cleanup phases, demonstrating state and dependency management.

```typescript
const examplePlugin: MilkdownPlugin = (ctx) => {
  // 1. Setup Phase
  ctx.inject(mySlice, defaultValue)
  ctx.record(myTimer)

  return async () => {
    // 2. Initialization Phase
    await ctx.wait(RequiredTimer)

    // 3. Runtime Phase
    const value = ctx.get(mySlice)
    ctx.set(mySlice, newValue)

    // 4. Cleanup Phase
    return () => {
      ctx.remove(mySlice)
    }
  }
}
```

--------------------------------

### Install Core Milkdown and Theme Packages

Source: https://milkdown.dev/docs/recipes/vue

Install the core Milkdown packages along with a theme for basic editor usage.

```bash
npm install @milkdown/vue @milkdown/kit @milkdown/theme-nord
```

--------------------------------

### Install Crepe and React Packages

Source: https://milkdown.dev/docs/recipes/react

Install the necessary packages for using Crepe, the React integration, and Milkdown kits.

```bash
npm install @milkdown/crepe @milkdown/react @milkdown/kit
```

--------------------------------

### Install @milkdown/kit

Source: https://milkdown.dev/docs/guide/getting-started

Install the core Milkdown package for building a custom editor from scratch.

```bash
npm install @milkdown/kit
```

--------------------------------

### Install Crepe and Vue Packages

Source: https://milkdown.dev/docs/recipes/vue

Install the necessary Milkdown packages for Crepe and Vue integration.

```bash
npm install @milkdown/crepe @milkdown/vue @milkdown/kit
```

--------------------------------

### Complete Editor Example with Shiki

Source: https://milkdown.dev/docs/guide/code-highlighting

A full example demonstrating the creation of a Milkdown editor with Shiki syntax highlighting configured. This includes setting up the parser and applying the highlight plugin.

```typescript
import { Editor } from '@milkdown/core'
import { commonmark } from '@milkdown/preset-commonmark'
import { highlight, highlightPluginConfig } from '@milkdown/plugin-highlight'
import { createParser } from '@milkdown/plugin-highlight/shiki'

async function createHighlightedEditor() {
  const parser = await createParser({
    theme: 'github-light',
    langs: ['javascript', 'typescript', 'python', 'html', 'css', 'json'],
  })

  const editor = Editor.make()
    .config((ctx) => {
      ctx.set(highlightPluginConfig.key, { parser })
    })
    .use(commonmark)
    .use(highlight)

  await editor.create()
  return editor
}
```

--------------------------------

### Basic Milkdown Editor Implementation in React

Source: https://milkdown.dev/docs/recipes/react

A minimal example demonstrating the core Milkdown editor setup in a React component.

```tsx
import { Editor, rootCtx } from '@milkdown/kit/core'
import { commonmark } from '@milkdown/kit/preset/commonmark'
import { Milkdown, MilkdownProvider, useEditor } from '@milkdown/react'
import { nord } from '@milkdown/theme-nord'

const MilkdownEditor: React.FC = () => {
  const { get } = useEditor((root) =>
    Editor.make()
      .config(nord)
      .config((ctx) => {
        ctx.set(rootCtx, root)
      })
      .use(commonmark)
  )

  return <Milkdown />
}

export const MilkdownEditorWrapper: React.FC = () => {
  return (
    <MilkdownProvider>
      <MilkdownEditor />
    </MilkdownProvider>
  )
}
```

--------------------------------

### Install Milkdown React and Kit Packages

Source: https://milkdown.dev/docs/recipes/react

Install the core Milkdown React integration and kit packages for basic usage.

```bash
npm install @milkdown/react @milkdown/kit
```

--------------------------------

### Install @milkdown/crepe

Source: https://milkdown.dev/docs/guide/getting-started

Install the ready-to-use Milkdown editor package using npm.

```bash
npm install @milkdown/crepe
```

--------------------------------

### Command Creation and Usage

Source: https://milkdown.dev/docs/api/utils

Code examples for creating commands and calling them, including async command creation.

```javascript
import { setBlockType } from '@milkdown/prose/commands'

const commandPlugin = $command('SetAsHeading', (ctx) => {
  return (level = 1) => setBlockType(headingSchema.type(), { level });
});
```

```javascript
import { callCommand } from '@milkdown/utils';
const editor = Editor.make().use(/* some plugins */).use(commandPlugin).create();

editor.action(callCommand(commandPlugin.key, 3));
```

```javascript
const commandPlugin = $commandASync('LoadRemoteDoc', (ctx) => {
  return async (url = 'my-remote-api') => {
    const doc = await LoadRemoteDoc(url);
    return addDoc(doc);
  }
});
```

--------------------------------

### Initialize Crepe Editor

Source: https://milkdown.dev/docs/guide/using-crepe

Basic setup for creating and destroying a Crepe editor instance.

```javascript
import { Crepe } from '@milkdown/crepe'
import '@milkdown/crepe/theme/common/style.css'
import '@milkdown/crepe/theme/frame.css'

// Choose your preferred theme

// Create editor instance
const crepe = new Crepe({
  root: document.getElementById('app'),
  defaultValue: '# Hello, Crepe!\n\nStart writing your markdown...',
})

// Initialize the editor
await crepe.create()

// Clean up when done
crepe.destroy()
```

--------------------------------

### Install Crepe Editor

Source: https://milkdown.dev/docs/guide/using-crepe

Commands to install the Crepe package using common package managers.

```bash
# Using npm
npm install @milkdown/crepe
  

# Using yarn
yarn add @milkdown/crepe
  

# Using pnpm
pnpm add @milkdown/crepe
```

--------------------------------

### Shiki Highlighter Setup

Source: https://milkdown.dev/docs/api/plugin-highlight

Import and create a Shiki highlighter instance. Ensure themes and languages are specified.

```typescript
// For shiki
import { getSingletonHighlighter } from 'shiki'
import { createParser } from '@milkdown/plugin-highlight/shiki'
const highlighter = await getSingletonHighlighter({
  themes: ['github-light'],
  langs: ['javascript', 'typescript', 'python'],
})
const parser = createParser(highlighter)
```

--------------------------------

### Refractor Highlighter Setup

Source: https://milkdown.dev/docs/api/plugin-highlight

Import and create a Refractor highlighter instance using Prism.js.

```typescript
// For refractor
import { refractor } from 'refractor/all'
import { createParser } from '@milkdown/plugin-highlight/refractor'
const parser = createParser(refractor)
```

--------------------------------

### Highlight Plugin Setup

Source: https://milkdown.dev/docs/api/plugin-highlight

Demonstrates how to set up the highlight plugin with different parser configurations for Shiki, Lowlight, Refractor, and Sugar High, and then integrate it into a Milkdown editor.

```APIDOC
## Highlight Plugin Setup

### Description
This section shows how to configure and use the Milkdown highlight plugin with various syntax highlighting libraries.

### Methods
- `highlight`: The Milkdown highlight plugin.
- `highlightPluginConfig`: Configuration object for the highlight plugin.

### Usage Examples

#### Using Shiki
```typescript
import { getSingletonHighlighter } from 'shiki'
import { createParser } from '@milkdown/plugin-highlight/shiki'

const highlighter = await getSingletonHighlighter({
  themes: ['github-light'],
  langs: ['javascript', 'typescript', 'python'],
})
const parser = createParser(highlighter)
```

#### Using Lowlight
```typescript
import 'highlight.js/styles/default.css'
import { common, createLowlight } from 'lowlight'
import { createParser } from '@milkdown/plugin-highlight/lowlight'

const lowlight = createLowlight(common)
const parser = createParser(lowlight)
```

#### Using Refractor
```typescript
import { refractor } from 'refractor/all'
import { createParser } from '@milkdown/plugin-highlight/refractor'

const parser = createParser(refractor)
```

#### Using Sugar High
```typescript
import { createParser } from '@milkdown/plugin-highlight/sugar-high'

const parser = createParser()
```

#### Editor Setup
```typescript
import { Editor } from '@milkdown/core'
import { highlight, highlightPluginConfig } from '@milkdown/plugin-highlight'

// Assuming 'parser' is one of the parser instances created above

Editor.make()
  .config((ctx) => {
    ctx.set(highlightPluginConfig.key, { parser })
  })
  .use(highlight)
  .create()
```

### Parameters

#### highlightPluginConfig
- **parser** (object) - Required - The parser instance for the chosen highlighting library.
```

--------------------------------

### Lowlight Highlighter Setup

Source: https://milkdown.dev/docs/api/plugin-highlight

Import and create a Lowlight highlighter instance. Requires CSS import for styles.

```typescript
// For lowlight
import 'highlight.js/styles/default.css'
import { common, createLowlight } from 'lowlight'
import { createParser } from '@milkdown/plugin-highlight/lowlight'
const lowlight = createLowlight(common)
const parser = createParser(lowlight)
```

--------------------------------

### Create Tooltip View

Source: https://milkdown.dev/docs/api/plugin-tooltip

Example of creating a tooltip plugin view using TooltipProvider.

```typescript
import { TooltipProvider } from '@milkdown/kit/plugin/tooltip';

function tooltipPluginView(view) {
  const content = document.createElement('div');
  const provider = new TooltipProvider({
    content: this.content,
  });

  return {
    update: (updatedView, prevState) => {
      provider.update(updatedView, prevState);
    },
  };
}
```

--------------------------------

### Icon Configuration Example

Source: https://milkdown.dev/docs/api/crepe

Shows how to customize feature icons by providing SVG strings in the featureConfigs.

```typescript
const config: CrepeConfig = {
  featureConfigs: {
    [Crepe.Feature.Toolbar]: {
      boldIcon: '<svg>...</svg>',
      italicIcon: '<svg>...</svg>',
    },
  },
}
```

--------------------------------

### Install Collaborative Editing Plugins

Source: https://milkdown.dev/docs/guide/collaborative-editing

Install the necessary packages for collaborative editing, including the Milkdown collab plugin and Y.js.

```bash
npm install @milkdown/plugin-collab
  
npm install yjs y-protocols y-prosemirror
```

--------------------------------

### Install Milkdown Dependencies with npm

Source: https://milkdown.dev/docs/recipes/angular

Install the necessary Milkdown packages for Angular integration using npm.

```bash
npm install @milkdown/kit
npm install @milkdown/theme-nord
```

--------------------------------

### Install Milkdown Dependencies for NuxtJS

Source: https://milkdown.dev/docs/recipes/nuxtjs

Install the necessary Milkdown packages, including core, Vue integration, and a theme, using npm.

```bash
npm install @milkdown/vue
npm install @milkdown/kit
npm install @milkdown/theme-nord
```

--------------------------------

### Collab Plugin Setup and Usage

Source: https://milkdown.dev/docs/api/plugin-collab

Demonstrates how to set up and use the collab plugin for collaborative editing with Yjs.

```APIDOC
## Collab Plugin Setup and Usage

### Description
This section shows how to integrate the collab plugin into your Milkdown editor and configure it for collaborative editing using Yjs.

### Method
```typescript
import { collab, collabServiceCtx } from '@milkdown/plugin-collab'
import { Editor } from '@milkdown/core'
import { Doc } from 'yjs'
import { WebsocketProvider } from 'y-websocket'

async function setup() {
  const editor = await Editor.make().use(collab).create()

  const doc = new Doc()
  const wsProvider = new WebsocketProvider('<YOUR_WS_HOST>', 'milkdown', doc)

  editor.action((ctx) => {
    const collabService = ctx.get(collabServiceCtx)

    collabService
      // bind doc and awareness
      .bindDoc(doc)
      .setAwareness(wsProvider.awareness)
      // connect yjs with milkdown
      .connect()
  })
}
```

### Parameters
N/A (This is a setup example)

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Create Custom Command with Shortcut

Source: https://milkdown.dev/docs/guide/keyboard-shortcuts

Example of creating a custom command and then defining a keymap for it, allowing multiple shortcuts.

```typescript
import { $command, $useKeymap } from '@milkdown/utils'
import { commandsCtx } from '@milkdown/core'

// Create a custom command
const customCommand = $command('CustomCommand', (ctx) => () => {
  return (state, dispatch) => {
    // Command implementation
    return true
  }
})

// Create a keymap
const customKeymap = $useKeymap('customKeymap', {
  CustomCommand: {
    shortcuts: ['F1', 'Mod-F1'], // Multiple shortcuts
    command: (ctx) => {
      const commands = ctx.get(commandsCtx)
      return () => commands.call(customCommand.key)
    },
  },
})

// Usage
Editor.make().use(customCommand).use(customKeymap)
```

--------------------------------

### Advanced Crepe Editor Setup

Source: https://milkdown.dev/docs/guide/getting-started

Initialize a Milkdown editor with the Crepe package, including theme and default content. Demonstrates editor creation and destruction.

```typescript
import { Crepe } from '@milkdown/crepe'
import '@milkdown/crepe/theme/common/style.css'
/**
 * Available themes:
 * frame, crepe, nord
 * frame-dark, crepe-dark, nord-dark
 */
import '@milkdown/crepe/theme/frame.css'

const crepe = new Crepe({
  root: '#app',
  defaultValue: 'Hello, Milkdown!',
})

crepe.create().then(() => {
  console.log('Editor created')
})

// To destroy the editor
crepe.destroy()
```

--------------------------------

### Basic Crepe Editor Setup

Source: https://milkdown.dev/docs/guide/getting-started

Initialize a basic Milkdown editor using the Crepe package. Ensure to import the necessary CSS for theming.

```typescript
import { Crepe } from '@milkdown/crepe'
import '@milkdown/crepe/theme/common/style.css'
import '@milkdown/crepe/theme/frame.css'
  

const crepe = new Crepe({
root: '#app',
defaultValue: 'Hello, Milkdown!',
})
  

crepe.create()
```

--------------------------------

### Remark Plugin Setup

Source: https://milkdown.dev/docs/plugin/example-iframe-plugin

Import and configure the remark-directive plugin for custom markdown syntax support.

```typescript
import directive from 'remark-directive'
import { $remark } from '@milkdown/kit/utils'

const remarkDirective = $remark('remarkDirective', () => directive)
```

--------------------------------

### Latex Feature Configuration Example

Source: https://milkdown.dev/docs/api/crepe

Shows how to enable the Latex feature and pass KaTeX options via featureConfigs. The katexOptions.throwOnError is set to false and displayMode to true.

```typescript
interface LatexFeatureConfig {
  katexOptions?: KatexOptions // KaTeX rendering options
  inlineEditConfirm?: string // Custom confirm icon for inline math
}

// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.Latex]: true,
  },
  featureConfigs: {
    [Crepe.Feature.Latex]: {
      katexOptions: {
        throwOnError: false,
        displayMode: true,
      },
    },
  },
}
```

--------------------------------

### splitListItemCommand example

Source: https://milkdown.dev/docs/api/preset-commonmark

Shows the before and after states of splitting a list item with the splitListItemCommand. The cursor is on the second item, and after splitting a new empty item is created after it.

```markdown
* List item 1
* List item 2 <- cursor here
```

```markdown
* List item 1
* List item 2
* <- cursor here
```

--------------------------------

### BlockEdit Feature Configuration and Example

Source: https://milkdown.dev/docs/api/crepe

The BlockEditFeatureConfig interface defines the configuration options for the BlockEdit feature, including block handle icons, block handle positioning, and menu group customization. The example shows how to enable the feature and customize the menu by setting groups or items to null to hide them.

```typescript
interface BlockEditFeatureConfig {
  // Block handle icons
  handleAddIcon?: string
  handleDragIcon?: string

  // Block handle configuration
  blockHandle?: {
    // A function to determine whether the block handle should be shown.
    shouldShow?: (view: EditorView) => boolean
    // A function to configure the offset of the block handle.
    getOffset?: (deriveContext: DeriveContext) => {
      mainAxis?: number
      crossAxis?: number
    }
    // A function to get the position of the block handle.
    getPosition?: (deriveContext: DeriveContext) => DOMRect
    // A function to get the placement of the block handle.
    getPlacement?: (
      deriveContext: DeriveContext
    ) => 'top' | 'bottom' | 'left' | 'right'
    // An array of floating-ui middlewares.
    middleware?: unknown[]
    // Additional options for floating-ui.
    floatingUIOptions?: unknown
    // The root element for the block handle.
    root?: HTMLElement
  }

  // Menu configuration
  buildMenu?: (builder: GroupBuilder<SlashMenuItem>) => void

  // Text group configuration
  textGroup?: {
    label?: string
    text?: {
      label?: string
      icon?: string
    } | null
    h1?: {
      label?: string
      icon?: string
    } | null
    h2?: {
      label?: string
      icon?: string
    } | null
    h3?: {
      label?: string
      icon?: string
    } | null
    h4?: {
      label?: string
      icon?: string
    } | null
    h5?: {
      label?: string
      icon?: string
    } | null
    h6?: {
      label?: string
      icon?: string
    } | null
    quote?: {
      label?: string
      icon?: string
    } | null
    divider?: {
      label?: string
      icon?: string
    } | null
  } | null

  // List group configuration
  listGroup?: {
    label?: string
    bulletList?: {
      label?: string
      icon?: string
    } | null
    orderedList?: {
      label?: string
      icon?: string
    } | null
    taskList?: {
      label?: string
      icon?: string
    } | null
  } | null

  // Advanced group configuration
  advancedGroup?: {
    label?: string
    image?: {
      label?: string
      icon?: string
    } | null
    codeBlock?: {
      label?: string
      icon?: string
    } | null
    table?: {
      label?: string
      icon?: string
    } | null
    math?: {
      label?: string
      icon?: string
    } | null
  } | null
}
```

```typescript
// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.BlockEdit]: true,
  },
  featureConfigs: {
    [Crepe.Feature.BlockEdit]: {
      handleAddIcon: customAddIcon,
      handleDragIcon: customDragIcon,
      blockHandle: {
        getPlacement: () => 'left-start',
      },
      textGroup: {
        label: 'Text Blocks',
        text: {
          label: 'Normal Text',
          icon: customTextIcon,
        },
        h1: {
          label: 'Heading 1',
          icon: customH1Icon,
        },
        h2: null,
        h3: null,
        h4: null,
        h5: null,
        h6: null,
      },
      listGroup: {
        label: 'Lists',
        bulletList: {
          label: 'Bullet List',
          icon: customBulletIcon,
        },
        orderedList: null,
        taskList: null,
      },
      advancedGroup: {
        label: 'Advanced',
        image: {
          label: 'Image',
          icon: customImageIcon,
        },
        codeBlock: null,
        table: null,
        math: null,
      },
      buildMenu: (builder) => {
        // Custom menu building logic
      },
    },
  },
}
```

--------------------------------

### useCrepe hook example

Source: https://milkdown.dev/docs/api/crepe

Shows how to access the CrepeBuilder instance within a Milkdown plugin using the useCrepe hook. The example sets the editor to readonly mode.

```typescript
import { crepeCtx } from '@milkdown/crepe'
const plugin = (ctx: Ctx) => {
  return () => {
    const crepe = useCrepe(ctx)
    crepe.setReadonly(true)
  }
}
```

--------------------------------

### OpenAI Provider Configuration

Source: https://milkdown.dev/docs/api/crepe

Example of creating an OpenAI provider with custom body fields and message building logic.

```typescript
// OpenAI: any chat-completions body fields (temperature, top_p, etc.)
// can go in `body`. `buildMessages` lets you fully customize the
// messages array — the defaults are passed in so you can wrap them.
// `defaults.systemPrompt` is `string | null`: `null` means the user
// asked to omit the system message, so don't coerce it to ''.
createOpenAIProvider({
  apiKey,
  model: 'gpt-4o-mini',
  body: { temperature: 0.2 },
  buildMessages: (context, defaults) => [
    ...(defaults.systemPrompt !== null
      ? [{ role: 'system' as const, content: defaults.systemPrompt }]
      : []),
    { role: 'user', content: defaults.userMessage },
  ],
})
```

--------------------------------

### Initialize Crepe editor with features and event handling

Source: https://milkdown.dev/docs/api/crepe

Creates a Crepe editor instance with a root selector, enables Toolbar and Latex features, configures the Placeholder feature, sets a default value, and demonstrates getting markdown, setting readonly mode, and listening to markdownUpdated events.

```javascript
import { Crepe } from '@milkdown/crepe'

const editor = new Crepe({
  root: '#editor', // DOM element or selector
  features: {
    [Crepe.Feature.Toolbar]: true,
    [Crepe.Feature.Latex]: true,
  },
  featureConfigs: {
    [Crepe.Feature.Placeholder]: {
      text: 'Start writing...',
      mode: 'block',
    },
  },
  defaultValue: '# Hello World',
})

// Get markdown content
const markdown = editor.getMarkdown()

// Set readonly mode
editor.setReadonly(true)

// Listen to editor events
editor.on((listener) => {
  listener.markdownUpdated((ctx, markdown, prevMarkdown) => {
    // Handle updates
  })
})
```

--------------------------------

### sinkListItemCommand example

Source: https://milkdown.dev/docs/api/preset-commonmark

Shows the before and after states of sinking a list item with the sinkListItemCommand. The cursor is on the second item, and after sinking it becomes a child of the first item.

```markdown
* List item 1
* List item 2 <- cursor here
```

```markdown
* List item 1
  * List item 2
```

--------------------------------

### liftListItemCommand example

Source: https://milkdown.dev/docs/api/preset-commonmark

Shows the before and after states of lifting a list item with the liftListItemCommand. The cursor is on the nested item, and after lifting it becomes a sibling of the first item.

```markdown
* List item 1
  * List item 2 <- cursor here
```

```markdown
* List item 1
* List item 2
```

--------------------------------

### @milkdown/plugin-listener Usage

Source: https://milkdown.dev/docs/api/plugin-listener

Example of how to import and use the listener plugin in a Milkdown editor configuration.

```APIDOC
## Usage
```typescript
import { Editor } from '@milkdown/kit/core'
import { listener, listenerCtx } from '@milkdown/kit/plugin/listener'
import { commonmark } from '@milkdown/kit/preset/commonmark'
import { nord } from '@milkdown/theme-nord'
  

Editor.make()
.config((ctx) => {
const listener = ctx.get(listenerCtx)
  
listener.markdownUpdated((ctx, markdown, prevMarkdown) => {
if (markdown !== prevMarkdown) {
YourMarkdownUpdater(markdown)
}
})
})
.use(listener)
// use other plugins
.create()
```
```

--------------------------------

### Sugar High Highlighter Setup

Source: https://milkdown.dev/docs/api/plugin-highlight

Create a Sugar High parser instance. No external dependencies are required for this parser.

```typescript
// For sugar high
import { createParser } from '@milkdown/plugin-highlight/sugar-high'
const parser = createParser()
```

--------------------------------

### useCrepeFeatures hook example

Source: https://milkdown.dev/docs/api/crepe

Shows how to check enabled feature flags using the useCrepeFeatures hook. The example checks if the CodeMirror feature is enabled and performs an action accordingly.

```typescript
import { useCrepeFeatures } from '@milkdown/crepe'
const plugin = (ctx: Ctx) => {
  const features = useCrepeFeatures(ctx)
  if (features.get().includes(CrepeFeature.CodeMirror)) {
    // Do something with CodeMirror
  }
}
```

--------------------------------

### CrepeBuilder.editor

Source: https://milkdown.dev/docs/api/crepe

Gets the Milkdown editor instance.

```APIDOC
## Property: `editor: Editor`

### Description
Gets the Milkdown editor instance.

### Returns
- **Editor** - The Milkdown editor instance.
```

--------------------------------

### CrepeBuilder.getMarkdown()

Source: https://milkdown.dev/docs/api/crepe

Gets the markdown content of the editor.

```APIDOC
## Method: `getMarkdown() → string`

### Description
Gets the markdown content of the editor.

### Returns
- **string** - The markdown content.
```

--------------------------------

### Accessing Editor Instance with useInstance Hook

Source: https://milkdown.dev/docs/recipes/react

Demonstrates how to use the `useInstance` hook within a `MilkdownProvider` to get the editor instance for advanced operations.

```tsx
import { useInstance } from '@milkdown/react'
import { getMarkdown } from '@milkdown/utils'

// ❌ This won't work - ParentComponent is outside MilkdownProvider
const ParentComponent: React.FC = () => {
  const [isLoading, getInstance] = useInstance() // This will be [true, () => undefined]
  return <MilkdownEditorWrapper />
}

// ✅ This is the correct way - EditorControls is inside MilkdownProvider
const EditorControls: React.FC = () => {
  const [isLoading, getInstance] = useInstance()

  const handleSave = () => {
    if (isLoading) return

    const editor = getInstance()
    if (!editor) return

    const content = editor.action(getMarkdown())
    // Do something with the content
  }

  return (
    <button onClick={handleSave} disabled={isLoading}>
      Save
    </button>
  )
}

// ✅ Proper component structure
const EditorWithControls: React.FC = () => {
  return (
    <MilkdownProvider>
      <MilkdownEditorWrapper />
      <EditorControls />
    </MilkdownProvider>
  )
}
```

--------------------------------

### Milkdown Editor Setup with Highlight Plugin

Source: https://milkdown.dev/docs/api/plugin-highlight

Configure the Milkdown editor to use the highlight plugin. Set the parser in the plugin configuration.

```typescript
// Setup
import { highlight, highlightPluginConfig } from '@milkdown/plugin-highlight'
Editor.make()
.config((ctx) => {
ctx.set(highlightPluginConfig.key, { parser })
})
.use(highlight)
.create()
```

--------------------------------

### Insert Initial Content

Source: https://milkdown.dev/docs/guide/macros

Add initial content to the editor upon mounting using the `insert` macro within the listener plugin. This sets up the starting text for the user.

```typescript
import { insert } from '@milkdown/kit/utils'
import { listenerCtx } from '@milkdown/kit/plugin/listener'

editor.config((ctx) => {
  ctx.get(listenerCtx).mounted(insert('# Welcome\nStart editing...'))
})
```

--------------------------------

### LinkTooltip Feature Configuration

Source: https://milkdown.dev/docs/api/crepe

Shows the LinkTooltipFeatureConfig interface and an example configuration for the LinkTooltip feature.

```typescript
interface LinkTooltipFeatureConfig {
  linkIcon?: string // Custom link icon
  editButton?: string // Custom edit button icon
  removeButton?: string // Custom remove button icon
  confirmButton?: string // Custom confirm button icon
  inputPlaceholder?: string // Placeholder text for link input
  onCopyLink?: (link: string) => void // Callback when link is copied
}
```

```typescript
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.LinkTooltip]: true,
  },
  featureConfigs: {
    [Crepe.Feature.LinkTooltip]: {
      inputPlaceholder: 'Enter URL...',
      onCopyLink: () => console.log('Link copied'),
    },
  },
}
```

--------------------------------

### ListItem Feature Configuration

Source: https://milkdown.dev/docs/api/crepe

Shows the ListItemFeatureConfig interface and an example configuration for the ListItem feature.

```typescript
interface ListItemFeatureConfig {
  bulletIcon?: string // Custom bullet list icon
  checkBoxCheckedIcon?: string // Custom checked checkbox icon
  checkBoxUncheckedIcon?: string // Custom unchecked checkbox icon
}
```

```typescript
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.ListItem]: true,
  },
  featureConfigs: {
    [Crepe.Feature.ListItem]: {
      bulletIcon: customBulletIcon,
      checkBoxCheckedIcon: customCheckedIcon,
      checkBoxUncheckedIcon: customUncheckedIcon,
    },
  },
}
```

--------------------------------

### CrepeBuilder.readonly

Source: https://milkdown.dev/docs/api/crepe

Gets the readonly state of the editor.

```APIDOC
## Property: `readonly: boolean`

### Description
Gets the readonly state of the editor.

### Returns
- **boolean** - The readonly state.
```

--------------------------------

### Build editor with CrepeBuilder and add features manually

Source: https://milkdown.dev/docs/api/crepe

Creates a CrepeBuilder instance, imports feature-specific styles and theme, adds blockEdit, toolbar, and topBar features, then creates the editor. Demonstrates getting markdown, setting readonly mode, and listening to markdownUpdated events. Useful for reducing bundle size and controlling feature order.

```javascript
import { CrepeBuilder } from '@milkdown/crepe/builder'
import { blockEdit } from '@milkdown/crepe/feature/block-edit'
import { toolbar } from '@milkdown/crepe/feature/toolbar'
import { topBar } from '@milkdown/crepe/feature/top-bar'

// You may also want to import styles by feature
import '@milkdown/crepe/theme/common/prosemirror.css'
import '@milkdown/crepe/theme/common/reset.css'
import '@milkdown/crepe/theme/common/block-edit.css'
import '@milkdown/crepe/theme/common/toolbar.css'
import '@milkdown/crepe/theme/common/top-bar.css'

// And introduce the theme
import '@milkdown/crepe/theme/crepe.css'

const builder = new CrepeBuilder({
  root: '#editor',
  defaultValue: '# Hello World',
})

// Add features manually
builder.addFeature(blockEdit).addFeature(toolbar).addFeature(topBar)

// Create the editor
const editor = await builder.create()

// Get markdown content
const markdown = builder.getMarkdown()

// Set readonly mode
builder.setReadonly(true)

// Listen to editor events
builder.on((listener) => {
  listener.markdownUpdated((ctx, markdown, prevMarkdown) => {
    // Handle updates
  })
})
```

--------------------------------

### Import and use commonmark preset

Source: https://milkdown.dev/docs/api/preset-commonmark

Basic setup to use the commonmark preset with the Milkdown editor. Import the Editor and commonmark, then create the editor with the preset.

```typescript
import { Editor } from '@milkdown/kit/core'
import { commonmark } from '@milkdown/kit/preset/commonmark'

Editor.make().use(commonmark).create()
```

--------------------------------

### Cursor Feature Configuration

Source: https://milkdown.dev/docs/api/crepe

Shows the CursorFeatureConfig interface and an example configuration for the Cursor feature.

```typescript
interface CursorFeatureConfig {
  color?: string | false // Custom cursor color
  width?: number // Cursor width in pixels
  virtual?: boolean // Enable/disable virtual cursor
}
```

```typescript
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.Cursor]: true,
  },
  featureConfigs: {
    [Crepe.Feature.Cursor]: {
      color: '#ff0000',
      width: 2,
      virtual: true,
    },
  },
}
```

--------------------------------

### Anthropic Provider Configuration

Source: https://milkdown.dev/docs/api/crepe

Example of creating an Anthropic provider with specific token limits and body parameters.

```typescript
// Anthropic: `maxTokens` (default 4096), `anthropicVersion` (default
// '2023-06-01'), and any `/v1/messages` body fields via `body`.
// `buildMessages` returns `{ system, messages }` since Anthropic puts
// the system prompt in a top-level field rather than the messages array.
createAnthropicProvider({
  apiKey,
  model: 'claude-sonnet-4-5',
  maxTokens: 2048,
  body: { temperature: 0.5 },
})
```

--------------------------------

### Crepe Features: TopBar and CodeMirror

Source: https://milkdown.dev/docs/api/crepe

Documentation for the TopBar and CodeMirror features of the Crepe editor, including configuration interfaces and examples.

```APIDOC
### TopBar Feature

A fixed toolbar at the top of the editor with heading selector, formatting buttons, insert actions, and block commands. Unlike the Toolbar feature (which appears as a floating tooltip on text selection), the TopBar is always visible. This feature is **disabled by default**.

```typescript
interface TopBarFeatureConfig {
  // Heading selector options
  headingOptions?: HeadingOption[]

  // Icon overrides
  boldIcon?: string
  italicIcon?: string
}

// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.TopBar]: true,
  },
  featureConfigs: {
    [Crepe.Feature.TopBar]: {
      headingOptions: [
        { label: 'Paragraph', value: 'p' },
        { label: 'Heading 1', value: 'h1' },
        { label: 'Heading 2', value: 'h2' },
        { label: 'Heading 3', value: 'h3' },
        { label: 'Heading 4', value: 'h4' },
        { label: 'Heading 5', value: 'h5' },
        { label: 'Heading 6', value: 'h6' },
      ],
      boldIcon: 'bold',
      italicIcon: 'italic',
    },
  },
}
```

### CodeMirror Feature

A feature that provides a code block editor with language selection, search, copy, and preview capabilities.

```typescript
interface CodeMirrorFeatureConfig {
  extensions?: Extension[] // Custom CodeMirror extensions
  languages?: LanguageDescription[] // Available languages
  theme?: Extension // CodeMirror theme

  // UI customization
  expandIcon?: string
  searchIcon?: string
  clearSearchIcon?: string
  searchPlaceholder?: string
  noResultText?: string

  // Copy button customization
  copyIcon?: string // Custom copy button icon
  copyText?: string // Custom copy button text
  onCopy?: (content: string) => void // Callback when code is copied

  // Rendering customization
  renderLanguage?: (language: string, selected: boolean) => string
  renderPreview?: (
    language: string,
    content: string
  ) => string | HTMLElement | null
  previewToggleIcon?: (previewOnlyMode: boolean) => string
  previewToggleText?: (previewOnlyMode: boolean) => string
}

// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.CodeMirror]: true,
  },
  featureConfigs: {
    [Crepe.Feature.CodeMirror]: {
      searchPlaceholder: 'Search programming language...',
      noResultText: 'No matching language found',
      theme: oneDark, // Import from @codemirror/theme-one-dark
    },
  },
}
```

It's also possible to configure the language list and theme:

```typescript
import { oneDark } from '@codemirror/theme-one-dark'
import { LanguageDescription } from '@codemirror/language'
import { markdown } from '@codemirror/lang-markdown'

const config: CreepConfig = {
  features: {
    [Crepe.Feature.CodeMirror]: {
      languages: [
        // Only load markdown language
        LanguageDescription.of({
          name: 'Markdown',
          extensions: ['md', 'markdown'],
          load() {
            return import('@codemirror/lang-markdown').then((m) => m.markdown())
          },
        }),
      ],
    },
  },
}
```

To learn which languages are available, you can refer to the CodeMirror language data.
```

--------------------------------

### Implement a Custom AI Provider

Source: https://milkdown.dev/docs/guide/ai-feature

Create a custom AI provider as an async generator that yields markdown chunks. This example uses `fetch` to communicate with an AI API.

```typescript
import type { AIProvider } from '@milkdown/crepe/feature/ai'

const customProvider: AIProvider = async function* (context, signal) {
  const response = await fetch('/api/ai', {
    method: 'POST',
    body: JSON.stringify(context),
    signal, // forward the abort signal so cancellation works
  })
  if (!response.ok || !response.body) throw new Error('AI request failed')

  const reader = response.body.getReader()
  const decoder = new TextDecoder()
  while (true) {
    const { done, value } = await reader.read()
    if (done || signal.aborted) return
    yield decoder.decode(value, { stream: true })
  }
}
```

--------------------------------

### Customize AI suggestions with buildAISuggestions

Source: https://milkdown.dev/docs/api/crepe

Configure the AI instruction palette by mutating the builder. The builder is pre-populated with defaults; use removeItem to drop built-ins, addItem to add new ones, and addSubmenu to create submenus. Call builder.clear() to start from scratch.

```typescript
const config: AIFeatureConfig = {
  buildAISuggestions: (builder) => {
    // The builder is pre-populated with the defaults; mutate freely.
    builder.removeItem('grammar') // drop a built-in
    builder.addItem('summarize', {
      icon: '<svg>…</svg>',
      label: 'Summarize',
      streamingLabel: 'Summarizing', // shown in the streaming indicator
      prompt: 'Summarize this in one paragraph.',
    })

    // Add a new submenu with its own items
    builder.addSubmenu(
      'audience',
      {
        icon: '<svg>…</svg>',
        label: 'Rewrite for audience…',
        title: 'Rewrite for audience',
        searchPlaceholder: 'Search audiences…',
      },
      (sub) => {
        sub.addItem('beginner', {
          icon: '<svg>…</svg>',
          label: 'Beginners',
          prompt: 'Rewrite this for a beginner audience.',
        })
      }
    )

    // To start from scratch instead, call builder.clear() first.
  },
}
```

--------------------------------

### crepe.create()

Source: https://milkdown.dev/docs/guide/using-crepe

Initialize the editor instance.

```APIDOC
## crepe.create()

### Description
Initializes the editor instance. This should be awaited.

### Usage
```javascript
await crepe.create();
```
```

--------------------------------

### Initialize Editor with Plugins

Source: https://milkdown.dev/docs/plugin/using-plugins

Demonstrates how to create a Milkdown editor instance and enable core plugins like commonmark, history, and listener.

```typescript
import { Editor } from '@milkdown/kit/core'
import { history } from '@milkdown/kit/plugin/history'
import { listener } from '@milkdown/kit/plugin/listener'
import { commonmark } from '@milkdown/kit/preset/commonmark'

Editor.make().use(commonmark).use(history).use(listener).create()
```

--------------------------------

### Install Milkdown Dependencies for Next.js

Source: https://milkdown.dev/docs/recipes/nextjs

Install the necessary Milkdown packages for React integration in your Next.js project using npm.

```bash
npm install @milkdown/react
npm install @milkdown/kit
npm install @milkdown/theme-nord
```

--------------------------------

### MarkParserSpec match function example

Source: https://milkdown.dev/docs/api/transformer

Example match function for a mark parser spec, checking if the mark type is 'emphasis'.

```typescript
match: (mark) => mark.type === 'emphasis'
```

--------------------------------

### NodeParserSpec match function example

Source: https://milkdown.dev/docs/api/transformer

Example match function for a node parser spec, checking if the node type is 'paragraph'.

```typescript
match: (node) => node.type === 'paragraph'
```

--------------------------------

### Configure CodeMirror feature with theme and custom languages

Source: https://milkdown.dev/docs/api/crepe

Configure the CodeMirror feature. The first block shows the CodeMirrorFeatureConfig interface and a basic example enabling the feature with a custom theme and UI text. The second block demonstrates importing a theme and language descriptions to restrict the language list to Markdown only, using LanguageDescription.of with a lazy load.

```typescript
interface CodeMirrorFeatureConfig {
  extensions?: Extension[] // Custom CodeMirror extensions
  languages?: LanguageDescription[] // Available languages
  theme?: Extension // CodeMirror theme

  // UI customization
  expandIcon?: string
  searchIcon?: string
  clearSearchIcon?: string
  searchPlaceholder?: string
  noResultText?: string

  // Copy button customization
  copyIcon?: string // Custom copy button icon
  copyText?: string // Custom copy button text
  onCopy?: (content: string) => void // Callback when code is copied

  // Rendering customization
  renderLanguage?: (language: string, selected: boolean) => string
  renderPreview?: (
    language: string,
    content: string
  ) => string | HTMLElement | null
  previewToggleIcon?: (previewOnlyMode: boolean) => string
  previewToggleText?: (previewOnlyMode: boolean) => string
  previewLabel?: () => string
}

// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.CodeMirror]: true,
  },
  featureConfigs: {
    [Crepe.Feature.CodeMirror]: {
      searchPlaceholder: 'Search programming language...',
      noResultText: 'No matching language found',
      theme: oneDark, // Import from @codemirror/theme-one-dark
    },
  },
}
```

```typescript
import { oneDark } from '@codemirror/theme-one-dark'
import { LanguageDescription } from '@codemirror/language'
import { markdown } from '@codemirror/lang-markdown'

const config: CrepeConfig = {
  features: {
    [Crepe.Feature.CodeMirror]: true,
  },
  featureConfigs: {
    [Crepe.Feature.CodeMirror]: {
      theme: oneDark,
      languages: [
        // Only load markdown language
        LanguageDescription.of({
          name: 'Markdown',
          extensions: ['md', 'markdown'],
          load() {
            return import('@codemirror/lang-markdown').then((m) => m.markdown())
          },
        }),
      ],
    },
  },
}
```

--------------------------------

### Configure Toolbar Feature with ToolbarFeatureConfig and CrepeConfig

Source: https://milkdown.dev/docs/api/crepe

Defines the ToolbarFeatureConfig interface and shows a CrepeConfig example that enables the toolbar feature and customizes icons, labels, and the toolbar builder. The aiIcon only renders when AI is enabled and a provider is configured; labels default to English.

```typescript
interface ToolbarFeatureConfig {
  boldIcon?: string
  codeIcon?: string
  italicIcon?: string
  linkIcon?: string
  strikethroughIcon?: string
  latexIcon?: string
  aiIcon?: string // Override only the toolbar's AI button (only renders when AI is enabled and a provider is configured)
  // Accessible names, for localization. Each defaults to its English label.
  boldLabel?: string
  codeLabel?: string
  italicLabel?: string
  linkLabel?: string
  strikethroughLabel?: string
  latexLabel?: string
  aiLabel?: string
  buildToolbar?: (builder: GroupBuilder<ToolbarItem>) => void
}

// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.Toolbar]: true,
  },
  featureConfigs: {
    [Crepe.Feature.Toolbar]: {
      boldIcon: customBoldIcon,
      italicIcon: customItalicIcon,
      boldLabel: 'Fett',
      buildToolbar: (builder) => {
        // Custom toolbar building logic
      },
    },
  },
}
```

--------------------------------

### Configure ImageBlock feature with onUpload callback

Source: https://milkdown.dev/docs/api/crepe

Configure the ImageBlock feature in Crepe. The interface defines all available options for inline and block images, including upload callbacks and placeholder texts. The example enables the feature and sets custom labels and an onUpload handler that returns a URL after processing the file.

```typescript
interface ImageBlockFeatureConfig {
  // Inline image configuration
  inlineUploadButton?: string
  inlineImageIcon?: string
  inlineConfirmButton?: string
  inlineUploadPlaceholderText?: string
  inlineOnUpload?: (file: File) => Promise<string>

  // Block image configuration
  blockUploadButton?: string
  blockImageIcon?: string
  blockCaptionIcon?: string
  blockConfirmButton?: string
  blockCaptionPlaceholderText?: string
  blockUploadPlaceholderText?: string
  blockOnUpload?: (file: File) => Promise<string>

  // Common configuration
  onUpload?: (file: File) => Promise<string>
  proxyDomURL?: string
}
```

```typescript
// Example:
const config: CrepeConfig = {
  features: {
    [Crepe.Feature.ImageBlock]: true,
  },
  featureConfigs: {
    [Crepe.Feature.ImageBlock]: {
      inlineUploadButton: 'Upload Image',
      blockCaptionPlaceholderText: 'Add image caption...',
      onUpload: async (file) => {
        // Handle file upload
        return 'https://example.com/image.jpg'
      },
    },
  },
}
```

--------------------------------

### MarkParserSpec runner function example

Source: https://milkdown.dev/docs/api/transformer

Example runner function for a mark parser spec, opening a mark, processing children, and closing the mark.

```typescript
runner: (state, node, type) => {
  state
    .openMark(type)
    .next(node.children)
    .closeMark(type)
}
```

--------------------------------

### NodeParserSpec runner function example

Source: https://milkdown.dev/docs/api/transformer

Example runner function for a node parser spec, opening a node, processing children, and closing the node.

```typescript
runner: (state, node, type) => {
  state
    .openNode(type)
    .next(node.children)
    .closeNode();
}
```

--------------------------------

### Customize Crepe theme variables

Source: https://milkdown.dev/docs/api/crepe

Override CSS custom properties on the .milkdown element to customize the theme. The example scales the editor's base font size from the default 16px to 14px.

```css
.milkdown {
  --crepe-base-font-size: 14px;
}
```
Tokens:
Raw