MUI Docs Infra

Transform Markdown Demo Links

A remark plugin that automatically cleans up "[See Demo]" links and horizontal rules that follow Demo components in markdown documentation. This plugin identifies Demo components (without .Title) and removes associated navigation elements to create cleaner documentation.

Overview

Use this plugin to automatically clean up demo-related markdown patterns in your documentation. It removes redundant "[See Demo]" links that point to demo pages and optional horizontal rules that follow Demo components, streamlining the reading experience by eliminating unnecessary navigation clutter.

Key Features

  • Demo component detection: Identifies <Demo components without .Title props
  • Link removal: Removes "[See Demo]" links that follow Demo components
  • Rule cleanup: Removes horizontal rules (---) that follow Demo components
  • Multiple formats: Supports standalone, multiline, and mixed-content Demo components
  • Smart detection: Only removes elements that directly follow Demo components
  • Safe processing: Preserves all other markdown content and structure

Installation & Usage

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import transformMarkdownDemoLinks from '@mui/internal-docs-infra/pipeline/transformMarkdownDemoLinks';

const processor = unified().use(remarkParse).use(transformMarkdownDemoLinks);

With docs-infra

This plugin is automatically included when using withDocsInfra() from @mui/internal-docs-infra. See the CodeHighlighter documentation for examples of Demo components in action.

Syntax Examples

Basic Demo Component Cleanup

The most common usage - removes "[See Demo]" links and horizontal rules that follow Demo components:

Before:

<Demo src="ButtonDemo" />

[See Demo](/material-ui/react-button/)

---

More content here...

After:

<Demo src="ButtonDemo" />

More content here...

Demo Component with Properties

Before:

<Demo 
  src="advanced/ButtonDemo" 
  variant="playground"
  height={400}
/>

[See Demo](/material-ui/react-button/playground/)

---

Next section content...

After:

<Demo 
  src="advanced/ButtonDemo" 
  variant="playground"
  height={400}
/>

Next section content...

Horizontal Rule Only Cleanup

Removes horizontal rules even when there's no "[See Demo]" link:

Before:

<Demo src="SimpleDemo" />

---

Continue reading...

After:

<Demo src="SimpleDemo" />

Continue reading...

Demo Component Detection

The plugin detects Demo components in various formats:

Standalone HTML:

<Demo src="ButtonDemo" />

Opening/Closing Tags:

<Demo src="ButtonDemo">
  Content here
</Demo>

Multiline with Properties:

<Demo 
  src="advanced/ButtonDemo" 
  variant="playground"
  height={400}
/>

Demo.Title Exclusion

Demo components with .Title are not processed:

Preserved (not cleaned up):

<Demo.Title>Button Examples</Demo.Title>

[See Demo](/material-ui/react-button/)

---

This pattern remains unchanged because Demo.Title components serve a different purpose and their associated links should be preserved.

Plugin Behavior

Processing Rules

  1. Demo detection: Scans for HTML elements containing "Demo" components
  2. Sequential processing: Checks the next elements after each Demo component
  3. Link identification: Looks for paragraphs containing "[See Demo]" links
  4. Rule removal: Removes horizontal rules that follow Demo components
  5. Safe removal: Only removes elements that directly follow Demo components

Element Matching

"[See Demo]" Links:

  • Must be in a paragraph element
  • Must contain text that starts with "[See Demo]"
  • Must be the immediate next element after a Demo component

Horizontal Rules:

  • Standard markdown horizontal rules (---)
  • Must immediately follow a Demo component or "[See Demo]" link

Content Preservation

The plugin preserves:

  • All non-Demo HTML components
  • Demo components with .Title
  • "[See Demo]" links not following Demo components
  • Horizontal rules not following Demo components
  • All other markdown content and structure

Common Use Cases

Documentation Cleanup

Remove redundant navigation elements from documentation that already contains interactive demos.

Migration from External Demos

Clean up documentation when migrating from external demo pages to embedded demos.

Streamlined Reading Experience

Eliminate navigation clutter to create a more focused reading experience.

Configuration

This plugin works out-of-the-box with no configuration required. It automatically detects Demo components and cleans up associated navigation elements.

For more information about Demo components and how they work with the CodeHighlighter system, see the CodeHighlighter documentation.

Troubleshooting

Links Not Being Removed

Problem: "[See Demo]" links remain in the output.

Solutions:

  • Ensure the link immediately follows a Demo component
  • Verify the link text starts with "[See Demo]"
  • Check that the Demo component doesn't have .Title

Demo Components Not Detected

Problem: The plugin doesn't recognize Demo components.

Solutions:

  • Verify the HTML element contains "Demo" in the tag name
  • Check that it's not Demo.Title (which is excluded)
  • Ensure proper HTML syntax in the markdown

Unexpected Content Removal

Problem: Content is being removed that shouldn't be.

Solutions:

  • Verify that removed content immediately follows a Demo component
  • Check for "[See Demo]" text in unexpected places
  • Ensure proper markdown structure