Stop Reading HTML Like a Caveman: md-browse Exposes the Web's Hidden Markdown Layer

What if everything you've been told about browsing the web was backwards? For thirty years, we've accepted HTML—bloated, tracked, ad-saturated HTML—as the default lens for consuming online content. We install ad blockers, reader modes, and distraction-free extensions, desperately trying to strip away the noise that shouldn't exist in the first place. But what if you could bypass this entire mess and see the web as clean, structured, readable markdown—the same way AI systems like Claude and Copilot already do?

Enter md-browse, the radical markdown-first browser that flips the script on web consumption. Built by the innovative team at Needle Tools using the lightning-fast Electrobun framework, this isn't just another browser—it's a paradigm shift. While traditional browsers beg servers for HTML and then struggle to make it readable, md-browse leads with Accept: text/markdown headers and transforms everything else into pristine markdown automatically. The result? A browsing experience that's faster, cleaner, and eerily similar to how large language models "see" the web.

If you're tired of fighting websites just to read their content, this tool will feel like discovering a secret passage that's been hiding in plain sight. Let's dive into why developers are already calling this the most interesting browser experiment of 2026.

What is md-browse? The Browser AI Doesn't Want You to Know About

md-browse is an experimental desktop browser built with Electrobun, a cutting-edge framework that combines Bun's blazing JavaScript runtime with native webview capabilities. Created by Needle Tools—known for their innovative work in 3D web technologies and developer tooling—this browser represents a fundamentally different philosophy about how humans should interact with web content.

The project's tagline says it all: "See the web like an AI does." While that might sound like marketing fluff, it's technically precise. Modern AI systems don't "render" web pages in any traditional sense. When Claude, ChatGPT, or GitHub Copilot fetch web content, they convert everything to clean markdown—stripping scripts, styles, navigation chrome, and tracking pixels—to focus purely on semantic content. md-browse applies this same pipeline to your everyday browsing, giving you the same distilled, distraction-free view that powers AI comprehension.

Why is this trending now? Three converging forces make md-browse's timing perfect:

• AI-native workflows are exploding: Developers increasingly think in markdown—it's the lingua franca of LLM interactions, documentation, and note-taking apps
• The web obesity crisis: Average web pages now exceed 2.5MB of bloat, with most bytes serving ads, trackers, and unnecessary JavaScript
• Electrobun's emergence: Bun's incredible performance (4x faster than Node.js) finally makes alternative browser architectures practical

Unlike reader modes that bolt onto existing browsers as afterthoughts, md-browse is architected from the ground up around markdown as the primary content format. HTML becomes the fallback, not the default. This inversion unlocks capabilities that traditional browsers simply cannot match.

Key Features: The Technical Secrets Behind md-browse's Magic

md-browse isn't a stripped-down toy—it's a fully functional browser with sophisticated features that reveal deep technical craft:

Markdown-First Content Negotiation

The browser's opening move is revolutionary. Every request leads with:

Accept: text/markdown, text/html;q=0.9

This header tells servers: "Give me markdown if you have it; I'll tolerate HTML as a last resort." Progressive platforms like Vercel's documentation already serve native markdown when asked politely. This isn't theoretical—it's a real, working content negotiation strategy that more servers should implement.

AI-Matched HTML-to-Markdown Conversion

When servers respond with HTML (which is still most of them), md-browse doesn't give up. It pipes content through Turndown, the gold-standard HTML-to-Markdown converter, with carefully tuned settings designed to match exactly what major AI platforms produce. The conversion pipeline:

• Aggressively strips noise: Scripts, stylesheets, navigation bars, footers, and advertisement containers vanish
• Intelligently extracts content: Prioritizes <main> and <article> semantic tags, falling back to heuristic content detection
• Preserves structure: Headings, links, lists, code blocks, tables, and emphasis convert cleanly
• Maintains readability: Output mirrors the markdown training data that LLMs consume

Dual View Architecture

Flexibility matters. md-browse provides instantaneous toggling between:

• Raw Markdown View: See the underlying structure—perfect for developers, writers, and AI prompt engineers who need clean copy-paste sources
• Rendered Preview: Comfortable reading with proper typography, syntax highlighting, and formatted elements

This dual-mode approach serves multiple personas without compromise.

Full Browser Fundamentals

Despite its experimental nature, md-browse ships with production-grade essentials:

