Free Markdown View

🚀 A powerful VS Code Markdown preview extension with Mermaid diagram support, math formulas, HTML syntax, image support, and PDF export.

✨ Features

• 📝 Markdown Rendering: Supports CommonMark and GFM extended syntax
• 📊 Mermaid Diagrams: Supports all 23 diagram types (v11.12.2)
• 🔢 Math Formulas: Supports LaTeX math formulas (inline and block)
• 🌐 HTML Syntax: Safe HTML tag support
• 🖼️ Image Support: Supports multiple image formats (PNG, JPG, SVG, GIF, WebP) with flexible size control
  • Multiple ways to set image size: markdown-it-imsize syntax (=widthxheight), markdown-it-attrs syntax ({width=300 height=200}), or HTML tags
  • Support for custom attributes: Use markdown-it-attrs to add class, id, style, and other attributes to any Markdown element
• 📄 PDF Export: Export Markdown to PDF with intelligent sizing
• ⌨️ Keyboard Shortcuts: Ctrl+Shift+M to toggle preview

🚀 Quick Start

1. Install: Search "Free Markdown View" in VS Code Extensions
2. Open: Open a Markdown file
3. Toggle Preview: Press Ctrl+Shift+M (Windows/Linux) or Cmd+Shift+M (macOS)
4. Export PDF: Use Ctrl+Shift+E to export as PDF

⌨️ Keyboard Shortcuts

• Ctrl+Shift+M (Windows/Linux) or Cmd+Shift+M (macOS): Toggle preview (open/close preview panel)
• Ctrl+Shift+V (Windows/Linux) or Cmd+Shift+V (macOS): Open preview to the side
• Ctrl+Shift+E (Windows/Linux) or Cmd+Shift+E (macOS): Export to PDF
• Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (macOS): Batch Export to PDF

Tip: If shortcuts don't work, you can use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) to search for:

• "Toggle Preview" - Toggle preview
• "Open Preview to the Side" - Open preview to the side
• "Export to PDF" - Export to PDF
• "Batch Export to PDF" - Batch export multiple Markdown files to PDF

📊 Supported Mermaid Diagram Types

Basic Diagrams

• Flowchart
• Sequence Diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Quadrant Chart
• Requirement Diagram
• GitGraph
• C4 Diagram
• Mindmaps
• Timeline
• ZenUML

New Feature Diagrams 🔥

• Sankey
• XY Chart
• Block Diagram
• Packet
• Kanban
• Architecture (with icon support: logos, mdi, carbon, fa)
• Radar
• Treemap

Note: Architecture diagrams support icon packs (logos, mdi, carbon, fa). Icons are displayed correctly in both preview and PDF export modes.

🔢 Math Formula Support

Supports LaTeX math formulas:

• Inline: $E = mc^2$ or \(x^2 + y^2 = z^2\)
• Block: $$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$ or \[...\]

🖼️ Image Size Control

Multiple ways to set image size:

