Show Markdown

Show Markdown in Browser

Render markdown content in a browser using a clean, styled HTML page with CDN-based markdown parsing.

When to Use

Use this skill when the user:

• Asks to display or preview markdown files in a browser
• Wants to see how markdown content looks when rendered
• Requests visual markdown rendering with proper styling
• Needs to quickly view markdown documentation

How It Works

The skill uses:

• marked.js: Fast markdown parser loaded via CDN
• HTML template: Pre-styled template with clean CSS
• Python script: Generates HTML from markdown and opens it in the browser

Usage

Display a Markdown File

python scripts/display.py <path-to-markdown-file>

Example:

python scripts/display.py README.md

Display Markdown with Custom Title

python scripts/display.py <path-to-markdown-file> --title "My Title"

Example:

python scripts/display.py README.md --title "Project Documentation"

Display Markdown Content Directly

python scripts/display.py --content "# Hello\\n\\nThis is **bold** text"

Note: Use \\n for newlines when passing content via command line.

Path Resolution

When invoking from Claude Code, use the ${CLAUDE_PLUGIN_ROOT} variable:

python ${CLAUDE_PLUGIN_ROOT}/skills/show-markdown/scripts/display.py /path/to/file.md

Workflow

1. Identify the markdown source (file path or content)
2. Run the display script with appropriate arguments
3. Script determines the page title:
   • Explicit --title argument (highest priority)
   • First # heading from markdown content
   • Filename (without extension)
   • "Markdown Preview" (default)
4. Script generates HTML with embedded markdown
5. HTML opens in default browser via xdg-open
6. Temp file is created in system temp directory

Features

• Fast rendering via marked.js CDN
• Clean, GitHub-inspired styling
• Responsive design
• Code syntax highlighting
• Dark mode support (system preference)
• Temporary file generation (no cleanup needed)
• Smart title detection (explicit → heading → filename → default)
• Mermaid diagram rendering (flowcharts, sequence diagrams, Gantt charts, class diagrams, etc.)
• Click-to-zoom for mermaid diagrams (opens in modal)

Technical Details

• Markdown Parser: marked.js (https://cdn.jsdelivr.net/npm/marked/marked.min.js)
• Diagram Rendering: mermaid.js (https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js)
• Syntax Highlighting: highlight.js (https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js)
• Browser: Opens via xdg-open (respects system default)
• Temp Files: Created using Python's tempfile.mkstemp
• Character Encoding: UTF-8

Examples

Show a README file

python scripts/display.py README.md

Show a README file with custom title

python scripts/display.py README.md --title "My Project Documentation"

Show documentation

python scripts/display.py docs/api.md

Render inline markdown

python scripts/display.py --content "# Title\\n\\n- Item 1\\n- Item 2\\n\\nCode: `example`"

Render inline markdown with custom title

python scripts/display.py --content "# Title\\n\\nContent" --title "My Custom Title"

Mermaid Diagrams

The skill supports rendering mermaid diagrams inline. Use fenced code blocks with the mermaid language identifier:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do something]
    B -->|No| D[Do something else]
    C --> E[End]
    D --> E
```

Supported diagram types:

• Flowcharts (graph TD, graph LR, etc.)
• Sequence diagrams (sequenceDiagram)
• Class diagrams (classDiagram)
• State diagrams (stateDiagram-v2)
• Entity relationship diagrams (erDiagram)
• Gantt charts (gantt)
• Pie charts (pie)
• And more (see Mermaid documentation)

Click-to-zoom: Click on any rendered diagram to open it in a larger modal view. Press Escape or click the backdrop to close.

Notes

• The browser opens the rendered HTML immediately
• The temp file remains for the browser session
• No manual cleanup required - temp files are managed by the system
• Works best on Linux systems with xdg-open installed
• Mermaid diagrams automatically adapt to light/dark mode based on system preference