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:

Problem	MaraudersMapMD Solution
AI can't read the whole document	AI Map provides structure at a glance
AI misses critical rules	AI Hint Blocks mark must-read content (`RULE`, `DECISION`, `NOTE`)
Long docs lose accuracy	Section Pack splits by heading for precise retrieval
Keyword search fails for AI	Search Index enables semantic section discovery
Rewriting docs is tedious	Rewrite Prompt generates a ready-to-paste AI prompt

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.marauders-map-md

First Steps

Open any .md file
Run MaraudersMapMD: Open Preview to Side (Command Palette)
Start editing — preview updates in real-time
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

Command	Description
`Open Preview to Side`	Open live Markdown preview panel
`Toggle Preview Lock`	Lock/unlock preview to current document
`Format: Make Bold`	Wrap selection in `bold`
`Format: Make Italic`	Wrap selection in `italic`
`Format: Make Inline Code`	Wrap selection in `code`
`Insert: Insert Link`	Insert Markdown link template
`Insert: Insert Heading`	Insert heading markup
`Insert: Insert Quote`	Insert blockquote
`Toggle: Toggle Task`	Toggle task checkbox (`- [ ]` / `- [x]`)

Images & Export

Command	Description
`Images: Insert Image from File`	Pick image, copy to assets, insert link
`Images: Paste Image to Assets`	Paste clipboard image to assets directory
`Export: Export to HTML`	Export as standalone HTML file
`Export: Export to PDF`	Export as PDF via Chrome/Chromium

History

Command	Description
`History: Open History`	View snapshot history for current file
`History: Create Checkpoint`	Create labeled checkpoint snapshot
`History: Diff with Current`	Compare snapshot with current version
`History: Restore Snapshot`	Restore file from selected snapshot
`History: Prune History Now`	Run retention cleanup manually

AI Readability (GEO)

Command	Description
`AI: Insert AI Rule Hint`	Insert `[AI RULE]` semantic marker
`AI: Insert AI Decision Hint`	Insert `[AI DECISION]` semantic marker
`AI: Insert AI Note Hint`	Insert `[AI NOTE]` semantic marker
`AI: Copy Readability Prompt`	Copy prompt for readability-focused rewriting

Help

Command	Description
`Help: Open Usage Guide`	Open the in-extension usage guide panel

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.

Preview Settings

Setting	Default	Description
`preview.updateDelayMs`	`200`	Debounce delay (ms) before updating preview
`preview.largeDocThresholdKb`	`512`	Size threshold (KB) for large document handling
`preview.largeDocUpdateDelayMs`	`700`	Debounce delay (ms) for large documents
`preview.scrollSync`	`true`	Synchronize scroll between editor and preview
`render.allowHtml`	`false`	Allow raw HTML rendering in Markdown

Image Settings

Setting	Default	Description
`images.assetsDir`	`"assets"`	Asset directory name relative to Markdown file
`images.allowRemote`	`false`	Allow embedding remote image URLs
`images.filenamePattern`	`"{basename}-{yyyyMMdd-HHmmss}"`	Pattern for generated image filenames
`images.altTextSource`	`"filename"`	Source for alt text (`filename`, `prompt`, `empty`)

PDF Export Settings

Setting	Default	Description
`pdf.browserPath`	`"auto"`	Path to Chrome/Chromium (`auto` = auto-detect)
`pdf.format`	`"A4"`	Paper format (`A4`, `Letter`, `A3`, `A5`)
`pdf.marginMm`	`12`	Margin size in millimeters
`pdf.printBackground`	`true`	Include background colors/images
`pdf.embedImages`	`"fileUrl"`	Image embedding method (`fileUrl`, `dataUri`)
`pdf.outputDirectory`	`"${workspaceFolder}/exports"`	Output directory for PDFs
`pdf.openAfterExport`	`true`	Open PDF after export

History Settings

Setting	Default	Description
`history.enabled`	`true`	Enable history snapshots
`history.storageLocation`	`"workspace"`	Storage location (`workspace`, `globalStorage`)
`history.mode`	`"onSave"`	Snapshot trigger (`onSave`, `interval`, `manual`)
`history.intervalMinutes`	`10`	Auto-snapshot interval (minutes)
`history.maxSnapshotsPerFile`	`100`	Max snapshots per file
`history.maxTotalStorageMb`	`200`	Max total storage (MB)
`history.retentionDays`	`30`	Retention period (days)
`history.protectManualCheckpoints`	`true`	Protect checkpoints from auto-pruning
`history.snapshotCompression`	`"gzip"`	Compression (`none`, `gzip`)
`history.createPreRestoreSnapshot`	`true`	Create safety snapshot before restore