• Multi-tab browsing with complete navigation history
• Back/forward/reload controls that actually work
• URL bar with standard web navigation
• Dark, modern UI optimized for extended reading sessions
• Native macOS application packaging (Windows builds in progress)

Use Cases: Where md-browse Absolutely Destroys Traditional Browsers

1. Technical Documentation Deep Dives

You're researching a new framework at 2 AM. Traditional browsers bombard you with cookie banners, newsletter popups, and "Was this helpful?" widgets. md-browse serves clean markdown—just the facts, structured perfectly for your notes or AI prompts. Copy a section? It's already in the format your knowledge base expects.

2. AI-Assisted Research Workflows

Building RAG pipelines or training data sets? md-browse becomes your human-in-the-loop validation tool. See exactly what your scrapers and LLMs will receive. Verify that conversion quality matches expectations before committing to pipeline architectures. It's the missing debugger for web-to-AI data flows.

3. Content Creation and Curation

Bloggers, newsletter writers, and documentation maintainers constantly harvest web references. Instead of fighting HTML paste disasters in your markdown editor, md-browse gives you source-ready content. That Stack Overflow answer, that API reference, that research paper—immediately usable in your static site generator or Obsidian vault.

4. Accessibility-First Browsing

Screen reader users and those with visual processing differences often struggle with inconsistently structured HTML. Markdown's rigid, predictable hierarchy—one # for main title, ## for sections, clean lists and links—provides superior navigability. md-browse essentially enforces structural best practices across the entire web.

5. Focus-Driven Reading on Slow Connections

Traveling with spotty WiFi? md-browse's stripped content transfers faster and renders instantly. No waiting for seventeen analytics scripts to timeout. The markdown-first approach is inherently bandwidth-efficient, making it ideal for constrained environments.

Step-by-Step Installation & Setup Guide

Ready to experience the web differently? Getting md-browse running takes under five minutes if you meet the prerequisites.

Prerequisites

