MaraudersMapMD

Ultra-fast Markdown preview with AI-native readability artifacts, PDF export, and document history for VS Code

Why? · Features · Quick Start · AI / GEO · Commands · Settings · FAQ · llms.txt · llms-full.txt

Why MaraudersMapMD?

Modern development increasingly relies on AI assistants (Cursor, Claude, Copilot) that consume Markdown documentation. But AI has token limits — it can't read your entire 500-page PRD at once.

MaraudersMapMD solves this by generating AI-native artifacts that help LLMs understand large documents within token budgets:

Plus: blazing-fast preview, PDF/HTML export, document history with diff/restore — all in one lightweight extension.

Vendor-neutral: MaraudersMapMD does NOT call any AI API. It generates file-based artifacts (docs/MaraudersMap/ directory) that ANY AI tool can read.

Features

Ultra-Fast Markdown Preview

• Instant rendering with configurable debounce (default 200ms)
• Scroll sync between editor and preview
• Task list support with interactive checkbox toggle
• Large document optimization with adaptive delay
• Source line injection for accurate rendering

AI Readability & GEO Support

GEO (Generative Engine Optimization): Optimizing content for AI-powered search engines and LLM consumption.

• AI Map (ai-map.md): Structure table with heading hierarchy, line ranges, and token estimates — lets AI understand your document without reading it entirely
• Section Pack (sections/*.md): Heading-based document splits for precise LLM consumption
• Search Index (index.json): Keywords, links, and AI hint extraction per section
• AI Hint Blocks: Insert semantic markers (RULE, DECISION, NOTE) that AI agents prioritize
• Rewrite Prompt: One-click prompt generation for AI-powered readability rewriting (skill)
• Build on Save: Automatic AI artifact generation to docs/MaraudersMap/ directory
• llms.txt & llms-full.txt: Standard AI documentation files for Generative Engine Optimization

Quick Edit Commands

• Format: Bold (**), Italic (*), Inline Code (`)
• Insert: Link, Heading, Blockquote
• Toggle: Task checkbox in both editor and preview

Image Workflow

• Insert from file with automatic assets/ directory management
• Editor-side drag-and-drop support
• Clipboard paste to assets
• Configurable filename patterns and alt text sources

PDF & HTML Export

• PDF: Export via system Chrome/Chromium (auto-detected, no bundled browser)
• HTML: Standalone export with local image embedding
• Configurable margins, paper format (A4/Letter/A3/A5), and background printing
• Graceful fallback: if Chrome not found, guides to HTML print-to-PDF

Document History & Snapshots

• Automatic snapshots on save (configurable: onSave, interval, manual)
• Manual checkpoints with labels
• Visual diff viewer and one-click restore
• Configurable retention (days, max snapshots, storage limits)
• gzip compression for efficient storage
• Pre-restore safety snapshots (never lose data)

Quick Start

Install from VSIX

# 1. Download the latest .vsix from GitHub Releases
# 2. In VS Code, run:
code --install-extension marauders-map-md-1.0.0.vsix

Or: Command Palette → Extensions: Install from VSIX... → select file.

Install from Marketplace

Search "MaraudersMapMD" or "Marauders Map MD" in the VS Code Extensions view.

Direct link: https://marketplace.visualstudio.com/items?itemName=mandarange-dev.marauders-map-md

First Steps

1. Open any .md file
2. Run MaraudersMapMD: Open Preview to Side (Command Palette)
3. Start editing — preview updates in real-time
4. Save the file — AI artifacts auto-generate to docs/MaraudersMap/ directory

Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type "MaraudersMapMD":

Preview & Edit

Images & Export

History

AI Readability (GEO)

Help

Detailed Usage

Readability-First Markdown

• Keep a clear heading hierarchy (#, ##, ###). Avoid skipping levels.
• Use short paragraphs and bullets for dense content.
• Use tables for settings, options, and comparisons.
• Use bold for key terms, inline code for identifiers.
• Use blockquotes for critical notes, not general prose.
• Use AI Hint Blocks for must-read content:
  • > [AI RULE] constraints
  • > [AI DECISION] key decisions
  • > [AI TODO] follow-up actions
  • > [AI CONTEXT] essential background

Visual Emphasis (Preview)

• Heading levels are color-coded to show hierarchy.
• Links are colored; convert raw URLs into Markdown links.
• Code blocks and inline code are styled for commands/paths.
• Blockquotes get a colored border for critical notes.

History Workflow

• Use History to browse snapshots and restore when needed.
• Create a Checkpoint before major edits.

Prompt Workflow

• Use Rewrite Prompt button to copy a rewrite prompt.
• Paste into Cursor/Antigravity and apply to a copy of the document.

Settings

All settings use the maraudersMapMd.* namespace. Configure via VS Code Settings UI or settings.json.

AI Artifacts Output Structure

When AI features are enabled, MaraudersMapMD generates the following file structure:

docs/MaraudersMap/
  <document-id>/
    ai-map.md          # Document structure map with token estimates
    index.json         # Search index with keywords and links
    sections/
      01-introduction.md
      02-architecture.md
      ...

For AI agents: Read docs/MaraudersMap/<docId>/ai-map.md first to understand document structure, then selectively load sections as needed.

Generative Engine Optimization (GEO)

MaraudersMapMD is designed for the GEO era — where AI search engines (ChatGPT, Perplexity, Claude, Gemini) answer questions by consuming documentation:

What is GEO?

Generative Engine Optimization (GEO) is the practice of optimizing content to be accurately understood and cited by AI-powered search engines and large language models. Unlike traditional SEO (which targets keyword matching), GEO focuses on:

• Structured information: Clear hierarchies, explicit relationships
• Machine-readable metadata: Schema.org, llms.txt standards
• Token efficiency: Conveying maximum information within context windows
• Semantic markers: Explicit annotations for AI priority processing

FAQ

Development

git clone https://github.com/mandarange/MaraudersMapMD.git
cd MaraudersMapMD
npm install
npm run compile
npm test
npm run package    # Creates .vsix file

Publishing

See PUBLISHING.md for Marketplace publish steps.

Tech Stack

• Language: TypeScript
• Bundler: esbuild (single-file bundle)
• Markdown: markdown-it with task-lists plugin
• PDF: puppeteer-core (system Chrome)
• Testing: Vitest (unit) + VS Code Test Electron (integration)

Contributing

Contributions are welcome! Please see the GitHub Issues for open tasks.

License

MIT © 2025