AI Readability Settings

Setting	Default	Description
`ai.enabled`	`true`	Enable AI readability features
`ai.outputDir`	`"docs/MaraudersMap"`	AI artifacts output directory
`ai.buildOnSave`	`true`	Generate AI artifacts on save
`ai.generate.map`	`true`	Generate AI Map artifact
`ai.generate.sections`	`true`	Generate Section Pack artifact
`ai.generate.index`	`true`	Generate Search Index artifact
`ai.tokenEstimateMode`	`"koreanWeighted"`	Token estimation method (`simple`, `koreanWeighted`)
`ai.gitPolicy`	`"ignoreAll"`	Git policy for AI artifacts (`ignoreAll`, `commitMapOnly`, `commitAll`)
`ai.largeDocThresholdKb`	`512`	Size threshold (KB) for limiting AI generation

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:

GEO Feature	File	Purpose
llms.txt	`llms.txt`	Concise AI-readable project summary
llms-full.txt	`llms-full.txt`	Complete reference for AI agents
AI Map	`docs/MaraudersMap/*/ai-map.md`	Token-efficient document structure
Section Pack	`docs/MaraudersMap/*/sections/`	Heading-based splits for retrieval
Search Index	`docs/MaraudersMap/*/index.json`	Semantic keyword index
AI Hint Blocks	In-document markers	Priority content for AI consumption
Schema.org JSON-LD	README.md	Structured data for search engines

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

Does MaraudersMapMD call any AI API?

No. MaraudersMapMD is completely vendor-neutral. It generates file-based artifacts (docs/MaraudersMap/ directory) that any AI tool (Cursor, Claude, Copilot, etc.) can read. Zero external API calls, zero cloud dependencies.

What is the AI Map and why do I need it?

The AI Map (ai-map.md) is a structured table showing your document's heading hierarchy, line ranges, and token estimates. When an AI assistant reads your repository, it can read the AI Map first (small token cost) and then selectively load only the sections it needs, dramatically improving accuracy and reducing token usage.

Does it work with Korean (or other CJK) text?

Yes. The token estimator supports a koreanWeighted mode (default) that accounts for the higher token-per-character ratio of CJK text, providing more accurate estimates.

Why Chrome/Chromium for PDF export?

MaraudersMapMD uses puppeteer-core with your system's Chrome/Chromium to avoid bundling a 300MB+ browser. If Chrome is not detected, it provides clear setup instructions and falls back to HTML export with browser print-to-PDF.

How is this different from Markdown Preview Enhanced or other Markdown extensions?

MaraudersMapMD is AI-first. While other extensions focus on rendering features (diagrams, math, charts), MaraudersMapMD focuses on making your documents optimally consumable by LLMs through AI Map, Section Pack, Search Index, and AI Hint Blocks. It's designed for the workflow where you write docs AND AI reads them.

What is llms.txt?

llms.txt is an emerging standard (proposed by Jeremy Howard / Answer.AI) for providing AI-readable documentation alongside your project. It's like robots.txt but for LLMs. MaraudersMapMD ships with both llms.txt (concise) and llms-full.txt (comprehensive) to maximize discoverability by AI search engines.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.sisyphus		.sisyphus
docs		docs
media		media
src		src
test		test
.gitignore		.gitignore
.vscodeignore		.vscodeignore
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
esbuild.js		esbuild.js
icon.png		icon.png
llms-full.txt		llms-full.txt
llms.txt		llms.txt
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

mandarange/MaraudersMapMD

Folders and files

Latest commit

History

Repository files navigation

MaraudersMapMD

Why MaraudersMapMD?

Features

Ultra-Fast Markdown Preview

AI Readability & GEO Support

Quick Edit Commands

Image Workflow

PDF & HTML Export

Document History & Snapshots

Quick Start

Install from VSIX

Install from Marketplace

First Steps

Commands

Preview & Edit

Images & Export

History

AI Readability (GEO)

Help

Detailed Usage

Readability-First Markdown

Visual Emphasis (Preview)

History Workflow

Prompt Workflow

Settings

AI Artifacts Output Structure

Generative Engine Optimization (GEO)

What is GEO?

FAQ

Development

Publishing

Tech Stack

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages