@wireweave/markdown-plugin

Markdown plugins to embed Wireweave diagrams in your documentation

Installation

npm install @wireweave/markdown-plugin
# or
pnpm add @wireweave/markdown-plugin
# or
yarn add @wireweave/markdown-plugin

Supported Libraries

• markdown-it - Most popular Markdown parser
• marked - Fast Markdown compiler
• remarkable - Markdown parser with CommonMark support

Quick Start

markdown-it

import MarkdownIt from 'markdown-it';
import { markdownItWireframe } from '@wireweave/markdown-plugin';

const md = new MarkdownIt();
md.use(markdownItWireframe, {
  format: 'svg-img',  // or 'html', 'html-preview', 'svg'
  theme: 'light',     // or 'dark'
});

const html = md.render(`
# My Documentation

\`\`\`wireframe
page {
  card p=4 {
    title "Login"
    input "Email" inputType=email
    input "Password" inputType=password
    button "Sign In" primary
  }
}
\`\`\`
`);

marked

import { marked } from 'marked';
import { markedWireframe } from '@wireweave/markdown-plugin';

marked.use(markedWireframe({
  format: 'svg-img',
  theme: 'light',
}));

const html = marked.parse(`
# Documentation

\`\`\`wireframe
page { button "Click me" primary }
\`\`\`
`);

remarkable

import { Remarkable } from 'remarkable';
import { remarkableWireframe } from '@wireweave/markdown-plugin';

const md = new Remarkable();
remarkableWireframe(md, {
  format: 'svg-img',
  theme: 'light',
});

const html = md.render(`
\`\`\`wireframe
page { card { text "Hello" } }
\`\`\`
`);

Options

All plugins accept the same options:

Option	Type	Default	Description
format	'html' | 'html-preview' | 'svg' | 'svg-img'	'svg-img'	Output format
theme	'light' | 'dark'	'light'	Theme for rendering
containerClass	string	'wireframe-container'	CSS class for wrapper div
errorHandling	'code' | 'error' | 'both'	'both'	How to handle parse errors
containerWidth	number	0	Container width for preview scaling (0 = no scaling)
maxScale	number	1	Maximum scale factor (prevents upscaling beyond this value)

Output Formats

• svg-img (default): Base64-encoded SVG in an <img> tag. Best for compatibility.
• svg: Inline SVG. Allows CSS styling but may conflict with page styles.
• html: Full HTML/CSS rendering. Interactive but may conflict with page styles.
• html-preview: HTML with preview container that supports scaling to fit container width.

Error Handling

• both (default): Shows both error message and original code
• error: Shows only the error message
• code: Shows only the original code

Standalone Rendering

You can also use the renderWireframe function directly:

import { renderWireframe } from '@wireweave/markdown-plugin';

const html = renderWireframe(`
  page { button "Click" primary }
`, {
  format: 'html-preview',
  theme: 'light',
  containerClass: 'my-wireframe',
  containerWidth: 600,  // Scale to fit 600px width
});

Styling

Add CSS to style the wireframe containers:

.wireframe-container {
  margin: 1rem 0;
  border: 1px solid #e0e0e0;
  border-radius: 4px;
  overflow: hidden;
}

.wireframe-container img {
  display: block;
  max-width: 100%;
  height: auto;
}

.wireframe-error {
  color: #d32f2f;
  background: #ffebee;
  padding: 1rem;
  margin: 0;
}

.wireframe-source {
  background: #f5f5f5;
  padding: 1rem;
  margin: 0;
  overflow-x: auto;
}

Integration Examples

VitePress / VuePress

// .vitepress/config.ts
import { markdownItWireframe } from '@wireweave/markdown-plugin';

export default {
  markdown: {
    config: (md) => {
      md.use(markdownItWireframe);
    },
  },
};

Docusaurus

// docusaurus.config.js
const { markdownItWireframe } = require('@wireweave/markdown-plugin');

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [],
          rehypePlugins: [],
        },
      },
    ],
  ],
  // For markdown-it based setup
};

Astro

// astro.config.mjs
import { markdownItWireframe } from '@wireweave/markdown-plugin';

export default {
  markdown: {
    remarkPlugins: [],
    rehypePlugins: [],
    // For markdown-it integration
  },
};

API Reference

markdownItWireframe(md, options?)

Plugin for markdown-it.

import type MarkdownIt from 'markdown-it';
import type { WireframePluginOptions } from '@wireweave/markdown-plugin';

function markdownItWireframe(
  md: MarkdownIt,
  options?: WireframePluginOptions
): void;

markedWireframe(options?)

Extension for marked.

import type { MarkedExtension } from 'marked';
import type { WireframePluginOptions } from '@wireweave/markdown-plugin';

function markedWireframe(
  options?: WireframePluginOptions
): MarkedExtension;

remarkableWireframe(md, options?)

Plugin for remarkable.

import type { Remarkable } from 'remarkable';
import type { WireframePluginOptions } from '@wireweave/markdown-plugin';

function remarkableWireframe(
  md: Remarkable,
  options?: WireframePluginOptions
): void;

renderWireframe(code, options?)

Standalone render function.

import type { WireframePluginOptions } from '@wireweave/markdown-plugin';

function renderWireframe(
  code: string,
  options?: WireframePluginOptions
): string;

License

MIT