@grandaniel/vue-markdown-editor

@grandaniel/vue-markdown-editor

A block-based, Notion-like Markdown editor and SSR-safe renderer for Vue 3. UI-first. Powered by TipTap.

@grandaniel/vue-markdown-editor provides two complementary packages:

• Editor — A rich block-editing experience where every Markdown element — headlines, bullet & numbered lists, tables, blockquotes, code blocks, dividers, images, and files — is its own independently editable, draggable block. Built for content-first workflows: write, reorder, and format with keyboard shortcuts and an always-visible drag handle.

• Renderer — A lightweight, SSR-safe component that renders Markdown strings to semantic HTML. Uses the same remark-parse pipeline as the editor, so custom module blocks render identically. Fully customizable: override any default render component with your own Vue components.

Images are first-class citizens: paste an image to auto-upload, then edit its src, alt text, and caption in a dedicated modal. The editor serializes back to clean Markdown automatically.

Table of Contents

• Who uses it
• Installation
• Editor
  • Quick Start
  • Keyboard Shortcuts
  • Image Upload
  • API Reference
• Renderer
  • Quick Start
  • Custom Render Components
  • API Reference
• Exported Types & Utilities
• Custom Styling
• Supply Chain Security
• Contributing
• License

Who uses it

Installation

npm install @grandaniel/vue-markdown-editor

Peer dependency: Vue ^3.5.0
Node: >=22

Import the components and the stylesheet:

import {
  MarkdownEditor,
  MarkdownRenderer,
  useMarkdownEditor,
  useMarkdownRenderer,
} from "@grandaniel/vue-markdown-editor";
import "@grandaniel/vue-markdown-editor/style.css";

Editor

The editor is driven by a composable: useMarkdownEditor() creates the reactive state, and <MarkdownEditor> renders it.

Editor Quick Start

<script setup lang="ts">
import { ref } from "vue";
import {
  MarkdownEditor,
  useMarkdownEditor,
  type MarkdownAstNode,
} from "@grandaniel/vue-markdown-editor";
import "@grandaniel/vue-markdown-editor/style.css";

const editor = useMarkdownEditor("# Hello, world!\n\nStart writing here…");
const focusedNode = ref<MarkdownAstNode | null>(null);
</script>

<template>
  <MarkdownEditor :editor="editor" v-model:focused-node="focusedNode" />
</template>

Reading the output

The composable keeps the raw Markdown in sync automatically. Read it at any time:

console.log(editor.markdownContent.value);
// "# Hello, world!\n\nStart writing here…"

You can also programmatically set the content:

editor.markdownContent.value = "## New heading\n\nFresh content.";

Keyboard Shortcuts

Auto type‑detection

Type # , ## , or ### at the start of a paragraph and the block auto‑converts to the matching heading level.

Block modules & serialized Markdown

The editor splits Markdown into block modules — every module is its own draggable, editable block:

Most blocks are parsed from standard Markdown — paste a Markdown document and it is split into blocks automatically. Headings also convert on the fly: type # , ## , or ### at the start of a paragraph, or type > , 1. , a code fence, or --- for the matching non-heading block.

The special """…""" blocks carry extra metadata and are used for images and files. Here is the exact Markdown the editor accepts and produces for every module:

# Heading 1

## Heading 2

### Heading 3

