mkdnsite: Dual-Channel Markdown Publishing for Humans and AI

The Problem: AI Crawlers Can't Read Your Website

In 2026, a growing share of your traffic comes from AI agents — Google AI Overview, ChatGPT, Perplexity, Claude, and Gemini all crawl the web to answer user queries. But there is a mismatch: your beautifully designed HTML site is full of navigation menus, sidebars, ad slots, and JavaScript that these crawlers have to parse through to find the actual content.

AI crawlers prefer clean, structured Markdown. They can extract meaning from a well-structured Markdown document far more accurately than from a rendered HTML page with dozens of DOM nodes per paragraph. The problem is that most publishing tools force you to choose: HTML for humans OR plain text for machines, but not both.

Enter mkdnsite — an open-source tool that solves this by serving both from a single Markdown source file.

What Is mkdnsite?

mkdnsite is a lightweight, zero-build Markdown site generator that detects who is visiting and serves the right format:

• Human readers get a clean, styled HTML page — rendered on-the-fly from Markdown with minimal layout overhead.
• AI crawlers (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, and others) get the raw Markdown source — the same content, zero decoration, maximum signal.

This dual-channel approach means you write your content once in Markdown, and both audiences get what they need. No duplicate content, no separate AI-friendly versions, no complex build pipelines.

Key differentiator: Unlike traditional static site generators that pre-build HTML, mkdnsite renders dynamically based on the User-Agent header. The same URL serves different content types depending on who requests it.

How It Works

mkdnsite is a single Go binary with no dependencies. You run it in your project directory and it serves your .md files as both HTML and Markdown:

$ mkdnsite
  Serving /blog on port 8080
  AI crawlers get .md, humans get .html

Create a Markdown file like blog/my-post.md and it is instantly available at:

https://yoursite.com/blog/my-post    # Humans: styled HTML
  https://yoursite.com/blog/my-post.md # AI crawlers: raw Markdown

No npm install, no build step, no deploy pipeline. Write a Markdown file, save it, refresh — done.

Why Dual-Channel Matters for Content Creators

If you are a writer, blogger, or content creator publishing Markdown-driven content, here is why the dual-channel approach matters:

Publishing platforms like LinkedIn and X Articles do not consume raw Markdown or HTML directly. They accept rich text (formatted text with headings, bold, lists). This is where the publishing pipeline splits again — and where md2rich fills the gap.

The Complete Publishing Pipeline

Here is how the three tools work together for a complete Markdown-to-publication workflow:

1. Write in Markdown — Use any editor (Obsidian, VS Code, iA Writer) to create your content in plain Markdown.
2. Serve with mkdnsite — Deploy your Markdown files via mkdnsite. Humans see a clean blog. AI crawlers get the raw Markdown for better AI search visibility.
3. Publish to social with md2rich — For LinkedIn posts, X Articles, Medium, or Notion: copy the Markdown source, paste into md2rich.com, and copy the formatted rich text to your target platform.

mkdnsite vs Traditional Static Site Generators

mkdnsite is not a replacement for full-featured SSGs. If you need a complex theme, pagination, taxonomies, or multilingual sites, Hugo or Astro are better choices. But if you want a zero-friction Markdown blog that serves AI crawlers natively, mkdnsite is the most elegant solution available in 2026.

Real-World Scenario: From Markdown to LinkedIn in 60 Seconds

Here is a complete walkthrough of the dual-channel publishing pipeline:

1. Write: Draft a 500-word article on Markdown productivity tips in Obsidian.
2. Publish to site: Save the .md file to your mkdnsite-served blog folder. mkdnsite immediately serves it as HTML for visitors and Markdown for AI crawlers.
3. Publish to LinkedIn: Open the same Markdown file, paste it into md2rich.com, click convert, copy the rich text, and paste into LinkedIn. Your headings, bold, and lists transfer perfectly.

# Markdown Productivity Tips

## Use Templates
Save reusable headers in a templates folder.

## Keyboard Shortcuts
- **Bold:** Ctrl+B
- **Italic:** Ctrl+I
- **Heading:** Ctrl+Shift+H

Limitations to Consider

mkdnsite is not the right tool for every scenario. Here is what to keep in mind:

• No theming engine. The HTML output is deliberately minimal. If you need a custom design, you will have to write your own template or serve the Markdown through a different frontend.
• User-agent detection is not perfect. Some AI crawlers use generic user agents that mkdnsite may not recognize. The detection list is community-maintained and needs regular updates.
• Not for complex sites. If you need tags, categories, search, or analytics integration, traditional SSGs are still the better choice.
• Server required. Unlike static HTML that can be served from any CDN, mkdnsite is a running server that needs to be deployed on a VPS or cloud instance.

FAQ

Conclusion

As AI-driven search becomes the primary way people discover content, the way we publish needs to evolve. Serving clean Markdown to AI crawlers is no longer optional — it directly affects how accurately your content is cited in AI-generated answers.

mkdnsite solves this elegantly for Markdown-first publishers. Combined with md2rich for social publishing, you get a complete pipeline:

• Write once in Markdown
• Serve your blog with mkdnsite (HTML for humans + Markdown for AI)
• Publish to LinkedIn, X Articles, or Medium with md2rich

Give mkdnsite a try on GitHub, and when you are ready to publish your Markdown content to social platforms, md2rich is here to help.