1. markdown-it-imsize syntax:

   ![alt](https://gitee.com/fanzhiyu/free-markdown-view/image.png =300x200)
   

   • Set both width and height: =300x200
   • Set width only: =300x
   • Set height only: =x200

2. markdown-it-attrs syntax:

   ![alt](https://gitee.com/fanzhiyu/free-markdown-view/image.png){width=300 height=200}
   

   • Add custom attributes:

   ![alt](https://gitee.com/fanzhiyu/free-markdown-view/image.png){.custom-class #id style="width: 300px;"}
   

3. HTML tags:

   <img src="https://gitee.com/fanzhiyu/free-markdown-view/image.png" width="300" height="200">
   

🎨 Custom Attributes

Use markdown-it-attrs to add custom attributes to any Markdown element:

• Text:

  **Bold text**{.highlight style="color: red;"}
  

• Links:

  [Link](https://example.com){.external target="_blank"}
  

• Images:

  ![Image](https://gitee.com/fanzhiyu/free-markdown-view/example.png){.rounded style="border-radius: 8px;"}
  

• Headings:

  ### Title {#custom-id .custom-class}
  

• Code blocks: `code`{.code-inline}

🏗️ Architecture

The extension follows a modular architecture with a service layer for shared functionality:

• Service Layer (src/services/): Manages shared services using Singleton pattern

  • ExtensionContextService: Manages extension path resolution and caching
  • IconPackService: Manages icon pack loading and caching

• Core Modules:

  • MarkdownParser: Parses Markdown content
  • PDFExporter: Exports Markdown to PDF
  • MarkdownPreviewProvider: Manages WebView panels
  • ResourceLoader: Loads local resources (KaTeX fonts, Highlight.js, etc.)

For detailed architecture documentation, see docs/架构设计.md.

🛠️ Development

# Install dependencies
npm install

# Compile
npm run compile

# Watch mode
npm run watch

# Run tests
npm test

# PDF export test (check Mermaid diagram sizing and blank spaces)
npm run test:pdf

# PDF export test (auto continuous testing)
npm run test:pdf:watch

📦 Packaging

Package Release Version

# Method 1: Use npm script (recommended, auto-compile)
npm run package:prepublish

# Method 2: Use vsce directly (need to compile first)
npm run compile
npm run package

After packaging, a .vsix file will be generated in the project root directory with the format: free-markdown-view-0.1.0.vsix

Install Packaged Extension

1. In VS Code, press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)
2. Type Extensions: Install from VSIX...
3. Select the generated .vsix file

Publish to VS Code Marketplace

To publish to the VS Code Marketplace, you need:

1. Install vsce (if not installed):

   npm install -g @vscode/vsce
   

2. Create a publisher account (if you don't have one):

   • Visit https://marketplace.visualstudio.com/manage
   • Login with your Microsoft account
   • Create a new Publisher

3. Update the publisher field in package.json to your Publisher ID

4. Get a Personal Access Token:

   • Visit https://dev.azure.com
   • Create a new Personal Access Token (requires Marketplace permission)

5. Publish the extension:

   vsce publish
   

📄 PDF Export

Single File Export

• ✅ Smart Size Control: Mermaid diagrams maintain original size, only scale proportionally when width or height exceeds page limits
• ✅ WYSIWYG: PDF export matches preview mode display
• ✅ Page Break Optimization: Large diagrams can span pages, avoiding blank pages
• ✅ Theme Support: Supports light and dark theme export
• ✅ Icon Support: Architecture diagram icons (logos, mdi, carbon, fa) are correctly displayed in PDF exports

How to use:

• Press Ctrl+Shift+E (Windows/Linux) or Cmd+Shift+E (macOS)
• Or use Command Palette: "Export to PDF"

Batch Export

• ✅ Batch Processing: Automatically find and convert all Markdown files in a directory
• ✅ Progress Tracking: Real-time progress notification with file count
• ✅ Cancellable: Can cancel the export operation at any time
• ✅ Error Handling: Single file failure doesn't affect other files
• ✅ Statistics: Shows success and failure counts after completion

How to use:

1. Press Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (macOS)
2. Or use Command Palette: "Free Markdown View: Batch Export to PDF"
3. Select input directory (containing Markdown files)
4. Select output directory (for PDF files)
5. Configure PDF options (theme, page size, page numbers)
6. Start export

Features:

• Automatically finds all .md and .markdown files (including subdirectories)
• Excludes node_modules and .git directories
• Creates output directory if it doesn't exist
• Supports all PDF options (theme, page size, page numbers)

For detailed usage instructions, see docs/批量导出PDF使用说明.md.

Size Control Rules

• Small Diagrams: Maintain original size, not forced to stretch
• Large Diagrams: If width exceeds 750px or height exceeds 1000px, scale proportionally maintaining aspect ratio
• Extra Large Diagrams: When width exceeds 1500px, limit to container width

Testing

Run npm run test:pdf to automatically test PDF export functionality, checking:

• Whether Mermaid diagram sizes meet expectations
• Whether there are abnormal blank areas
• Whether PDF files are generated normally

📋 Requirements

• VS Code 1.57.0+
• Node.js (included in VS Code)

🐛 Known Issues

No known issues at the moment. If you encounter any problems, please report them in Issues.

📦 Release Notes

See CHANGELOG.md for version history.

📝 License

MIT License - see LICENSE file.

🤝 Contributing

Contributions welcome! Please submit Issues and Pull Requests.

🌐 Language Versions

• English (current)
• 中文 (Chinese)

Happy Markdown editing! 🎉