.md previewer (markdown)

Read documentation beside your code. When a task is finished, record what changed, why it changed, and how you tested it in a Markdown file you can keep in Git.

Start here

1. Install .md previewer in Visual Studio Code.
2. Open a Markdown file such as README.md.
3. Right-click the file in Explorer and select Open with .md previewer.
4. To edit while reading, select .md previewer: Preview to the Side instead.
5. Type in the source editor. The preview updates automatically. Save normally with Ctrl+S, or Cmd+S on macOS.

Both preview options also appear when you right-click a Markdown editor tab or inside its source editor. Explorer supports .md and .markdown files, including uppercase extensions.

Keyboard shortcut: Ctrl+Alt+M on Windows/Linux, Cmd+Alt+M on macOS, while a Markdown editor is focused.

Animated usage guide

Press Ctrl+Shift+P (macOS: Cmd+Shift+P), type .md previewer: Getting Started, and press Enter.

The built-in guide includes an animated guide showing the current preview interface, numbered instructions, and a Try the sample document button. The GIF is bundled with the extension and works offline.

To try the features immediately, run .md previewer: Try Sample Document. It opens an editable, unsaved sample beside its preview. Save a copy if you want to keep your edits.

Read and navigate

Tables, task lists, syntax-highlighted code blocks, heading links, and local images are supported. Put local images in the document's directory or a subdirectory.

Diagrams and mathematics

Use a fenced block with the language mermaid for diagrams:

```mermaid
graph LR
  A[Change code] --> B[Record the reason]
  B --> C[Save the journal]
```

Use a fenced block with the language math for mathematical expressions:

```math
E = mc^2
```

Use $E = mc^2$ for inline mathematics and $$E = mc^2$$ for display mathematics. Display formulas may span multiple lines between $$ delimiters. Escaped dollar signs and dollar signs in code remain literal.

Record a development change

Before you start: open a trusted project folder that is already a Git repository. Git must be installed. Make your code changes first.

1. Click Record change in the preview, or run .md previewer: Record Change from the Command Palette.
2. If multiple workspace folders are open, choose the folder to document.
3. Enter a short title, for example Add login validation.
4. Explain why, for example Prevent empty credentials from reaching the API.
5. Enter your testing notes, for example Checked empty fields and successful login. If you have not tested the change, say so.
6. Review the new draft in DEVELOPMENT.md. The extension includes staged, unstaged, and untracked filenames.
7. Fill in implementation decisions and any AI assistance, then save with Ctrl+S / Cmd+S.

Use .md previewer: Open Development Log to return to the journal later.

The journal is a draft until you save it. The extension does not commit code, inspect past commits, automatically explain code changes, or call an AI service. You supply the meaning of the change.

Export to HTML and PDF

1. Open a Markdown source file or its preview.
2. Click Export HTML in the preview, or run .md previewer: Export HTML.
3. Choose a destination and save.
4. Open the exported .html file in a browser.

Exported HTML includes rendered Mermaid diagrams, math styling and fonts, and supported local PNG, JPEG, GIF, WebP and SVG images. Missing local images produce a warning. HTTPS images remain remote and need connectivity. Invalid diagrams remain readable source text.

For browser printing, select Print / PDF or run .md previewer: Print / Save as PDF. Save the HTML file when prompted; it opens in your browser. Click Print / Save as PDF, then select your printer or Save as PDF in the browser print dialog.

Direct PDF export

1. Click Export PDF in the preview, or run .md previewer: Export PDF.
2. Choose a .pdf filename and save. The extension generates the PDF directly, including math, rendered diagrams and local images.
3. Change projectMemory.pdf.paperSize (A4 or Letter) and projectMemory.pdf.orientation (portrait or landscape) in Settings when needed.

Direct PDF export requires an installed Microsoft Edge, Google Chrome or Chromium on the machine running the extension. Common installations are detected automatically. For a custom installation, set the executable path in projectMemory.pdf.browserPath in your user settings. A separate temporary browser profile is used for each export. In Remote SSH, WSL or containers, the browser must be installed on that extension host. The browser print workflow remains available if direct export is unavailable.

