Preview Markdown Skill

GitHub-flavored Markdown viewer that generates beautiful HTML with syntax highlighting and automatic table of contents.

Agent Usage

When the user asks to preview a Markdown file, DO NOT build HTML manually. Use the Bash tool to execute this skill's run.sh script:

# Preview a file
./run.sh README.md

# Pipe content
cat docs.md | ./run.sh

The script handles all HTML generation and automatically opens the result in the browser. Do NOT open the file manually to avoid duplicate tabs.

Usage

# Preview a Markdown file
/preview-markdown README.md

# Pipe Markdown content (preferred for temporary content)
cat docs.md | /preview-markdown
echo "# Hello\n\nThis is **markdown**" | /preview-markdown

# With custom background color
/preview-markdown article.md --background "#ffffff"

Best Practice: For temporary or generated content, prefer piping over creating temporary files. This avoids cluttering your filesystem and the content is automatically cleaned up.

Options

The script works with sensible defaults but supports these flags for flexibility:

• -o, --output PATH - Custom output path
• --no-browser - Skip browser, output file path only

Features

• GitHub-flavored Markdown rendering with full spec support
• Syntax highlighting for code blocks (100+ languages)
• Automatic TOC generation from headers
• Task lists with checkboxes
• Tables with formatting
• Images and links fully supported
• Math equations (LaTeX via KaTeX)
• Emoji support
• Footnotes and references
• Responsive design adapts to screen size

When to Use This Skill

Use this skill when the user wants to:

• Preview README or documentation files
• Read formatted Markdown documents
• Verify Markdown rendering before publishing
• Share formatted documentation
• Review pull request descriptions

Examples

Natural language requests:

• "preview this README"
• "show me the documentation"
• "open the markdown file"
• "visualize CONTRIBUTING.md"
• "let me see the formatted docs"

Technical Details

File Requirements

• File extensions: .md, .markdown
• Maximum size: 10MB (configurable)
• Encoding: UTF-8

Features in Detail

GitHub-Flavored Markdown

Supports all GitHub Markdown features:

• Headers (h1-h6)
• Bold, italic, strikethrough
• Ordered and unordered lists
• Code blocks with language specification
• Blockquotes
• Horizontal rules
• Links and images
• Tables

Syntax Highlighting

• Automatic language detection
• 100+ programming languages supported
• Theme: GitHub light/dark
• Line numbers optional
• Copy code button

Table of Contents

• Auto-generated from headers
• Clickable links to sections
• Hierarchical structure
• Sticky sidebar navigation

Task Lists

- [x] Completed task
- [ ] Pending task

Tables

Full support for:

• Header rows
• Alignment (left, center, right)
• Multi-line cells
• Inline formatting

Browser Compatibility

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Requires JavaScript enabled
• CDN-dependent: Marked.js, DOMPurify, Mermaid (for diagrams in markdown)

Output

The skill generates a standalone HTML file at:

.preview-skills/markdown/{filename}.html

The file is self-contained and can be:

• Opened directly in any browser
• Shared with others (requires internet for CDN assets)
• Archived for later viewing

Troubleshooting

Markdown doesn't render correctly

• Ensure file is valid Markdown format
• Check for unsupported extensions
• Verify UTF-8 encoding

Code blocks not highlighted

• Specify language after triple backticks
• Check that language is supported
• Example: ```javascript

Images don't load

• Use absolute URLs or relative paths
• Ensure images are accessible
• Check image file permissions

Math equations don't render

• Ensure KaTeX CDN is accessible
• Use proper LaTeX syntax
• Wrap in $ for inline, $$ for block

Development

This skill is standalone and includes all dependencies:

• Shared libraries bundled in lib/
• Templates bundled in templates/
• External CDN dependencies:
  • marked.js (Markdown parser)
  • DOMPurify (XSS prevention)
  • Mermaid (diagram support)

To modify the skill:

1. Edit config.sh for configuration
2. Edit templates/scripts/markdown-renderer.js for behavior
3. Edit templates/styles/markdown.css for styling
4. Run run.sh to test changes