View the Live Demo
Check Repository
md-viewer: A Modern Markdown Renderer with Mermaid and Math Support
Markdown has become the standard format for documentation, README files, technical blogs, and knowledge sharing. However, most simple Markdown viewers only render text and basic formatting. They often lack support for diagrams, mathematical equations, advanced code blocks, and clean UI presentation.
To solve this, I built md-viewer — a modern, lightweight Markdown rendering application designed to support not only standard Markdown, but also Mermaid diagrams, mathematical expressions, syntax highlighting, and a polished reading experience.
In this article, I will walk through the motivation, architecture, core features, and technical decisions behind the project.
Why Build Another Markdown Viewer?
Most Markdown renderers handle headings, lists, tables, and code blocks. But in real-world development workflows, we often need more:
- Technical diagrams for system design
- Mathematical equations for academic content
- Clean syntax highlighting for code
- Consistent styling for documentation
- A distraction-free reading interface
When working on documentation-heavy projects, I wanted a viewer that could render:
- Complex Mermaid diagrams
- LaTeX-style math equations
- Beautifully highlighted code blocks
- Responsive layout
- Clean, modern UI
That requirement led to the development of md-viewer.
Core Features
1. Full Markdown Rendering
The application supports standard GitHub-flavored Markdown, including:
- Headings
- Lists
- Tables
- Blockquotes
- Inline formatting
- Code blocks
It ensures compatibility with typical README files and technical documentation.
2. Syntax Highlighting for Code Blocks
Code readability is essential for developers. The viewer integrates syntax highlighting for multiple programming languages, ensuring:
- Clean formatting
- Proper indentation rendering
- Visual distinction between tokens
This makes it suitable for viewing documentation, tutorials, and code-heavy articles.
3. Mermaid Diagram Support
Modern documentation frequently includes architecture and flow diagrams. The viewer supports Mermaid, enabling rendering of:
- Flowcharts
- Sequence diagrams
- Class diagrams
- State diagrams
- Gantt charts
This feature makes the tool especially useful for system design documentation and technical blogs.
4. Mathematical Expression Rendering
Technical and academic documentation often includes mathematical formulas. The project integrates math rendering support, allowing LaTeX-style equations to be displayed properly.
This is particularly useful for:
- Algorithm explanations
- Research documentation
- Educational material
5. Clean, Minimal Interface
The UI is intentionally designed to be:
- Minimal
- Readable
- Responsive
- Distraction-free
The focus is on content presentation rather than UI complexity.
Technical Architecture
The project is structured with modular rendering logic to ensure maintainability and extensibility.
Rendering Pipeline
The typical flow follows:
- Load raw Markdown content
- Parse Markdown into HTML
- Process extended features (Mermaid, Math)
- Apply syntax highlighting
- Render into the DOM
By separating parsing, transformation, and rendering, the architecture remains clean and easy to scale.
Extensibility
The viewer is designed in a way that additional plugins or enhancements can be added without rewriting the core logic.
Possible future enhancements include:
- Theme switching (dark/light mode)
- Export to PDF
- Live editing mode
- File upload support
Design Decisions
While building this project, I focused on:
Simplicity Over Complexity
Instead of creating a full-fledged Markdown editor, the goal was to create a powerful renderer that focuses purely on display quality.
Developer-Centric Features
Support for diagrams and math was prioritized because these are often missing in simple viewers but are essential in real-world documentation.
Performance and Clean Code
The codebase emphasizes clarity and modularity. Each rendering concern is handled separately to avoid tightly coupled logic.
Use Cases
The project can be used for:
- Viewing README files locally
- Rendering technical documentation
- Previewing academic notes
- Sharing system design diagrams
- Demonstrating algorithm explanations with math
It is particularly helpful for students, developers, and technical writers who rely heavily on Markdown.
Lessons Learned
Building this project reinforced several important engineering principles:
- Rendering pipelines must be modular
- Documentation tools should prioritize readability
- Supporting diagrams significantly improves documentation clarity
- Clean UI enhances user experience more than complex UI
Conclusion
md-viewer is a focused solution for developers who need more than just basic Markdown rendering. By combining standard Markdown, syntax highlighting, Mermaid diagrams, and mathematical equation support, it provides a powerful yet minimal documentation viewer.
If you work with technical documentation frequently, this project may serve as a useful foundation or inspiration for your own documentation tools.
If you found this useful, feel free to explore the repository and suggest improvements. Contributions and feedback are always welcome.
Top comments (2)
Nice project! For focused Mermaid editing I've been using webtoolz.dev/mermaid — the shareable SVG URLs are really handy for embedding diagrams in docs and READMEs.
Thank You Kai ❤️
Btw you can also use " mermaid.live " but webtoolz is also a very great option