Why I Built a C# Markdown to/from HTML, and AmigaGuide to HTML Converter
Description: “A lightweight, safe and complete .md to .html, .html to .md, .txt to .html, .html to .txt, and .guide to .html converter built in C#, and why existing tools like Pandoc and Typora didn’t meet my needs.”
🚀 Introducing the Markdown to HTML Converter You Didn’t Think Was Possible
“If you’d told me a year ago that it’s possible to build a faster and fully standards-compliant Markdown-to-HTML converter than Pandoc—in a single C# file, with built-in XSS protection, working on both .NET Framework and .NET 7/8/9—I honestly wouldn’t have believed it myself. So I built it to prove it can be done.”
I’ve always admired tools like Pandoc for their power. But I wanted:
Blazing fast conversion speed, even for documents hundreds of pages long.
Smaller footprint, without pulling in hundreds of MB of dependencies.
Full compatibility across .NET Framework and modern .NET versions.
W3C-valid HTML output—no broken markup, no surprises.
Built-in security, to make sure no malicious Markdown can slip through and cause XSS vulnerabilities.
No external tools, no native binaries, no complex installs.
In my personal and professional work, I needed a reliable Markdown to HTML converter that could:
Be embedded in console, desktop, or web applications
Produce clean, W3C-valid HTML5
Offer full feature support, including task lists, footnotes, tables, TOC, etc.
Provide XSS protection out-of-the-box
Remain small, fast, and dependency-free
After trying several popular tools — Pandoc, Typora, VS Code Markdown preview — I ran into limitations I couldn’t accept.
🔍 Why Not Use Pandoc or Typora?
These tools are powerful. But they weren’t right for my needs:
Tool
Limitations
Pandoc
Heavy binary, slow execution, poor table rendering, no task lists
Typora
Lacks XSS protection, doesn’t support multi-line footnotes, inconsistent HTML
VS Code
Basic preview only, no customization
When you care about structure, safety, and full feature coverage, even powerful tools fall short.
As someone who needed a fast, embeddable Markdown to / from HTML converter in C#, I couldn’t find anything that met all of these goals:
✅ Small and dependency-free
✅ Fully supports advanced Markdown (TOC, footnotes, tables, tasks…)
✅ XSS-safe and robust for user input
✅ Easy to integrate into console, desktop, or web apps
So I built it.
Markdown to HTML Converter
✅ Markdown Supported Features
Headings (#, ##, ###, etc.)
Heading underlining (e.g., Heading\n=== for H1 or Heading\n--- for H2)
Basic text styles (bold, italic, strikethrough, ==highlighted==)
Subscript and superscript (e.g., H~2~O, E=mc^2^)
Multi-level ordered lists and unordered lists
Mixed nesting of ordered and unordered lists
Task lists (with checkbox states)
Blockquotes
Code blocks (code fences)
fenced code blocks (e.g., ```csharp)
indented code blocks (e.g., indented by 4 spaces or a tab)
Inline code
Horizontal rules
Links
Images
Tables
Column alignment (left / center / right)
Footnotes
Clickable references and backlinks
Multi-line footnote definitions
Inline styles supported inside footnotes
Raw HTML elements
Embedding arbitrary HTML tags inside Markdown
Self-closing tags (e.g. <br>)
Audio/video tags for media embedding
Front matter (YAML metadata block)
Supports title and custom meta tags for HTML <head>
Table of Contents (TOC) generation
Automatically collects all headings during parsing
Generates hierarchical TOC as nested lists
Optionally inserts TOC at [TOC] marker in the document
✅ The generated HTML code is valid according to W3C standards, verified through the W3C Validator.
🔐 Security Considerations
This converter includes built-in logic to detect and sanitize potentially dangerous HTML input:
Detects and blocks tags such as <script>, <iframe>, <object>, and other potentially unsafe HTML elements.
Blocks dangerous attributes like onerror, onclick, onload, etc.
Decodes and analyzes HTML entity encoding (e.g. j...) and URL encoding (e.g. %6a%61...) to prevent obfuscated XSS attacks.
Automatically inserts warnings for any detected issues, allowing users to fix Markdown syntax errors without breaking the conversion process.
No external libraries or HTML sanitizers are required — the security logic is fully self-contained.
🚨 Warnings for Syntax and Security Issues
The converter detects common Markdown syntax mistakes (e.g., unclosed bold, italic, ==highlight==, etc.).
It also scans the input for potential XSS and phishing vulnerabilities (e.g., embedded <script> tags or suspicious links).
Instead of halting the conversion, all issues are collected and displayed as a styled warning block appended to the end of the generated HTML.
Each warning includes the line number (and optionally the position) where the issue occurred.
Inline fallback styling is used to ensure visibility of warnings, even without custom CSS.
This feature improves robustness, especially for automated batch conversions or unverified input sources.
It’s ideal for batch-processing Markdown or handling user-submitted content.
HTML to Markdown Converter
✅ HTML Supported Features
Headings (<h1>–<h6>)
Basic text styles (<strong>, <em>, <del>, <mark>)
Subscript and superscript (e.g., <sub>, <sup>)
Span elements with class attributes (e.g., <span class="lang-en">)
Blockquotes
Ordered lists and unordered lists
Task lists (with checkbox states)
Links
Images with alt and title attributes (e.g., <img src="..." alt="..." title="...">)