Skip to content

plugin-markdown.mdx

Latest commit

 

History

History
389 lines (281 loc) · 7.86 KB

plugin-markdown.mdx

File metadata and controls

389 lines (281 loc) · 7.86 KB
Raw
title Plugin Markdown

import { InteractiveDemo } from '@/app/components/InteractiveDemo'; import { PluginLoader } from '@/app/components/PluginLoader';

Markdown renderer with GitHub Flavored Markdown support.

Installation

npm install @object-ui/plugin-markdown

<PluginLoader plugins={['markdown']}>

Usage

Basic Usage

// Import once in your app entry point
import '@object-ui/plugin-markdown'

// Use in schemas
const schema = {
  type: 'markdown',
  content: '# Hello World\n\nThis is **markdown** text with [links](https://example.com).'
}

Interactive Examples

Features

  • GitHub Flavored Markdown (tables, task lists, strikethrough)
  • XSS protection (sanitized output)
  • Code syntax highlighting
  • Lazy-loaded (~100-200 KB loads only when rendered)

Schema API

{
  type: 'markdown',
  content: string,     // Markdown content (required)
  className?: string   // Tailwind classes
}

MarkdownSchema

Declared by @object-ui/types (packages/types/src/data-display.ts) and re-exported by @object-ui/plugin-markdown, so either import spelling resolves to the same type. The plugin used to ship a second declaration of this name; the two have been converged onto the one authority (objectui#6172). It extends BaseSchema, so the shared component properties are available on a markdown node as well as the ones below.

content is required: the plugin registers it as a required input, the renderer's own props type takes a non-optional string, and the Zod mirror (packages/types/src/zod/data-display.zod.ts) validates it as z.string().

Property Type Default Description
content string — (required) Markdown content to render
className string '' Additional Tailwind CSS classes

Retired (objectui#6972): sanitize and components used to be listed here. Neither was ever read. sanitize (a boolean defaulting to true) implied a switch that does not exist: sanitization is unconditional — rehype-sanitize is a fixed last link of the renderer's rehype chain, and no value of the key ever switched it, so sanitize: false changed nothing while reading as a security control. components (a Record of React component overrides) is not a value a JSON document can author, and the renderer's own fenced-block overrides (mermaid / metadata) are a fixed internal map, not an authoring surface. Both keys are now never on the TypeScript face and are refused by name by the Zod mirror, with that explanation in the parse message. There is no authored spelling that disables XSS sanitization, and no authored spelling that overrides markdown elements; delete the keys.

Supported Markdown Features

Headers

# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`

Links and Images

[Link text](https://example.com)
![Alt text](https://example.com/image.jpg)

Lists

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2
   1. Nested ordered item

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Code Blocks

```javascript
function hello() {
  console.log("Hello, World!");
}
```

Blockquotes

> This is a blockquote
> It can span multiple lines

Horizontal Rules

---
***
___

Examples

Documentation Page

const docSchema = {
  type: 'markdown',
  content: `
# Getting Started

Welcome to our documentation!

## Installation

Install the package using npm:

\`\`\`bash
npm install our-package
\`\`\`

## Quick Start

1. Import the package
2. Configure your settings
3. Start building!

For more information, see the [API Reference](/docs/api/schema-reference).
  `,
  className: 'prose prose-lg max-w-none'
}

README Viewer

const readmeSchema = {
  type: 'markdown',
  content: `
# Project Name

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()

A brief description of the project.

## Features

- ✅ Feature 1
- ✅ Feature 2
- ✅ Feature 3

## Installation

\`\`\`bash
npm install project-name
\`\`\`

## Usage

\`\`\`javascript
import { Component } from 'project-name'

const app = new Component()
app.run()
\`\`\`

## Contributing

Contributions are welcome! Please read our [contributing guidelines](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md).

## License

MIT
  `,
  className: 'prose dark:prose-invert'
}

Release Notes

const releaseNotes = {
  type: 'markdown',
  content: `
# Release Notes - v2.5.0

## 🎉 New Features

- Added dark mode support
- Improved performance by 40%
- New dashboard components

## 🐛 Bug Fixes

- Fixed login redirect issue (#123)
- Resolved memory leak in table component (#456)

## 🔄 Changes

- Updated dependencies
- Improved documentation
- Refactored authentication flow

## ⚠️ Breaking Changes

- Removed deprecated \`oldAPI\` method
- Changed config file format from JSON to YAML

## 📦 Dependencies

| Package | Old Version | New Version |
|---------|------------|-------------|
| react   | 18.2.0     | 18.3.0      |
| vite    | 4.5.0      | 5.0.0       |
  `
}

API Documentation

const apiDocs = {
  type: 'markdown',
  content: `
# API Reference

## Methods

### \`getData(id: string): Promise<Data>\`

Fetches data by ID.

**Parameters:**
- \`id\` (string) - The unique identifier

**Returns:**
- Promise resolving to Data object

**Example:**
\`\`\`typescript
const data = await getData('user-123')
console.log(data.name)
\`\`\`

### \`updateData(id: string, updates: Partial<Data>): Promise<void>\`

Updates existing data.

**Parameters:**
- \`id\` (string) - The unique identifier
- \`updates\` (Partial<Data>) - Fields to update

**Example:**
\`\`\`typescript
await updateData('user-123', { name: 'John Doe' })
\`\`\`
  `
}

Styling with Tailwind

Use Tailwind Typography plugin for better markdown styling:

const schema = {
  type: 'markdown',
  content: '# My Document\n\nContent here...',
  className: 'prose prose-lg prose-slate dark:prose-invert max-w-none'
}

Common prose classes:

  • prose - Base typography styles
  • prose-sm / prose-lg / prose-xl - Size variants
  • prose-slate / prose-gray - Color schemes
  • dark:prose-invert - Dark mode support
  • max-w-none - Remove max-width constraint

Security (XSS Protection)

All markdown content is automatically sanitized using rehype-sanitize to prevent XSS attacks:

// Safe - HTML tags are sanitized
const schema = {
  type: 'markdown',
  content: '**Safe** markdown with <script>alert("XSS")</script>'
}
// The script tag will be removed in the output

Bundle Size

The plugin uses lazy loading to optimize bundle size:

  • Initial load: ~0.2 KB (entry point)
  • Lazy chunk: ~100-200 KB (loaded when markdown is rendered)
  • Includes react-markdown and plugins

TypeScript Support

import type { MarkdownSchema } from '@object-ui/plugin-markdown'

const markdownSchema: MarkdownSchema = {
  type: 'markdown',
  content: '# Hello TypeScript!'
}

Related Documentation