A **paragraph** with _inline_ markup and a [link](https://example.com).

- Bullet item one
- Bullet item two

1. Numbered item one
2. Numbered item two

> A blockquote line
> Another blockquote line

```ts
const port = 25565;
```

---

| Module | Kind          |
| ------ | ------------- |
| Table  | Grid of cells |

"""MarkdownModuleImage
src: https://example.com/photo.jpg
alt: A scenic view
caption: Photo caption
"""

"""MarkdownModuleFile
url: https://example.com/file.pdf
fileName: file.pdf
fileSize: 1024
mimeType: application/pdf
"""

Image Upload

Images are first-class blocks with src, alt text, and caption fields. Right‑click any image → Edit Attributes to open the editing modal.

Paste‑to‑upload

Pass an imageUploadFunction prop — any pasted image (Ctrl+V) from the clipboard will be sent through your upload handler and inserted as a new image block:

<script setup lang="ts">
async function uploadImage(file: File): Promise<string> {
  const formData = new FormData();
  formData.append("image", file);

  const res = await fetch("/api/upload", { method: "POST", body: formData });
  const { url } = await res.json();
  return url;
}
</script>

<template>
  <MarkdownEditor :editor="editor" :image-upload-function="uploadImage" />
</template>

The serialized Markdown uses a custom block syntax for images:

"""MarkdownModuleImage
src: https://example.com/photo.jpg
alt: A scenic mountain view
caption: Photo taken during the 2026 summit
"""

Note: imageUploadFunction is optional. Without it, pasted images from the clipboard are ignored.

Editor API Reference

useMarkdownEditor(initialContent?: string)

Returns a reactive editor instance:

MarkdownEditor props

MarkdownEditor emits

MarkdownEditor slots

Renderer

<MarkdownRenderer> converts a Markdown string to semantic HTML. It uses the same remark-parse pipeline as the editor, so custom module blocks (like """MarkdownModuleImage""") render as rich <figure> elements automatically.

The renderer is SSR‑safe — no browser APIs, no TipTap. It works in nuxt generate, vite-ssg, and any server‑side rendering context.

Renderer Quick Start

<script setup lang="ts">
import { MarkdownRenderer } from "@grandaniel/vue-markdown-editor";

const markdown = `# Hello World

This is a **paragraph** with *inline* formatting.

- Bullet item one
- Bullet item two

1. Numbered item one
2. Numbered item two

> A short blockquote.

| Feature | Status |
| --- | --- |
| Tables | Rendered |
| Code | Fenced |

---

"""MarkdownModuleImage
src: https://example.com/photo.jpg
alt: A scenic view
caption: Photo caption
"""
`;
</script>

<template>
  <MarkdownRenderer :markdown="markdown" />
</template>

Live preview alongside the editor

Bind the editor's reactive markdownContent to the renderer:

<script setup lang="ts">
import {
  MarkdownEditor,
  MarkdownRenderer,
  useMarkdownEditor,
} from "@grandaniel/vue-markdown-editor";

const editor = useMarkdownEditor("# Start writing…");
</script>

<template>
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 2rem;">
    <MarkdownEditor :editor="editor" />
    <MarkdownRenderer :markdown="editor.markdownContent.value" />
  </div>
</template>

Custom Render Components

You can override any default render component with your own Vue component. Use useMarkdownRenderer() to create a renderer instance, then call overrideComponent() to swap in your custom component for a specific node type.

Each override is strictly typed — the replacement component must accept a state prop matching the correct state class for that node type (e.g. MarkdownModuleImageState for images, MarkdownModuleTextState for paragraphs and headings).

Overriding the image render component

<script setup lang="ts">
import {
  MarkdownRenderer,
  useMarkdownRenderer,
  MarkdownAstNodeType,
  type MarkdownModuleImageState,
} from "@grandaniel/vue-markdown-editor";
import CustomImageRender from "./CustomImageRender.vue";

// Create a renderer instance and override the image component
const renderer = useMarkdownRenderer();
renderer.overrideComponent(MarkdownAstNodeType.IMAGE, CustomImageRender);

const markdown = `"""MarkdownModuleImage
src: https://example.com/photo.jpg
alt: A scenic view
caption: My custom caption
"""
`;
</script>

<template>
  <MarkdownRenderer :markdown="markdown" :renderer="renderer" />
</template>

Your custom component receives the state as a typed prop:

<!-- CustomImageRender.vue -->
<script setup lang="ts">
import { type MarkdownModuleImageState } from "@grandaniel/vue-markdown-editor";

defineProps<{ state: MarkdownModuleImageState }>();
</script>

<template>
  <div class="my-custom-image-wrapper">
    <img :src="https://raw.githubusercontent.com/danielgran/vue-markdown-editor/HEAD/state.src" :alt="state.alt" />
    <span class="my-caption">{{ state.caption }}</span>
  </div>
</template>

Available node types and their state classes

Renderer API Reference

useMarkdownRenderer()

Returns a reactive renderer instance with a customizable component registry:

MarkdownRenderer props

Exported Types & Utilities

Custom Styling

All components use scoped SCSS. To override styles, use global CSS with higher specificity, or Vue's :deep() combinator from a parent component.

CSS class reference

Styling TipTap content

Each text‑based block hosts its own TinyMCE‑style TipTap editor. Target .tiptap inside a block's content area:

/* Make all TipTap editors use your font */
.markdown-editor-module-content .tiptap {
  font-family: "Georgia", serif;
  font-size: 1.1rem;
  line-height: 1.8;
}

Do's

• ✅ Import the stylesheet: import "@grandaniel/vue-markdown-editor/style.css"
• ✅ Use global (unscoped) CSS or :deep() from a parent to override styles
• ✅ Target .tiptap inside .markdown-editor-module-content for editor typography
• ✅ Use z-index values above 1000 / 9999 for anything that must layer above context menus and modals

Don'ts

• ❌ Don't rely on CSS custom properties — the editor uses hard‑coded Tailwind‑scale colors (grays and blues)
• ❌ Don't override z-index on .markdown-editor-context-menu or .markdown-editor-modal-overlay — it will break layering
• ❌ Don't use display: contents on .markdown-editor-module — it interferes with SortableJS drag logic
• ❌ Don't set outline: none on .markdown-editor-module-content globally — the focus ring is intentional for keyboard navigation

Supply Chain Security

We take package integrity seriously.

To verify provenance locally:

npm audit signatures

Contributing

We welcome contributions! Please follow the guidelines below.

PR Policy

1. Fork the repository and create a feature branch off dev.

2. Keep changes focused — one feature or fix per PR.

3. Add tests for any new functionality. The project uses Vitest + @vue/test-utils.

4. Run the full check before pushing:

   npm ci
   npm run test
   npm run type-check
   npm run build
   

5. Open a PR against the dev branch with a clear description of what changed and why.

Dev setup

# Clone and install
git clone https://github.com/danielgran/vue-markdown-editor.git
cd vue-markdown-editor
npm ci

# Start the dev server
npm run dev

The dev server launches at http://localhost:4010. The entry point is dev/App.vue — a full showcase that demonstrates every editor feature: block types, drag & drop, image upload, context menus, keyboard navigation, and Markdown output serialization. Use it as a playground while developing.

License

ISC © 2026 danielgran

All components use scoped SCSS. To override styles, use global CSS with higher specificity, or Vue's :deep() combinator from a parent component.

CSS class reference

Styling TipTap content

Each text‑based block hosts its own TinyMCE‑style TipTap editor. Target .tiptap inside a block's content area:

/* Make all TipTap editors use your font */
.markdown-editor-module-content .tiptap {
  font-family: "Georgia", serif;
  font-size: 1.1rem;
  line-height: 1.8;
}

Do's

• ✅ Import the stylesheet: import "@grandaniel/vue-markdown-editor/style.css"
• ✅ Use global (unscoped) CSS or :deep() from a parent to override styles
• ✅ Target .tiptap inside .markdown-editor-module-content for editor typography
• ✅ Use z-index values above 1000 / 9999 for anything that must layer above context menus and modals

Don'ts

• ❌ Don't rely on CSS custom properties — the editor uses hard‑coded Tailwind‑scale colors (grays and blues)
• ❌ Don't override z-index on .markdown-editor-context-menu or .markdown-editor-modal-overlay — it will break layering
• ❌ Don't use display: contents on .markdown-editor-module — it interferes with SortableJS drag logic
• ❌ Don't set outline: none on .markdown-editor-module-content globally — the focus ring is intentional for keyboard navigation

Supply Chain Security

We take package integrity seriously.

To verify provenance locally:

npm audit signatures

Contributing

We welcome contributions! Please follow the guidelines below.

PR Policy

1. Fork the repository and create a feature branch off dev.

2. Keep changes focused — one feature or fix per PR.

3. Add tests for any new functionality. The project uses Vitest + @vue/test-utils.

4. Run the full check before pushing:

   npm ci
   npm run test
   npm run type-check
   npm run build
   

5. Open a PR against the dev branch with a clear description of what changed and why.

Dev setup

# Clone and install
git clone https://github.com/danielgran/vue-markdown-editor.git
cd vue-markdown-editor
npm ci

# Start the dev server
npm run dev

The dev server launches at http://localhost:4010. The entry point is dev/App.vue — a full showcase that demonstrates every editor feature: block types, drag & drop, image upload, context menus, keyboard navigation, and Markdown output serialization. Use it as a playground while developing.

License

ISC © 2026 danielgran