Commands

Open the Command Palette with Ctrl+Shift+P / Cmd+Shift+P, then search for .md previewer.

Settings and requirements

• VS Code: version 1.90 or newer.
• Git: needed only for Record Change.
• Synchronized scrolling: toggle projectMemory.syncScroll in Settings; enabled by default. Synchronization follows Markdown blocks.
• PDF: choose A4/Letter paper and portrait/landscape orientation; set projectMemory.pdf.browserPath only when automatic browser detection does not find your installation.
• Preview font size: change projectMemory.fontSize in Settings; default 16, range 12–24.
• Workspace trust: Git recording requires a trusted workspace. Preview remains available in restricted mode.

Troubleshooting

The preview command is missing: run Developer: Reload Window, open a Markdown file, and search the Command Palette for .md previewer.

The right-click action is missing: select a .md or .markdown file, rather than a folder. In an editor, check that the language mode is Markdown.

Record Change cannot read Git: make sure Git is installed, the project folder is open, and it belongs to a Git repository. Preview does not require Git.

A local image does not display: use a relative image path within the Markdown file's directory or a subdirectory. Parent-directory images are outside the preview's local resource scope.

The extension header shows harish-chirati: this is the registered publisher ID. The publisher display name is Harish Chirati. Local VSIX installations may show the ID until VS Code receives the Marketplace publisher metadata. The ID must remain unchanged for updates to work.

Privacy

No AI credentials, AI provider, or telemetry are used. Raw HTML in Markdown is displayed as text. Preview scripts are bundled locally, with a Content Security Policy. HTTPS images may contact the image host. Git recording runs locally and collects changed filenames within the selected workspace folder.

For contributors

Install Node.js 22 or newer, then run npm install. Press F5 in this source project and choose Run .md previewer to launch an Extension Development Host.

npm run check
npm test
npm run package

npm run watch rebuilds JavaScript and TypeScript during development. CSS changes require a new build and reopening the preview.

Author and license

Created by Harish Chirati. Publisher ID: harish-chirati. MIT license.

Release verification

Install the VSIX in VS Code and verify scrolling in both directions, repeated preview commands, search navigation, tab switching and window restart restoration. Export a document with math, Mermaid and a local image; open the HTML and verify direct Export PDF, then verify the optional browser print dialog. Unsaved documents cannot reliably be restored across restarts.

Release packages include their version, for example .md preview-0.2.1.vsix. Repeated builds receive a build suffix and preserve all older packages. Before publishing a new update, run npm version patch --no-git-tag-version to increase the manifest version, then npm run package.

New in 0.4.0

• Diagram controls: zoom, pan, and save as SVG or PNG. Click an image to open the same viewer. Use the mouse wheel or + / −, drag to pan, Reset to fit, and Escape to close.
• Click checklist boxes to update the Markdown source. Edits use VS Code undo and leave the document unsaved for review. Stale clicks are rejected if the source changed.
• Appearance opens extension settings: font family, font size, reading width, line spacing, and editor / light / dark themes.
• PDF margins, header, footer, and page numbers are configurable under projectMemory.pdf. Use {title} in headers or footers. Margin headers and page numbers require Edge / Chrome / Chromium 131 or later; leave enough top and bottom margin for them.
• Put <!-- pagebreak --> on its own line to start a new PDF page. The preview shows a dashed marker.
• Relative .md and .markdown links open within the preview. Back and Forward restore reading positions during that preview session; other files open in VS Code and web links open externally.
• Unchanged diagrams are retained while prose updates. Unchanged source skips Markdown parsing, and large documents debounce rendering and search.

PNG diagram export converts HTML labels to SVG text for a portable image; complex multiline labels can differ from the vector SVG. SVG preserves the original diagram layout.

0.4.0 smoke test

Open the sample; toggle a task and undo in the source editor. Open a diagram, zoom and drag it, and save both formats. Click the logo to zoom it. Change Appearance settings, follow a relative Markdown link and return with Back. Export a document with a page-break marker and custom PDF margins/header/footer, then check both pages.