Installing Bun (if you haven't already):

# macOS/Linux via official installer
curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version
# Expected: 1.1.x or higher

Clone and Setup

# Clone the repository
git clone https://github.com/needle-tools/md-browse.git

# Enter project directory
cd md-browse

# Install all dependencies (Bun handles this blazingly fast)
bun install

The bun install command resolves Electrobun's native dependencies, Svelte compilation toolchain, and Turndown conversion libraries. Expect completion in 10-30 seconds depending on your connection—Bun's package management is genuinely that fast.

Development Mode

# Launch with hot-reload for development
bun run start

This spawns the Electrobun runtime with your local source, enabling rapid iteration. The main Bun process initializes, compiles the Svelte toolbar components, and presents the native application window.

Production Builds

# Build for current platform (macOS)
bun run build

# Cross-compile for Windows x64
bun run build:stable:win

Build artifacts appear in platform-specific directories, ready for distribution or local installation. Note that Windows builds require appropriate cross-compilation toolchains configured in your environment.

REAL Code Examples: Inside md-browse's Architecture

Let's examine actual implementation patterns from the repository, with detailed commentary on how this browser achieves its markdown magic.

Example 1: The Core Fetch Logic with Markdown Priority

The heart of md-browse lives in src/bun/index.ts, where the main process orchestrates all network requests. Here's the conceptual pattern driving every page load:

// src/bun/index.ts - Main process HTTP handling
async function fetchWithMarkdownPriority(url: string): Promise<string> {
  // CRITICAL: Lead with text/markdown in Accept header
  // This is the magic that makes servers reveal their markdown
  const response = await fetch(url, {
    headers: {
      'Accept': 'text/markdown, text/html;q=0.9, */*;q=0.8'
      // ^^^ markdown first, HTML with reduced priority, anything else last resort
    }
  });

  const contentType = response.headers.get('content-type') || '';
  
  // Direct markdown response? Return immediately, zero conversion needed
  if (contentType.includes('text/markdown')) {
    return await response.text();
  }
  
  // HTML received? Transform through Turndown pipeline
  if (contentType.includes('text/html')) {
    const html = await response.text();
    return convertHtmlToMarkdown(html); // See Example 2
  }
  
  // Fallback for unexpected content types
  return await response.text();
}

What's happening here? This function embodies md-browse's entire philosophy. The Accept header uses quality values (q=0.9, q=0.8) to formally express preference ordering—HTTP content negotiation done correctly. When Vercel's docs or any markdown-aware server sees this header, it can serve its native .md source directly. The response path branches cleanly: fast path for markdown, conversion path for HTML.

Example 2: Turndown Configuration Matching AI Patterns

The HTML-to-markdown conversion isn't generic—it's precisely tuned to match AI system behavior:

// src/bun/index.ts - Turndown instance with AI-matching configuration
import TurndownService from 'turndown';

const turndownService = new TurndownService({
  headingStyle: 'atx',        // Use # format, not underlines
  hr: '---',                  // Standard horizontal rule
  bulletListMarker: '-',      // Consistent with most AI training data
  codeBlockStyle: 'fenced',   // ``` for code, not indented
  fence: '```',               // Backtick fences everywhere
  emDelimiter: '_',           // Underscore for emphasis
  strongDelimiter: '**',      // Double asterisk for bold
  linkStyle: 'inlined',       // [text](url) format
  linkReferenceStyle: 'full', // Complete references, not collapsed
});

// CRITICAL: Strip elements that AI systems universally ignore
turndownService.remove([
  'script',      // JavaScript execution context - irrelevant to content
  'style',       // CSS presentation - meaningless semantically  
  'nav',         // Site navigation - repeated noise across pages
  'footer',      // Legal boilerplate - rarely relevant
  'header',      // Banner navigation - same as nav
  'aside',       // Sidebars, ads, tangential content
  '.advertisement',
  '.social-share',
  '#cookie-banner'
]);

function convertHtmlToMarkdown(html: string): string {
  // Extract primary content before conversion
  // AIs focus on main/article; so do we
  const mainContent = extractMainContent(html);
  
  return turndownService.turndown(mainContent);
}

function extractMainContent(html: string): string {
  // Priority: <main> tag, then <article>, then heuristic body extraction
  // This matches how AI scrapers identify substantive content
  const mainMatch = html.match(/<main[^>]*>([\s\S]*?)<\/main>/i);
  if (mainMatch) return mainMatch[1];
  
  const articleMatch = html.match(/<article[^>]*>([\s\S]*?)<\/article>/i);
  if (articleMatch) return articleMatch[1];
  
  // Fallback: strip known noise containers, return remainder
  return html.replace(/<(nav|footer|aside|header)[^>]*>[\s\S]*?<\/\1>/gi, '');
}

Why this configuration matters: Every setting choice reflects analysis of how major AI systems process web content. The atx heading style, fenced code blocks, and specific delimiter choices maximize compatibility with LLM training corpora. The aggressive element stripping isn't destruction—it's distillation, removing the 80% of HTML that carries zero semantic value.

Example 3: Svelte Toolbar with View Mode Toggle

The UI layer in src/toolbar-svelte/ handles user interaction. The markdown/preview toggle demonstrates clean reactive state management:

<!-- Conceptual structure from src/toolbar-svelte/ components -->
<script>
  // Reactive state: 'markdown' | 'preview'
  let viewMode = $state('markdown');
  
  // Derived: which content to display
  let displayContent = $derived(
    viewMode === 'markdown' 
      ? rawMarkdown           // Show Turndown output directly
      : renderedHtml          // Pass through markdown-it or similar
  );
  
  function toggleView() {
    viewMode = viewMode === 'markdown' ? 'preview' : 'markdown';
    // Signal main process to update webview content
    window.electrobun?.rpc?.invoke('setViewMode', viewMode);
  }
</script>

<div class="toolbar">
  <!-- Navigation controls -->
  <button onclick={goBack}>←</button>
  <button onclick={goForward}>→</button>
  <button onclick={reload}>↻</button>
  
  <!-- URL input with markdown indicator -->
  <input 
    type="text" 
    bind:value={currentUrl}
    placeholder="Enter URL (requests markdown first)..."
    onkeydown={(e) => e.key === 'Enter' && navigate(currentUrl)}
  />
  
  <!-- THE TOGGLE: Instant mode switching -->
  <div class="view-toggle">
    <button 
      class:active={viewMode === 'markdown'}
      onclick={() => viewMode = 'markdown'}
    >
      Markdown
    </button>
    <button 
      class:active={viewMode === 'preview'}
      onclick={() => viewMode = 'preview'}
    >
      Preview
    </button>
  </div>
</div>

<div class="content" class:raw={viewMode === 'markdown'}>
  {#if viewMode === 'markdown'}
    <pre><code>{displayContent}</code></pre>
  {:else}
    <div class="rendered">{@html displayContent}</div>
  {/if}
</div>

The architectural insight: This Svelte component compiles to vanilla JavaScript that runs in the native webview, communicating with the Bun main process via Electrobun's RPC bridge. The $state and $derived runes provide fine-grained reactivity without virtual DOM overhead. The toggle isn't merely cosmetic—it switches between two entirely different rendering pipelines while preserving scroll position and context.

Advanced Usage & Best Practices

Custom Turndown Rules

Extend md-browse for your specific needs by adding Turndown rules before the service initializes:

// Add custom handling for your internal documentation platform
turndownService.addRule('customCallout', {
  filter: (node) => node.matches('.callout, .admonition'),
  replacement: (content, node) => {
    const type = node.getAttribute('data-type') || 'note';
    return `> **${type.toUpperCase()}**\n> ${content.replace(/\n/g, '\n> ')}\n\n`;
  }
});

Server-Side Markdown Enablement

If you control web properties, respond to md-browse's headers natively:

// Express.js example
app.get('/docs/:page', (req, res) => {
  if (req.accepts('text/markdown')) {
    res.type('text/markdown');
    res.sendFile(`./content/${req.params.page}.md`);
  } else {
    res.render('doc-template', { page: req.params.page });
  }
});

Performance Optimization

For heavy research sessions, md-browse's minimal resource footprint shines. The Bun process typically consumes under 100MB RAM versus 500MB+ per Chromium tab. Run multiple instances for parallel research without system strain.

Comparison with Alternatives

The verdict: Reader modes are band-aids on broken defaults. Terminal browsers sacrifice modern web compatibility. CLI tools require manual orchestration. md-browse is the only solution architected around markdown as first-class citizen with full browsing capabilities intact.

FAQ: Your Burning Questions Answered

Does md-browse break JavaScript-heavy web applications?

md-browse prioritizes content pages—documentation, articles, references. Dynamic SPAs expecting rich interactivity may lose functionality in markdown view. Use traditional browsers for application interfaces; use md-browse for information consumption.

Can I use md-browse as my only browser?

Not yet, unless your workflow is exclusively content reading. Banking, video streaming, web-based IDEs, and complex dashboards still need conventional browsers. Think of md-browse as a specialized instrument in your toolkit, not a complete replacement.

How does this differ from "reader mode" extensions?

Reader modes are post-processing afterthoughts—they request HTML, render everything, then attempt surgical removal. md-browse prevents the disease rather than treating symptoms, requesting clean content from the start and converting with AI-tested precision.

Is Windows or Linux support coming?

The build:stable:win script indicates active Windows development. Linux builds depend on Electrobun's platform expansion. macOS is the current primary target due to native development toolchain maturity.

Can websites block md-browse's markdown requests?

Any server can ignore Accept headers, but there's no technical reason to do so. Serving markdown when explicitly requested reduces server load (no template rendering) and improves client experience. Ethical sites should embrace this pattern.

How accurate is the Turndown conversion versus actual AI processing?

Needle Tools tuned settings against observed outputs from major LLM providers. While exact matching varies by page complexity, the structural patterns—heading hierarchies, code block handling, link formatting—closely parallel production AI pipelines.

Is my browsing data tracked or sent to external services?

md-browse is fully open source with no telemetry. All conversion happens locally in your Bun process. Review src/bun/index.ts to verify—transparency is complete.

Conclusion: The Web Has a Markdown Layer—Start Using It

We've accepted HTML's tyranny for too long. Every ad impression, every tracking pixel, every megabyte of JavaScript framework bloat—we've normalized it all because we forgot to ask for something better. md-browse proves that asking works. When you lead with Accept: text/markdown, the web reveals a cleaner, faster, more comprehensible version of itself.

This isn't nostalgia for a simpler internet. It's a technically sophisticated, AI-informed approach to information consumption that happens to feel like relief. The same transformation pipeline that makes large language models effective makes human reading more productive too.

The team at Needle Tools has built something genuinely experimental yet immediately usable. Whether you're researching, writing, training models, or simply exhausted by modern web excess, md-browse offers a portal to a better experience.

Your next step is simple: Clone github.com/needle-tools/md-browse, run bun install && bun run start, and load your favorite documentation site. Watch it appear as clean markdown for the first time. Feel the difference. Then ask yourself why every browser doesn't work this way—and join the movement to make that future real.

The markdown web is already here. md-browse is just the first browser brave enough to prioritize it.