` โ with blank lines around the headings โ and the page gets a site menu in its Contents panel with nothing visible in the body. Each document then lists exactly the pages it wants, in plain markdown, with no header or theme changes. Headings that merely *contain* a link among other words keep their normal in-page anchor.
### Custom Themes
You can edit or add themes in your `MD DOCS-win32-x64\resources\public\themes` folder from where you install your MD DOCS application.
To create custom themes:
1. Shift+click the refresh button to open the themes folder
2. Create a new `.css` file following the existing theme format
3. Add metadata comments at the top:
```css
/**
* @name My Theme
* @background #FFFFFF
* @text #333333
*/
```
4. Click refresh to load your new theme
## Working with Images
### Insert from File
1. Click the **Image** button in the toolbar
2. Select an image file โ PNG, JPG, JPEG, GIF, WEBP, or SVG
3. The image is copied to a `{filename}_images/` folder
4. A markdown reference is inserted: ``
### Paste from Clipboard
1. Copy an image to your clipboard (screenshot, etc.)
2. Press **Ctrl+Shift+V** or click the paste image button
3. Enter a name for the image
4. The image is saved as PNG and inserted
### Drag and Drop
Drag one or more image files from Explorer or Finder straight onto the editor. Each one is copied into the document's `{filename}_images/` folder and a markdown reference is written at your cursor โ the same result as **Insert from File**, without the dialog.
Accepted types are PNG, JPG, JPEG, GIF, WEBP, and **SVG**. If a file of the same name is already in the folder, the new one is renamed rather than overwriting it (`diagram.svg` becomes `diagram-1.svg`).
Dropping an SVG works exactly like a raster image, and once it's in your document you can **Ctrl+click** it in the preview to open it in [DocuMark](#documark--image-annotation-editor) for annotation.
You can also insert an image already in your project without dragging:
1. Right-click an image in the Files panel
2. Select "Insert in Document"
3. The image path is inserted at your cursor position
### Export Base64 Images
If your document contains embedded base64 images:
1. Go to More Options (โฎ) > Export Base64 Images
2. Images are extracted to `{filename}_images/`
3. Optionally replace base64 data with file references
## Working with Tables
### Insert a Table
Click the **Table** button to insert a 3x3 table template:
```markdown
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
```
### Insert CSV as Table
You can turn CSV or TSV data into a markdown table in one step. Two commands live in More Options (โฎ):
- **Insert CSV from File...** โ Opens a file dialog (`.csv`, `.tsv`, or `.txt`) and inserts a markdown table at the cursor.
- **Insert CSV from Clipboard** โ Does the same using whatever CSV/TSV text is on your clipboard.
The converter:
- Auto-detects whether columns are separated by commas or tabs.
- Handles RFC 4180 quoting, so embedded commas, quotes, and line breaks inside a field are parsed correctly.
- Escapes pipes (`|`) and newlines so the resulting table always renders cleanly.
The first row becomes the table header.
### HTML Lists in Table Cells
Standard markdown lists don't work inside table cells. Use the HTML list options instead:
1. Select your list items
2. Go to More Options (โฎ)
3. Choose "HTML Bullet List" or "HTML Numbered List"
This generates:
```html
```
### Images in Tables
Images in tables are automatically sized to fit the column width. You cannot have paragraphs inside a cell of a table.
## In-Document Anchor Links
Anchor links let you jump from one place in a document to another โ like a clickable table of contents. Clicking an anchor link in the preview smooth-scrolls to the target heading.
### How Anchors Work
Every heading in your document automatically gets a hidden `id` derived from its text โ a "slug." The slug rule:
- Lowercase
- Spaces become hyphens
- Punctuation is stripped (letters, digits, `_`, `-` are kept)
Examples:
| Heading | Auto-generated slug |
|---------|---------------------|
| `## Getting Started` | `getting-started` |
| `## Step 1: Install!` | `step-1-install` |
| `### FAQ` | `faq` |
Duplicate headings get a numeric suffix: two `## Setup` headings become `setup` and `setup-1`.
### Creating an Anchor Link with the Link Button
1. **Select** the text in the editor that you want to be clickable.
2. Click the **Link** button in the toolbar.
3. A picker opens with two ways to finish the link:
- **URL field** (focused on open) โ paste any URL and press **Enter**. If you selected something that already looks like a URL, the field is pre-filled.
- **Anchors in this doc** โ a scrollable list of every heading in the current document, indented by heading level, plus any custom anchors (shown with an โ icon). Click one to insert.
4. The result is inserted as `[selectedText](#slug)` or `[selectedText](url)`, and the link label stays selected so you can keep formatting it.
Press **Esc** or click outside the picker to dismiss it without inserting.
If you click the Link button **without** any text selected, the picker is skipped and a `[link text](url)` placeholder is inserted at the cursor (legacy behavior).
### Custom Anchors
When you want a stable target that isn't tied to a heading's text (so it won't break if you later rename the heading), add an empty anchor tag where you want to land:
```markdown
```
Then link to it like any other anchor:
```markdown
[Jump to my spot](#my-spot)
```
Custom anchors appear in the Link picker's anchor list with an โ icon.
### Cross-File Anchors
Anchors aren't limited to the current file. Paste a relative path with a fragment into the Link picker's URL field:
```markdown
[See the API doc](./api-reference.md#authentication)
```
These links work when the rendered HTML files are placed in the same folder structure (for example, after exporting to browser). For a faster way to create links to other documents โ and to follow them inside the app โ see [Linking Between Documents](#linking-between-documents).
### Manual Typing
You can always type anchor links by hand using the slug rule above:
```markdown
[Click here to jump](#getting-started)
```
If a link doesn't scroll when clicked, open DevTools (Ctrl+Shift+I) in the preview panel, find the target heading, and copy its actual `id` attribute โ that is the exact slug to use.
## Linking Between Documents
Beyond jumping around inside one file with [anchor links](#in-document-anchor-links), MD DOCS lets you link **between separate `.md` files** that live in the same folder โ so a set of related documents can cross-reference each other like a small wiki. A document link is just a normal Markdown link whose target is another `.md` file:
```markdown
[Getting Started](getting-started.md)
[Install steps](setup.md#installation)
```
These links work two ways:
- **In the app** โ clicking the link in the live preview opens that document in a tab (or switches to it if it's already open) and shows its preview. A link with a heading fragment (`setup.md#installation`) opens the document **and** scrolls to that heading.
- **In published HTML** โ when you Export to Browser, links to `.md` files are automatically rewritten to point at the matching `.html` files, so the published pages link to each other correctly.
### Adding a Link with "Add as local link"
The quickest way to create one is from the **DIR** tab โ the directory tree in the left sidebar that lists every file in your project folder:
1. Open the **DIR** tab in the left sidebar.
2. **Right-click** the `.md` file you want to link to.
3. Choose **๐ Add as local link**.
A Markdown link is inserted at your cursor, using the target document's first `# Heading` as the link text (or its filename if it has no heading). For example, right-clicking `getting-started.md` inserts `[Getting Started](getting-started.md)`. You can also type these links by hand, or paste a relative path into the **Link** button's URL field (see [Cross-File Anchors](#cross-file-anchors)).
### Navigating Links in the Preview
Click any link to another document in the live preview and MD DOCS loads that file and shows it. Use the tab bar (or **Ctrl+Tab**) to get back to where you were. Links that point to a specific heading โ `guide.md#installation` โ open the document and jump straight to that heading.
> **Same-folder scope:** In-app navigation is designed for documents that sit in the **same folder**. A link that points into another folder (for example `../shared/notes.md`) is left for the browser to resolve and is not followed inside the app.
### Publishing Linked Documents
Each document is exported on its own, so to publish a set of linked documents, **Export to Browser for each one**. When you export, MD DOCS rewrites every same-folder `.md` link to the matching `.html` file (keeping any `#heading` fragment); external links (`http://โฆ`), e-mail links, and in-document anchors are left untouched.
If you export a document that links to another document you **haven't exported yet**, MD DOCS shows a warning listing the documents whose `.html` file doesn't exist beside it. The current page is still exported โ the warning is simply a reminder of which linked documents you still need to export before sharing, so you don't end up with dead links.
## YouTube Videos
### Inserting Videos
1. Click the **YouTube** button in the toolbar
2. Replace `VIDEO_ID` with the actual YouTube video ID
3. Replace `Video Title` with your description
The format is:
```markdown
[](https://www.youtube.com/watch?v=VIDEO_ID)
```
### How It Works
- In the preview, YouTube links display as clickable thumbnails
- The official YouTube play button overlay appears on hover
- Clicking opens the video in your default web browser
- This approach works in both the app and exported HTML
### Finding the Video ID
The video ID is the 11-character code in YouTube URLs:
- `https://www.youtube.com/watch?v=dQw4w9WgXcQ` โ ID is `dQw4w9WgXcQ`
- `https://youtu.be/dQw4w9WgXcQ` โ ID is `dQw4w9WgXcQ`
## Mermaid Diagrams
MD DOCS supports Mermaid diagrams in both the preview panel and browser export. Wrap your diagram code in a fenced mermaid code block:
````markdown
```mermaid
flowchart LR
A[Start] --> B{Decision}
B -->|Yes| C[Do something]
B -->|No| D[Do something else]
```
````
Diagrams render live in the preview panel (and in browser exports), with theme-aware colors:
### Supported Diagram Types
- **Flowcharts** โ `flowchart LR` or `flowchart TD`
- **Sequence diagrams** โ `sequenceDiagram`
- **Class diagrams** โ `classDiagram`
- **State diagrams** โ `stateDiagram-v2`
- **Gantt charts** โ `gantt`
- **Pie charts** โ `pie`
### Tips
- Diagrams automatically use theme-aware colors โ dark themes get light diagram elements and vice versa
- Line breaks in node text are converted automatically (`\n` becomes `
`)
- Use the **Mermaid Diagram** option in the More Options (โฎ) menu to insert a template
- Diagrams render in the preview panel and in all browser export themes
- Have a hand-drawn text diagram (box-drawing characters and arrows)? Ask your agent in the [chat panel](#chatting-with-an-ai-agent) to "convert this text diagram to Mermaid" and it will replace it with a rendered flowchart in place
## Marp Slide Presentations
MD DOCS supports **Marp** for creating slide presentations directly from Markdown. Add `marp: true` to your document's YAML frontmatter to activate slide mode.
### Creating a Marp Document
Add a frontmatter block at the very top of your `.md` file:
```markdown
---
marp: true
theme: default
paginate: true
---
# First Slide
Content for the first slide.
---
## Second Slide
- Bullet points
- Work as expected
---
## Third Slide
Use `---` (horizontal rule) to separate slides.
```
### How It Works
When MD DOCS detects `marp: true` in the frontmatter:
- The preview panel switches from normal markdown rendering to **slide mode**
- Slides are displayed stacked vertically, scaled to fit the preview width
- Marp's own theme CSS is applied instead of the MD DOCS theme selector
- Scroll sync is disabled (not applicable to slide content)
### Built-in Marp Themes
Marp includes three built-in themes you can set in the frontmatter:
- **`default`** โ Clean white background with dark text
- **`gaia`** โ Warm-toned theme with centered content
- **`uncover`** โ Minimal theme with large typography
### Marp Directives
Control slide appearance using HTML comment directives:
| Directive | Effect |
|-----------|--------|
| `` | Show page numbers on all slides |
| `` | Hide page number on this slide only |
| `` | Switch to dark color scheme |
| `` | Center content on this slide only |
| `` | Set background color |
| `` | Set gradient background |
| `` | Add a header to all slides |
| `` | Add a footer to all slides |
Directives prefixed with `_` (underscore) apply only to the current slide. Without the underscore, they apply globally from that point forward.
### Background Images
Use Marp's image syntax for slide backgrounds:
```markdown
```
### Auto-fit Text
Use the `` comment inside a heading to scale text to fill the slide width:
```markdown
# This text fills the width
```
### Math Equations
Marp supports LaTeX math via MathJax. Enable it in frontmatter with `math: mathjax`:
```markdown
---
marp: true
math: mathjax
---
Inline: $E = mc^2$
Block:
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
```
### Exporting Marp Presentations
Click the **Export** button (top-right of the preview panel) to generate an HTML presentation file. The exported file opens in your browser with three viewing modes:
- **Scroll mode** (default) โ All slides stacked vertically for easy review. Click any slide to select it as a starting point.
- **Fullscreen** (click "Fullscreen" or press **F5**) โ One slide at a time, fills the entire screen.
- **Window** (click "Window" or press **F6**) โ One slide at a time within the browser window.
#### Presentation Navigation
| Key | Action |
|-----|--------|
| **Arrow Right / Down / Space** | Next slide |
| **Arrow Left / Up** | Previous slide |
| **Home** | First slide |
| **End** | Last slide |
| **Escape** | Exit to scroll mode |
You can also **tap or click the right half** of a slide to go forward and the **left half** to go back โ this works on touch screens (phones and tablets), so the exported deck is fully navigable on mobile without a keyboard. Tap **Exit** (top-right) to leave the presentation.
### Tips
- Marp documents are standard Markdown โ they render normally in any markdown viewer, just without slide separation
- The `---` separator must be on its own line with blank lines above and below for reliable slide breaks
- Images can be sized with Marp syntax: `` or ``
- Syntax-highlighted code blocks work the same as regular Markdown
## Keyboard Shortcuts
### File Operations
| Shortcut | Action |
|----------|--------|
| **Ctrl+N** | New file |
| **Ctrl+O** | Open file |
| **Ctrl+S** | Save current file |
| **Ctrl+W** | Close current tab |
| **Ctrl+Tab** | Next tab |
| **Ctrl+Shift+Tab** | Previous tab |
| **F5** | Refresh file from disk |
### Editing
| Shortcut | Action |
|----------|--------|
| **Ctrl+F** | Find |
| **Ctrl+H** | Find and Replace |
| **Ctrl+B** | Toggle bold on selected text |
| **Ctrl+I** | Toggle italic on selected text |
| **Ctrl+Shift+V** | Paste image from clipboard |
| **Ctrl+Alt+V** | Paste as Markdown (converts HTML/RTF to markdown) |
| **Ctrl+Z** | Undo |
| **Ctrl+Y** | Redo |
| **Ctrl+A** | Select all |
### Navigation
| Shortcut | Action |
|----------|--------|
| **Ctrl+G** | Go to line |
| **Ctrl+Home** | Go to beginning |
| **Ctrl+End** | Go to end |
### DocuMark
| Shortcut | Action |
|----------|--------|
| **Ctrl+Click** on image in preview | Open DocuMark annotation editor |
| **Escape** | Cancel placement mode or crop mode in DocuMark |
## Settings
Open settings by clicking **Settings** in the toolbar. (This panel was previously named *Preferences*.)
Settings is split into two tabs: **General**, covering the editor and preview options below, and **AI Agents**, where you choose which AI agent MD DOCS chats with. It opens on General, and anything you've changed is kept if you switch tabs and come back.
### General
1. **App Theme** โ Sets the look of the application chrome itself (the title bar and window background) โ separate from the preview theme that styles your document. Choose **System** (follow your OS light/dark setting), **Light**, **Dark**, or **3rd**. Your choice is remembered between launches and applied before the first paint, so there's no flash on startup. *Reset to Defaults* restores **Dark**.
2. **Editor Font Size** โ Adjust the editor font size from 10px to 24px. Default is 18px.
3. **Enable Spell Check** โ Toggle the built-in spell checker on or off. When enabled, misspelled words are highlighted with red underlines in the editor. You can right-click misspelled words to see suggestions, ignore them, or add them to your custom dictionary. This setting takes effect immediately without restarting. Default is **ON**.
4. **HTML Preview Browser Path** โ Optionally specify a custom browser for the "Export to Browser" feature. Click **Browse** to pick an executable, or leave empty to use your system default browser.
5. **Consolidate Files on Save As** โ When enabled, using **Save As** will automatically find all locally-referenced files in your document (images, links, etc.) that are stored outside the document's `_images` folder, copy them into the new document's `_images` folder, and update all references in the markdown to point to the new locations. This makes your saved document fully self-contained and portable. If two files share the same name, the duplicate is automatically renamed (e.g., `photo.png` becomes `photo_1.png`). References inside code blocks are ignored. Default is **ON**.
6. **Reset to Defaults** โ Click to reset all settings including font size, spell check, browser path, app theme, Consolidate on Save As, preview theme selection, and window size and position.
### AI Agents
The **AI Agents** tab is where you pick the agent that powers [AI chat](#chatting-with-an-ai-agent):
Choose one: **Claude Code**, **Codex**, **Grok Build**, or **None**. It's a single choice โ picking one sets it up and makes it your chat agent in one click, and turns off whichever you had before. Choose **None** to turn AI chat off entirely.
The agent you pick expands to show its details:
- **Connection status** โ a green dot and *"Connected"* when it's ready, with the version it found. **Re-check** runs detection again.
- **Binary path** โ leave empty unless the program isn't found automatically.
- **Model** โ an optional default model, or the one from that tool's own config.
- **Advanced** (Claude only) โ store an OAuth token for headless or other machines.
Your binary path and model are remembered per agent, so if you go back to one you used before, its setup is still there.
#### Agent permissions
Below the agent picker, **Agent permissions** shows what your agent is allowed to do and lets you pull it back:
- **Full access** (the default) โ the agent can read and edit files, run commands, and control MD DOCS itself: switching themes, opening files, exporting.
- **No document tools** โ the agent keeps file editing and commands but can no longer drive the app.
There is deliberately no sandboxed option. A sandboxed agent cannot stop to ask your permission, so it declines silently โ a request looks like it worked when nothing happened.
# Chatting with an AI Agent
MD DOCS can chat with a coding agent already installed on your machine, so you can ask it to edit the document you're working on โ convert a diagram, tighten a section, fix tables, draft a summary โ and it makes the change in place.
Three are supported, and you pick one in **Settings โ AI Agents**:
| Agent | Runs on | Install |
|---|---|---|
| **Claude Code** | Your Claude subscription | [claude.com/claude-code](https://claude.com/claude-code) |
| **Codex** | Your ChatGPT subscription | `npm install -g @openai/codex@latest` |
| **Grok Build** | Your grok.com subscription | `irm https://x.ai/cli/install.ps1 \| iex` |
## No API key, no API credits
Chat runs on **your existing subscription** through the agent's own program already on your machine. MD DOCS launches that local program and deliberately ignores any API key in your environment, so you are **never billed for API usage** โ it's the same entitlement you get running the tool in a terminal.
## Setting it up
1. **Install the agent** you want, using the table above.
2. Open **Settings โ AI Agents** and select it.
3. Check the status line:
- **Not found** โ install the tool, then click **Re-check**.
- **Not signed in** โ click the sign-in button. A terminal opens and a browser handles the sign-in with your subscription; the status updates on its own when you're done.
- **Connected** โ a green dot confirms it's ready.
## Using the chat
1. Click the **AI** tab in the left sidebar to open the chat panel, alongside TOC, Files, and DIR.
2. The first time, confirm the one-time **"runs as a full agent"** notice.
3. Type a request โ for example *"add a one-paragraph summary at the top"* or *"convert the ASCII diagram to Mermaid"* โ and press **Enter**. The reply streams in, and any edits appear directly in your open document.
4. The tab is marked unsaved so you can review the change in the live preview before saving. Press **Stop** to cancel a run at any time.
## The agent knows which document you mean
Each conversation opens by telling the agent which document is on screen, its full path, the project folder, and that "this doc", "this file", and "it" all mean that document โ so *"rewrite this doc"* lands on the right file instead of a guess. If the document has unsaved edits, the agent is told the file on disk is behind what you see. The context is restated when you switch tabs, not on every message.
## Watching it work
- The panel header shows a **pulsing badge** with what the agent is doing and how long it has been going, so a quiet stretch doesn't look like a stall. The reply itself shows animated dots.
- The agent's steps collapse to a single **โ N steps** line you can click to expand. Without this, a dozen shell commands would push the reply off screen.
- The **eraser** at the top right of the panel empties the conversation and starts the agent on a fresh session, so it stops carrying over a conversation you can no longer see. Your next message re-introduces the open document.
> **Full agent:** the agent runs with full tool access on your machine and edits inside the folder of the open document. It can read and change files there, so review its edits before saving โ the same trust you'd extend to running that tool in a terminal.
# DocuMark โ Image Annotation Editor
DocuMark is a built-in SVG annotation editor for adding numbered callout dots, arrows, rectangles, and legends to screenshots and images. It opens in a separate window and saves annotations directly back into your document.
1. **Save & Close / Cancel** โ Save the annotated SVG back to your document, or cancel to discard changes.
2. **Annotation Toolbar** โ Add Dot, Add Rect, Renumber, dot size selector, Crop, and color pickers for annotations and text.
3. **Preview Canvas** โ The image being annotated, with numbered callout arrows pointing to key UI elements.
4. **Annotations Legend** โ Drag to reorder, double-click to rename, trash icon to delete. Shows all annotation labels.
## Opening DocuMark
**Ctrl+Click** (Cmd+Click on macOS) on any image in the preview panel to open it in DocuMark, or **right-click the image and choose Annotate image**:
- **SVG images** โ Opens the existing SVG for editing. Annotations are parsed and become editable.
- **Raster images** (PNG, JPG, WEBP, GIF, BMP) โ Opens a new annotation layer over the image. On save, a new SVG file is created and all markdown references to the original raster image are automatically updated to point to the new SVG.
## Annotation Tools
### Add Dot
Click the **+ Add Dot** button to enter placement mode (cursor becomes a crosshair). Click anywhere on the image to place a numbered marker. New dots are automatically labeled "Point N" โ double-click the label in the legend to rename it.
### Add Rect
Click the **+ Add Rect** button, then click-and-drag on the image to draw a rectangular highlight region. Rectangles appear as semi-transparent outlined regions. They can be renamed via double-click in the legend.
#### Moving Rects
Click and drag anywhere on a rectangle to reposition it. The rect stays clamped within the image bounds.
#### Resizing Rects
A small handle appears at the bottom-right corner of each rectangle. Drag it to resize (minimum 20ร20 pixels). The cursor changes to a diagonal resize arrow when hovering over the handle.
### Dot/Arrow Toggle
Right-click any annotation dot to toggle between two styles:
- **Dot** โ A numbered circle placed directly on the image
- **Callout Arrow** โ A numbered circle in the margin sidebar with an arrow pointing to the target location on the image. The arrow tip and margin dot can be repositioned independently by dragging.
### Dot Sizes
Right-click any annotation dot to choose a size preset:
- **Small** โ Compact markers for detailed images
- **Medium** โ Default size, good for most uses
- **Large** โ Prominent markers for presentations or large screenshots
The size setting applies to all annotations at once โ dots, arrows, rectangles, line weights, fonts, and margin width all scale together.
### Color Pickers
Two color pickers in the toolbar let you customize:
- **Annotation color** โ The color of dots, arrows, and rectangle outlines
- **Text color** โ The color of numbers and labels
Changes apply immediately to all annotations.
### Legend Panel
- **Drag** entries to reorder annotations
- **Double-click** a label to rename it inline (Enter to confirm, Escape to cancel)
- **Delete** button (trash icon) removes an annotation
- **Renumber** button re-sequences all annotations starting from 1
### Replace Image
Click **Replace Image** to swap the picture underneath the annotations โ for when the screen you documented has changed and you re-shot it. Pick the new image and every dot, arrow, rectangle and label stays, so you only fix what moved.
- **Same size as the old image** โ nothing moves. The annotations sit exactly where they were.
- **Different size** โ the annotations are scaled to the new image so they land near the same features and none end up off the edge, where you could not see or drag them. Nudge the few that missed.
Nothing is ever dropped, and the status line tells you which of the two happened. The new picture is written into the SVG when you save.
## Crop Mode
Click the **Crop** button to enter crop mode:
1. A crop rectangle appears with 8 resize handles (4 corners + 4 midpoints)
2. Drag any handle to resize the crop area
3. Drag inside the crop area to reposition it
4. Use the numeric X, Y, W, H fields for precise values
5. Click **Apply** to commit the crop, or **Cancel** (Escape) to exit
The crop area extends into the callout margin sidebar, and a darkened overlay shows what will be trimmed.
## Saving and Exporting
- **SVG** โ Saves the annotated image as SVG, overwriting the source file. The preview panel in MD DOCS refreshes automatically.
- **PNG** โ Exports the annotated image as a PNG file.
When you save in DocuMark, the parent MD DOCS document is automatically marked as unsaved (the save button turns orange) so you remember to save your markdown file too.
# Local Server Feature
MD DOCS includes a built-in local server that allows you to preview your HTML exports with full functionality, including embedded YouTube videos.
### How to Use
1. Open a project folder in MD DOCS
2. Click the **Globe** button in the preview panel header
3. A security warning will appear - click OK to continue
4. Your default browser opens to `http://localhost:8000`
5. Navigate to your exported HTML files
6. Click the green Globe button again to stop the server
### Benefits
#### Embedded Content Works
When you open HTML files directly from your file system (`file://` protocol), browsers block certain features for security reasons. The local server uses `http://` protocol, which allows:
- YouTube videos to play directly in the page
- External scripts and resources to load
- Iframe content to function properly
#### No Installation Required
The server is built into MD DOCS using Node.js - no external software needed. Unlike solutions that require Python or other tools, this works immediately.
#### Directory Browsing
When you start the server, you can browse all files in your project folder through the web interface.
#### Fast and Lightweight
The server runs in the same process as MD DOCS with minimal resource usage.
### Risks and Security Considerations
#### Network Exposure
When the server is running, files in your project folder are accessible to any device on your local network. This means:
- Other computers on your WiFi can access your files
- On a shared network (office, coffee shop, hotel), others could potentially view your content
#### Mitigation
- **Only run the server when you need it** - Stop it when done previewing
- **Avoid sensitive data** - Don't serve folders containing passwords, credentials, or private information
- **Be cautious on public networks** - Consider not using the server on untrusted networks
- The server only runs on `localhost:8000` by default, but other devices can still connect via your computer's IP address
#### What the Server CAN'T Do
- It cannot access files outside your project folder (directory traversal is blocked)
- It cannot execute code or modify files (read-only)
- It cannot install software or make system changes
- It stops automatically when you close MD DOCS
### Technical Details
- **Port**: 8000 (fixed)
- **Protocol**: HTTP (not HTTPS)
- **Scope**: Only serves files from the current project folder
- **Technology**: Node.js built-in `http` module
### Troubleshooting
#### "Port 8000 is already in use"
Another application is using port 8000. Close that application and try again, or restart your computer.
#### Server won't start
Check the View Log for error messages. Common issues:
- Firewall blocking the port
- Antivirus software interference
#### Browser shows "connection refused"
The server may have stopped unexpectedly. Click the Globe button to restart it.
# Recommended Workflow: The Google Docs Pipeline
Here is one use case of how MD DOCS can work in a Google Docs pipeline.
This workflow is the "Secret Weapon" of MD DOCS. It is designed for developers and content creators who manage multi-page documentation for products (such as software add-ons) and need a stable, professional way to publish to the web without building complex websites.
### The Problem
Many creators write in Google Docs because it is excellent for drafting. However, publishing directly from Google Docs is fragile. Google frequently changes its internal HTML code, which breaks custom parsers and scripts. Relying on Google's "Publish to Web" HTML often leads to broken formatting and constant maintenance headaches.
### The Solution: The Stability Pipeline
MD DOCS acts as the stabilization engine between your writing and your website. It allows you to write in Google Docs but publish with the stability and control of Markdown.
### Step 1: Author in Google Docs
Write your documentation in Google Docs. Enjoy the spell-check, collaboration, and familiarity. Even add in images and video links. When finished, export your document as Markdown (File > Download > Markdown).
### Step 2: Ingest & Rescue (The Critical Step)
Google Docs exports images as "Base64 encoded text"โgiant blobs of code that make files massive and hard to manage.
1. Open the exported `.md` file in **MD DOCS**.
2. Go to **More Options (โฎ)** > **Export Base64 Images**.
3. MD DOCS automatically extracts every image, saves them to a local `_images` folder, and rewrites the code to link to them correctly.
4. *Result:* A clean, lightweight Markdown file with standard image assets.
5. An added bonus is that MD DOCS will also convert you YouTube links to playable videos in your published online docs.
### Step 3: Clean & Format
Google Docs exports can sometimes strip paragraph formatting or mess up lists.
1. **Fix Text:** Use the **Sentences to Paragraphs** tool to instantly fix blocky text exports.
2. **Fix Tables:** If you have complex data, use MD DOCS' unique **HTML List** feature to put bullet points inside table cellsโsomething standard Markdown can't do.
### Step 4: Brand & Preview
Instead of relying on Google's default look:
1. Select the **Altuit** theme (or your own custom CSS) in the right panel.
2. This applies your product's specific branding, navigation styles, and colors immediately.
3. Verify everything looks perfect in the synchronized Live Preview.
### Step 5: Simple Hosting
Because MD DOCS generates standard HTML and CSS:
1. Click **Export** to generate the final HTML file.
2. Move the HTML file and its `_images` folder to any public web folder (e.g., a **pCloud Public** folder or a basic web server).
3. Your documentation is now live.
### Why This is Better
* **Stability:** Your documentation site will never break just because Google updated their code.
* **Control:** You control the styling via CSS themes, not Google's limited options.
* **Speed:** Pages load faster because images are optimized files, not embedded code blobs.
# Tips and Tricks
### Quick Access to Recent Files
Right-click the **Open** button to see your 10 most recently opened files.
### Open Themes Folder
Shift+click the refresh button in the preview panel to open the themes folder in File Explorer.
### View Application Logs
Click **View Log** in the status bar to see application logs for troubleshooting.
### Open Developer Tools
Shift+click the **View Log** button to open Chrome Developer Tools.
### Working with Many Open Documents
You can open as many documents as you like, but only about nine tabs fit across the bar at once.
1. **The document you are on** โ its tab is scrolled into view automatically, so it and its **โ** are always reachable, however many documents are open.
2. **The โ button and count** โ appears at the right end of the bar only once the tabs stop fitting. The number is how many documents are open.
3. **A document in the list** โ its name over its folder. Click the row to go to that document; hover it and a **โ** appears at the right of the row to close the document without going there first.
Past the point where the tabs stop fitting:
- **The document you are on is always in view.** Open a document or switch to one and its tab scrolls into view, so its close button is always reachable.
- **The โ button at the right end of the tab bar lists every open document**, with a count beside it. Click a document in the list to go to it, or click the **โ** on its row to close it without going there first. The button appears only when the tabs stop fitting.
- **Each row in the list shows the document's folder**, so two files with the same name are easy to tell apart. Hovering a tab or a row shows the full path.
Closing several documents in a row from the list leaves the list open. Closing one with unsaved changes closes the list first, so the save prompt is unobstructed.
### Clean Format
Select text and use More Options > **Clean Format** to turn copy pasted out of an AI chat into plain readable prose. Chat copy arrives wrapped at whatever width the window happened to be, carrying markdown, curly quotes, and often a pair of quotes around the whole thing.
1. **More Options (โฎ)** โ the toolbar button that opens the menu.
2. **Clean Format** โ the tool described here.
3. **Sentences to Paragraphs** โ its neighbour, covered [below](#sentences-to-paragraphs).
Clean Format:
- Strips markdown and HTML formatting โ bold, italic, headings, list markers, links (keeping the text), inline code
- Drops HTML comments, horizontal rules, and code fences (what is inside a fence is kept)
- Rejoins hard-wrapped lines, so each paragraph becomes one line again
- Removes quotes that wrap a whole paragraph, while leaving a quoted phrase inside a sentence alone
- Straightens curly quotes and apostrophes, and removes non-breaking and zero-width characters
Separate list items stay separate โ each becomes its own paragraph rather than running together into one sentence. Paragraphs stay separated by a blank line.
Ctrl+A first to clean a whole document. This is the tool to reach for when Clear Formatting leaves the text still broken across lines: Clear Formatting strips the markup but keeps every line break, and Clean Format also puts the lines back together.
### Sentences to Paragraphs
Select text and use More Options > "Sentences to Paragraphs" to convert a block of text into separate paragraphs (splits on periods, question marks, and exclamation points while preserving common abbreviations like "Dr.", "Mr.", "etc.").
### Clear Formatting
Select formatted text and click the **Clear Format** button to remove:
- Bold (`**`)
- Italic (`*`)
- Headers (`#`)
- Links (keeps text, removes URL)
- HTML tags
### File Tree Context Menu
Right-click any file in the DIR tab (the directory tree) to:
- Copy its relative path
- Open its containing folder
- Insert the path in your document (for images)
- **Add as local link** (for `.md` files) โ inserts a link to that document at your cursor (see [Linking Between Documents](#linking-between-documents))
# Troubleshooting
### Preview Not Updating
1. Check that scroll sync is enabled (lock icon)
2. Try clicking the refresh button in the preview panel
3. Check View Log for any errors
### Images Not Displaying
1. Ensure the image file exists at the referenced path
2. Use relative paths from your markdown file's location
3. Check that the `{filename}_images/` folder exists
### Theme Not Loading
1. Click the refresh button in the preview panel
2. Shift+click to open themes folder and verify the CSS file exists
3. Check that the theme CSS has proper metadata comments
### YouTube Videos Not Working
Videos display as thumbnails that open in your browser when clicked. This is by design for maximum compatibility.
### Scroll Syncing Stops Working
Toggle the scroll sync lock icon (top right of the preview panel) off and back on to reset synchronization.
# MD DOCS Web
MD DOCS Web is a lightweight, browser-based markdown editor that brings the core editing experience of the desktop app to any web browser. It requires no installation, no backend server, and runs entirely on the client side.
1. **Mode Tabs** โ Switch between Edit, Split, and Preview modes. On mobile (<768px), these become the primary navigation.
2. **File Operations** โ New, Open, URL (load from web address), and Save/Download buttons for managing documents.
3. **Theme Selector** โ All 10 desktop themes are available in the web version.
4. **Editor Panel** โ Full-featured text editor with syntax highlighting and line numbers.
5. **Preview Panel** โ Live-rendered HTML output using the same markdown-it engine as the desktop app.
## Accessing MD DOCS Web
Open the hosted version in any modern browser, or serve the files from any static web host. The app also supports loading documents directly via URL parameter:
```
https://your-host/md-docs/?url=https://example.com/document.md
```
## Features
MD DOCS Web shares the same markdown rendering engine and themes as the desktop version:
- **Live Preview** โ Split-view editor with rendered HTML preview side by side
- **11 Themes** โ All desktop themes available: Altuit, Altuit-TOC, Altuit-TOC-LG, Altuit-TOC-Light, Altuit-TOC-Sketchnote, Clean Light, GitHub Dark, GitHub Light, High Contrast, Modern Dark, and Notion
- **Mermaid Diagrams** โ Fenced `mermaid` code blocks render as interactive diagrams
- **Marp Slide Presentations** โ Documents with `marp: true` frontmatter render as stacked slide decks
- **YouTube Embeds** โ YouTube links convert to clickable thumbnail previews with inline playback
- **File Management** โ Open from device, open from URL, or save/download
- **Open from URL** โ Load any public `.md` file by pasting its URL:
- **Auto-Save** โ Content, filename, and theme preference are saved to browser localStorage
- **Keyboard Shortcuts** โ Ctrl+N (new file), Ctrl+S (save)
## Responsive Design
- **Desktop** (768px+): Split view with editor and preview side by side
- **Mobile** (<768px): Tab toggle between Edit, Split, and Preview modes
- Hamburger menu collapses toolbar actions on small screens
- Supports iOS home screen "Add to Home Screen" for app-like experience
## Desktop vs. Web Comparison
| Feature | Desktop | Web |
|---------|---------|-----|
| Platform | Windows/Mac (Electron) | Any modern browser |
| File Access | Full file system read/write | Device picker + downloads |
| Installation | Required | None โ open in browser |
| Themes | 10 themes | Same 10 themes |
| Markdown Engine | markdown-it | markdown-it (same) |
| Mermaid Diagrams | Yes | Yes |
| YouTube Embeds | Yes | Yes (inline playback) |
| DocuMark Annotations | Yes | No |
| MCP Server Integration | Yes | No |
| Multiple Tabs | Yes | Single document |
| TOC / File Tree Panel | Yes | No |
| Local Server | Yes | Not needed |
| Offline Support | Yes | Yes (runs locally) |
# Appendix A: MCP Server โ AI Assistant Integration
MD DOCS includes a built-in Model Context Protocol (MCP) server that allows AI assistants like Claude Code and Claude Desktop to programmatically control the editor. This enables AI-assisted documentation workflows such as creating, editing, and publishing markdown files without manual interaction.
## What is MCP?
The Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with external tools and services. MD DOCS implements an MCP server that exposes 33 tools and 7 resources, giving AI assistants full control over the editor.
## Architecture
The MCP server runs as a separate Node.js process that communicates with the running MD DOCS app via a local HTTP bridge on port 8321. The bridge is localhost-only โ there is no network exposure.
## Installation
### Step 1: Install MCP Server Dependencies
```bash
cd mcp-server
npm install
```
### Step 2: Ensure MD DOCS Is Running
The MCP server requires the desktop app to be running:
```bash
npm start
```
### Step 3: Configure Your AI Client
#### For Claude Code
Add to your `.claude/settings.json` (project or global):
```json
{
"mcpServers": {
"md-docs": {
"command": "node",
"args": ["D:/GitHub/md-docs/mcp-server/index.js"]
}
}
}
```
#### For Claude Desktop
Add to `%APPDATA%/Claude/claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"md-docs": {
"command": "node",
"args": ["D:/GitHub/md-docs/mcp-server/index.js"]
}
}
}
```
#### For Codex
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.md-docs]
command = "node"
args = ['D:\GitHub\md-docs\mcp-server\index.js']
```
**Codex also needs its sandbox opened, or every call is refused.** Codex's
sandbox gates the whole MCP channel, so at its default setting the MD DOCS
tools appear in the list but each call fails immediately with:
```text
user cancelled MCP tool call
```
Nothing was cancelled โ that is how Codex reports a sandbox refusal. Add this
near the top of `~/.codex/config.toml`, above the first `[section]`:
```toml
sandbox_mode = "danger-full-access"
```
Or pass `--sandbox danger-full-access` on a single run. Note the trade-off:
shell commands then run unsandboxed. There is no narrower setting that leaves
MCP working. Changing the approval policy does **not** help โ the sandbox is
the gate, not approvals.
> If a call returns **`fetch failed`** instead, the sandbox is fine and the
> call really ran โ MD DOCS just isn't open. Start the app.
This applies only to Codex used **outside** MD DOCS. The AI chat built into
MD DOCS already launches its agent correctly; see
[Chatting with an AI Agent](#chatting-with-an-ai-agent).
## Available Tools (34)
### File Operations
| Tool | Parameters | Description |
|------|-----------|-------------|
| `read_file` | `path` (string) | Read a text file from disk |
| `write_file` | `path` (string), `content` (string) | Write text content to a file |
| `list_directory` | `path` (string) | List files recursively as a tree |
| `file_exists` | `path` (string) | Check if a file or directory exists |
| `copy_file` | `source` (string), `destination` (string) | Copy a file from source to destination |
### Editor Operations
| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_editor_content` | (none) | Get the markdown content of the active tab |
| `set_editor_content` | `content` (string) | Replace the active tab's content |
| `replace_range` | `text` (string), plus `find` (string) **or** `startLine`/`endLine` (numbers) | Replace one span of the active tab in place โ the rest of the document (and its line endings) is untouched, the edit is undoable, and the tab is marked unsaved |
| `load_file` | `filePath` (string) | Open a file in a new editor tab |
| `save_file` | (none) | Save the active tab to its current path |
| `save_file_as` | `filePath` (string, optional) | Save the active tab to a specific path |
| `new_document` | (none) | Create a new untitled document tab |
| `refresh_file` | (none) | Reload the active file from disk |
### Tab Operations
| Tool | Parameters | Description |
|------|-----------|-------------|
| `list_tabs` | (none) | Get info about all open tabs |
| `switch_tab` | `index` (number) | Switch to a tab by zero-based index |
| `close_tab` | `index` (number), `save` (boolean, optional) | Close a tab, optionally saving first |
| `next_tab` | (none) | Switch to the next tab |
| `prev_tab` | (none) | Switch to the previous tab |
### Project Operations
| Tool | Parameters | Description |
|------|-----------|-------------|
| `open_project` | `folderPath` (string) | Open a folder as the active project |
| `get_project_info` | (none) | Get the project path, name, and file tree |
| `refresh_file_tree` | (none) | Re-scan the project directory |
### UI State
| Tool | Parameters | Description |
|------|-----------|-------------|
| `set_panel_mode` | `mode` ("md", "split", or "preview") | Set the editor layout mode |
| `get_app_state` | (none) | Get current UI state as JSON |
| `set_status_message` | `message` (string) | Display a message in the status bar |
| `dismiss_modal` | (none) | Dismiss any open modal dialog |
| `set_theme` | `theme` (string) | Set the preview theme by name or ID |
| `list_themes` | (none) | List all available preview themes |
### Export & Preview
| Tool | Parameters | Description |
|------|-----------|-------------|
| `export_html` | `outputPath` (string, optional) | Export the current preview as an HTML file |
| `get_preview_html` | (none) | Get the rendered HTML preview content |
| `export_base64_images` | (none) | Extract base64 images from the markdown |
| `publish` | (none) | Export to HTML+CSS and open in browser |
### Server Management
| Tool | Parameters | Description |
|------|-----------|-------------|
| `start_local_server` | `directory` (string, optional), `port` (number, optional) | Start the local HTTP preview server |
| `stop_local_server` | (none) | Stop the local HTTP preview server |
| `get_server_status` | (none) | Check if the server is running and its port |
## Available Resources (7)
Resources provide read-only access to MD DOCS state using the `mddocs://` URI scheme:
| URI | Type | Description |
|-----|------|-------------|
| `mddocs://active-file/content` | text/markdown | Markdown content of the active tab |
| `mddocs://active-file/info` | application/json | Active file metadata (name, path, dirty state) |
| `mddocs://tabs` | application/json | All open editor tabs |
| `mddocs://project/tree` | application/json | Project file tree structure |
| `mddocs://project/info` | application/json | Project metadata (path, name, version) |
| `mddocs://app/state` | application/json | Current UI state |
| `mddocs://app/log` | text/plain | Recent log entries (last 100 lines) |
## Port Configuration
The MCP bridge runs on port **8321** by default. This can be changed in `src/constants/config.js`:
```javascript
export const MCP_CONFIG = {
PORT: 8321,
HOST: '127.0.0.1',
RENDERER_TIMEOUT: 10000
};
```
The MCP server auto-discovers the port via a file written by the Electron app:
- **Windows:** `%APPDATA%\MD DOCS\mcp-bridge-port`
- **macOS:** `~/Library/Application Support/MD DOCS/mcp-bridge-port`
- **Linux:** `~/.config/MD DOCS/mcp-bridge-port`
## Troubleshooting
### "MD DOCS does not appear to be running"
Start the desktop app first with `npm start`. The MCP server requires the Electron app to be running.
### Port 8321 is already in use
Change `MCP_CONFIG.PORT` in `src/constants/config.js`. The MCP server will auto-discover the new port.
### Tools time out (10-second timeout)
If the app is loading or a dialog is blocking the UI, tools may time out. Dismiss any open dialogs and wait for the app to be idle before calling tools.
### Verifying the bridge is running
You can check the health endpoint directly:
```
GET http://127.0.0.1:8321/health
```
A successful response returns `{ "status": "ok", "version": "..." }`.
## About MD DOCS
**MD DOCS** - Edit Markdown Easily
ยฉ 2025-2026 Chipp Walters, Altuit, Inc.