# Rehype & Remark \[Customize the Markdown and HTML pipeline]

## Overview

Vocs compiles Markdown and MDX through the unified ecosystem. Add remark plugins when you want to transform Markdown before it becomes HTML. Add rehype plugins when you want to transform HTML before it is rendered. Add recma plugins only when you need to transform the JavaScript module produced by MDX.

Configure all three through the `markdown` option in `vocs.config.ts` — you only need `vite.config.ts` when you are changing Vite itself.

:::note
Vocs already includes plugins for callouts, code groups, frontmatter, Mermaid, snippets, file trees, steps, syntax highlighting, heading anchors, and image sizing. Add custom plugins when your project needs behavior outside the built-in [Markdown Extensions](/writing/markdown-extensions).
:::

## Setup

::::steps

### Install A Plugin

Install the remark or rehype plugin you want to use.

:::code-group

```bash [npm]
npm install rehype-external-links
```

```bash [pnpm]
pnpm add rehype-external-links
```

```bash [yarn]
yarn add rehype-external-links
```

```bash [bun]
bun add rehype-external-links
```

:::

### Run Dev Server

Start the development server and open a page that uses the affected Markdown.

:::code-group

```bash [npm]
npm run dev
```

```bash [pnpm]
pnpm dev
```

```bash [yarn]
yarn dev
```

```bash [bun]
bun run dev
```

:::

::::

## Recipes

### Add Remark Plugins

Use `remarkPlugins` for transforms that work on Markdown syntax, such as adding custom directives, rewriting headings, or changing code block metadata before HTML is generated.

```ts [vocs.config.ts]
import remarkGemoji from 'remark-gemoji'
import { defineConfig } from 'vocs/config'

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkGemoji] // [!code focus]
  }
})
```

### Add Rehype Plugins

Use `rehypePlugins` for transforms that work on HTML, such as adding attributes to links, rewriting elements, or integrating HTML-focused plugins.

```ts [vocs.config.ts]
import rehypeExternalLinks from 'rehype-external-links'
import { defineConfig } from 'vocs/config'

export default defineConfig({
  markdown: {
    rehypePlugins: [ // [!code focus:8]
      [
        rehypeExternalLinks,
        {
          rel: ['noopener', 'noreferrer'],
          target: '_blank'
        }
      ]
    ]
  }
})
```

### Add Recma Plugins

Use `recmaPlugins` only when you need to transform the JavaScript module produced by MDX. Most projects should prefer remark or rehype plugins — recma plugins operate later in the pipeline and are easier to make dependent on MDX internals.

```ts [vocs.config.ts]
import recmaExportFilepath from 'recma-export-filepath'
import { defineConfig } from 'vocs/config'

export default defineConfig({
  markdown: {
    recmaPlugins: [recmaExportFilepath] // [!code focus]
  }
})
```

## Plugin Order

Vocs runs its built-in Markdown plugins first, then runs plugins from your `markdown` config. Custom rehype plugins run after syntax highlighting and heading anchors, then Vocs finishes link and image processing.

## Reference

<Cards>
  <Card title="markdown config" description="remarkPlugins, rehypePlugins, recmaPlugins, and remarkRehypeOptions." icon="settings" to="/reference/site-config#markdown" />

  <Card title="Markdown Extensions" description="Built-in callouts, code groups, file trees, steps, snippets, and more." icon="book-open" to="/writing/markdown-extensions" />

  <Card title="Vite" description="Extend the underlying Vite stack with custom plugins." icon="zap" to="/features/vite" />
</Cards>