A lightweight, terminal-driven Markdown preview tool

agile and swift like a finch

简体中文 | English

📖 Introduction

Finch is a lightweight, terminal-driven Markdown preview tool that allows developers to preview Markdown files in their browser with a single command.

Why Finch?

| Problem | Finch Solution | |---------|----------------| | Heavy Markdown editors (Typora, Obsidian) require opening a separate application | One command finch file.md opens preview in browser | | Complex setup and configuration | Zero configuration, works out of the box | | Disrupted terminal workflow | Stay in terminal, preview instantly | | Missing diagram support | Built-in Mermaid & PlantUML rendering |

✨ Features

• 🚀 One-Command Preview — finch file.md opens your Markdown in the browser
• 🎨 Rich Syntax Support — Tables, code highlighting, math formulas, diagrams
• 📦 Zero Configuration — Works out of the box, no setup required
• ⚡ Fast & Lightweight — Minimal dependencies, instant startup
• 🔗 Local Asset Support — Relative image paths work automatically
• 📊 Diagram Rendering — Mermaid & PlantUML support (flowcharts, sequence diagrams, class diagrams, etc.)
• 🔌 Auto Port Selection — Automatically finds available port, no conflicts

📦 Installation

npm (Recommended)

npm install -g finch-md

Requirements

• Node.js >= 16.0.0
• npm or yarn

Verify Installation

finch --version

Upgrade

npm update -g finch-md

Uninstall

npm uninstall -g finch-md

🚀 Quick Start

# Preview any Markdown file (auto-selects available port)
finch README.md

# File names with spaces (wrap in quotes)
finch "my file.md"
finch "document with spaces.md"

# Specify a port (optional)
finch -p 3001 document.md

# View help
finch --help

📝 Supported Features

Basic Markdown

| Feature | Syntax | Example | |---------|--------|---------| | Code Blocks | ```js ... ``` | JavaScript, Python, Go, etc. | | Syntax Highlighting | Auto-detects language | Powered by highlight.js | | Tables | \| col \| col \| | Standard GFM tables | | Math Formulas | $...$, $$...$$ | KaTeX rendering | | Task Lists | - [ ], - [x] | GitHub-style checkboxes | | Images | ![alt](path.png) | Local & remote URLs |

Diagrams

| Diagram Type | Mermaid | PlantUML | |--------------|---------|----------| | Flowchart | ✅ | ✅ | | Sequence Diagram | ✅ | ✅ | | Class Diagram | ✅ | ✅ | | State Diagram | ✅ | ✅ | | Use Case Diagram | ⏸️ | ✅ | | Activity Diagram | ✅ | ✅ |

💡 Examples

Code Highlighting

```javascript
const greeting = "Hello, Finch!";
console.log(greeting);
```

```python
def hello():
    print("Hello from Python!")
```

Math Formulas

Inline: $E = mc^2$

Display:
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Mermaid Flowchart

```mermaid
graph TD
    A[User] --> B[finch command]
    B --> C[Start Server]
    C --> D[Open Browser]
    D --> E[Preview Markdown]
```

Mermaid Sequence Diagram

```mermaid
sequenceDiagram
    participant User as User
    participant CLI as Finch
    participant Server as Server
    participant Browser as Browser

    User->>CLI: finch doc.md
    CLI->>Server: Start server
    Server->>Browser: Open localhost
    Browser->>Server: GET /
    Server->>Browser: Return HTML
    Browser->>User: Show preview
```

PlantUML Sequence Diagram

```plantuml
@startuml
User -> CLI: finch doc.md
CLI -> Server: Start server
Server --> CLI: Server started
CLI -> Browser: Open browser
Browser -> Server: GET /
Server --> Browser: Return HTML
Browser --> User: Show preview
@enduml
```

PlantUML Use Case Diagram

```plantuml
@startuml
left to right direction
actor "User" as User
rectangle "Finch" {
  User --> (Preview Markdown)
  User --> (Specify Port)
  User --> (View Help)
}
@enduml
```

Tables & Task Lists

| Feature | Status | Priority |
|---------|--------|----------|
| Code Highlight | ✅ | P0 |
| Tables | ✅ | P0 |

- [x] Install Finch
- [x] Preview Markdown
- [ ] Build amazing docs

🏗️ Technical Architecture

Stack

| Component | Technology | |-----------|------------| | Runtime | Node.js | | CLI Framework | commander.js | | Web Server | Express.js | | Markdown Parser | markdown-it | | Syntax Highlighting | highlight.js | | Math Rendering | KaTeX | | Diagram Rendering | Mermaid.js + PlantUML (online) | | Browser Launch | open |

Architecture Diagram

graph LR
    A[User Command] --> B[CLI Parser]
    B --> C[Read Markdown File]
    C --> D[Markdown Renderer]
    D --> E[HTML Template]
    E --> F[Express Server]
    F --> G[Open Browser]
    G --> H[Display Preview]

How It Works

1. CLI parses the file path and options
2. Server starts a local HTTP server on 127.0.0.1 (auto-selects available port)
3. Renderer converts Markdown to HTML with syntax highlighting, math formulas, and diagrams
4. Browser opens automatically to display the preview
5. Static assets (images, etc.) are served from the Markdown file's directory

📖 Commands

| Command | Description | |---------|-------------| | finch <file> | Preview a Markdown file | | finch -p, --port <port> | Specify server port (default: auto-select) | | finch -h, --help | Display help | | finch -v, --version | Display version |

🛠️ Development

# Clone the repository
git clone <repository-url>

# Install dependencies
cd finch && npm install

# Link globally for development
npm link

# Test
finch test.md

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🙏 Acknowledgments

Finch is built with these amazing open-source projects:

• markdown-it - Markdown parser
• highlight.js - Syntax highlighting
• KaTeX - Math typesetting
• Mermaid - Diagrams
• PlantUML - Diagram rendering (online service)
• Express - Web server
• commander - CLI framework