DEV Community

Cover image for Why I Built a C# Markdown to/from HTML, and AmigaGuide to HTML/Markdown Converter
Miloš P.
Miloš P.

Posted on • Edited on • Originally published at milos-p-lab.github.io

Why I Built a C# Markdown to/from HTML, and AmigaGuide to HTML/Markdown Converter

#markdown #csharp #amigaguide #converter

Description: "A lightweight, safe and complete .md to .html, .html to .md, and .guide to .html converter built in C#, and why existing tools like Pandoc and Typora didn't meet my needs."

Markdown is great. HTML is everywhere. Turning one into the other should be easy, right?

Well — not always.

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^)
  • Blockquotes
  • Inline code and horizontal rules
  • Hyperlinks and images (with alt/title)
  • Multi-level ordered lists and unordered lists
  • Mixed nesting of ordered and unordered lists
  • Task lists (with checkbox states)
  • Tables with column alignment
  • Code blocks (with language hints)
  • Footnotes with multi-line support and backlinking
  • Raw HTML passthrough (audio, video, etc.)
  • YAML front-matter → meta tags
  • Automatic Table of Contents [TOC]
  • 🚨 Warnings for syntax and security issues (e.g., unclosed bold, italic, ==highlight==, etc.)
  • 🛡️ Built-in XSS protection with sanitization of dangerous content
  • 🚨 Warnings for security issues (e.g., embedded <script> tags or suspicious links)
  • ✅ 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. &#106;...) 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.

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="...">)
  • Tables
    • Pipe-style tables with alignment (e.g., | --- | :---: | ---: |)
  • Preformatted text blocks (e.g., <pre>...</pre>)
  • Code blocks with language highlighting (e.g., <pre><code class="language-csharp">...</code></pre>)
  • Front matter (YAML metadata block)
    • Supports title and custom meta tags for HTML <head>
  • 🚨 Warnings for syntax issues (e.g., improperly closed tags, unknown HTML entities, unexpected characters inside <pre> blocks)

AmigaGuide to HTML/Markdown Converter

✅ AmigaGuide Supported Features

  • Converts the most widely used AmigaGuide commands (rare or advanced commands may not be fully supported):
    • Nodes (@NODE, @ENDNODE, @TOC, @NEXT, @PREV)
    • Global commands (@DATABASE, @VER$, @(C), @TITLE, @AUTHOR)
    • Attribute commands (@{B}, @{I}, @{U}, @{PLAIN}, @{"Doc" LINK "doc.guide/intro"}, @{"Doc" SYSTEM "<command> doc.readme"})
    • For example, @{"Doc" LINK "doc.guide/intro"} creates a link to a node in another document (the LINK command specifies the target node or file), and @{"Doc" SYSTEM "<command> doc.readme"} opens documents with external commands (the SYSTEM command executes a system command, such as opening a file with an external viewer).
    • See AmigaGuide documentation for more details on these command forms.
  • Preserves the document’s structure for a retro feel
  • Generates clean HTML navigation buttons between nodes
  • Escapes special HTML characters to safely display content
  • 🚨 Warnings for syntax issues (e.g., improperly closed tags, repeated tags, unknown commands, link syntax errors, etc.)
  • ✅ The generated HTML code is valid according to W3C standards, verified through the W3C Validator.

Smart Plain Text to HTML Converter

✅ What It Does

  • Recognizes simple headings (e.g., Heading\n=== for H1 or Heading\n--- for H2) or uppercase headings (e.g., HEADING for H1 or HEADING for H2).
  • Converts bulleted lists (lines starting with -, *, or +)
  • Adds paragraph tags and basic inline formatting
  • Escapes unsafe characters (<, >, &) automatically
  • Outputs valid, minimal, styled HTML — ideal for fast previewing or lightweight rendering of plain notes
  • 🔐 It scans the input for potential XSS and phishing vulnerabilities (e.g., embedded <script> tags or suspicious links).

HTML to Plain Text Converter

  • Headings (e.g., Heading\n=== for H1 or Heading\n--- for H2)
  • Blockquotes
  • Ordered lists, unordered lists and task lists
  • Links
  • Tables
    • Pipe-style tables with alignment (e.g., | --- | :---: | ---: |)
  • 🚨 Warnings for syntax issues

Other Derived Conversions

  • Markdown to Plain Text
  • Smart Plain Text to Markdown
  • AmigaGuide to Markdown
  • AmigaGuide to Plain Text

⚡ One C# File. One Line to Use It

Instead of building a framework, I created a single-file class you can just drop into your project and use like this:

string html = ConvMarkdownHtml.Convert(markdown);
Enter fullscreen mode Exit fullscreen mode 
string markdown = ConvHtmlMarkdown.Convert(html);
Enter fullscreen mode Exit fullscreen mode 
string html = ConvGuideHtml.Convert(amigaGuide);
Enter fullscreen mode Exit fullscreen mode 
string html = ConvHtmlMarkdown.SmartTxtConvert(txt);
Enter fullscreen mode Exit fullscreen mode 
string txt = ConvHtmlMarkdown.ConvertToTxt(html);
Enter fullscreen mode Exit fullscreen mode

Done. No NuGet packages. No third-party libs. No surprises.

🌟 Additional Benefits

  • Fast conversion (e.g. a ~100-page book converts in just a few tens of milliseconds on a standard PC)
  • Compatible with both .NET Framework 4.x and .NET 7/8/9
  • Minimal footprint (just a few tens of KB)
  • Supports custom CSS themes for beautiful HTML rendering
  • No dependencies on external DLLs or tools like Pandoc
  • 🛡️ Built-in XSS protection — automatically detects dangerous tags, attributes, and obfuscated payloads for safer HTML output

🧠 Design Philosophy

One C# file. One method.

  • ⚡ No runtime dependencies
  • 🛡️ Safety and standards-compliance by default
  • 🔧 Easy to read, fork, modify, extend

📦 Try It or Fork It

🔹 Just want to test it? Download the mdoc.exe and run:

mdoc input.md output.html
mdoc input.md output.txt
mdoc input.html output.md
mdoc input.html output.txt
mdoc input.txt output.html
mdoc input.txt output.md
mdoc input.guide output.html
mdoc input.guide output.md
mdoc input.guide output.txt
Enter fullscreen mode Exit fullscreen mode

🔹 Want to embed or extend it? Just copy the .cs file into your project and you're done.

👉 GitHub: milos-p-lab/MarkdownGuideHtmlConverter

If you're tired of bloated or unsafe Markdown tools — try this minimalist approach. I built it for me, but maybe it's exactly what you need too.

✍️ Author: Miloš Perunović

Top comments (0)