show-markdown

What this skill does

# 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

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

Example:
```bash
python scripts/display.py README.md
```

### Display Markdown with Custom Title

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

Example:
```bash
python scripts/display.py README.md --title "Project Documentation"
```

### Display Markdown Content Directly

```bash
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:

```bash
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

```bash
python scripts/display.py README.md
```

### Show a README file with custom title

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

### Show documentation

```bash
python scripts/display.py docs/api.md
```

### Render inline markdown

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

### Render inline markdown with custom title

```bash
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:

````markdown
```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](https://mermaid.js.org/))

**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