MD-DOCS User Manual

Version 1.2.54
Created by Chipp Walters, Altuit, Inc.

A fast, modern markdown editor for Windows, Mac, and Linux.

Table of Contents

• Features
• Getting Started
  • Launching MD DOCS
  • Welcome Screen
  • Basic Operations
  • The Workspace Layout
• User Interface Overview
  • Editor Features
  • Preview Panel
  • Themes
  • Working with Images
  • Working with Tables
  • In-Document Anchor Links
  • Linking Between Documents
  • YouTube Videos
  • Mermaid Diagrams
  • Marp Slide Presentations
  • Keyboard Shortcuts
  • Preferences
• DocuMark — Image Annotation Editor
  • Opening DocuMark
  • Annotation Tools
  • Crop Mode
  • Saving and Exporting
• Local Server Feature
• Recommended Workflow: The Google Docs Pipeline
• Tips and Tricks
• Troubleshooting
• MD DOCS Web
  • Accessing MD DOCS Web
  • Features (Web)
  • Responsive Design
  • Desktop vs. Web Comparison
• Appendix A: MCP Server — AI Assistant Integration
  • What is MCP?
  • Architecture
  • Installation
  • Available Tools (33)
  • Available Resources (7)
  • Port Configuration
  • Troubleshooting (MCP)
  • About MD DOCS

Features

MD DOCS is an advanced Markdown editor designed specifically to bridge the gap between content creation and publication. It combines a modern writing environment with unique utilities for cleaning up imported documents.

🚀 Workflow & Cleanup Tools (Unique Features)

• Google Docs to Markdown Rescue: Automatically extracts Base64 encoded images from imported files (like those from Google Docs) and saves them as local files, drastically reducing file size.
• Smart “Sentence-to-Paragraph” Conversion: Rapidly converts blocks of sentences into distinct paragraphs—essential for fixing formatting issues often found in voice-to-text or PDF exports.
• Advanced Table Formatting: Overcomes standard Markdown limitations by allowing you to embed HTML lists, breaks, and multiple lines directly inside table cells.
• CSV / TSV to Table: Import a .csv/.tsv file or paste clipboard data to drop in a clean markdown table — comma/tab auto-detected, RFC 4180 quoting handled. See Insert CSV as Table.
• Integrated Local Server: Launches a built-in HTTP server to properly test YouTube embeds, JavaScript, and forms before publishing.

📝 Editing & Preview

• Synchronized Live Preview: A WYSIWYG side-by-side display that locks scrolling, ensuring your editor and preview are always on the same line.
• Multiple Document Support: You can open as many .md documents as you like. Each has it’s own tab.
• TOC: The table of contents expands and collapses to allow for quick navigation to the section you are interested in.
• Files: The Files list shows all of the file and folders in the current directory you are working in. You can launch files and even copy links.
• Professional Theming: Includes multiple Markdown-to-HTML themes (including the custom “Altuit” branding). Themes are CSS-based and fully customizable.
• Smart YouTube Embedding: Correctly embeds YouTube videos as lightweight, clickable thumbnails that play in the browser, preventing page bloat.
• In-Document Anchor Links: Auto-generates slug IDs for every heading and provides a Link button picker so you can jump between sections of a document with one click. See In-Document Anchor Links.
• Link Between Documents: Right-click any .md file in the DIR tab to drop in a link to it. Clicking the link in the preview opens that document, and Export to Browser rewrites the links so they keep working in the published HTML. See Linking Between Documents.
• Double-Click to Source: Double-click any word in the preview to jump the editor straight to it. See Jump to Source.
• Built-in Spelling Checker: Ensures your documentation is error-free.

🛠️ Core Utilities

• Comprehensive Toolbar: One-click access to formatting, tables, code blocks, and media insertion.
• Cross-Platform: Full compatibility for Windows, Mac, and Linux environments.
• Developer Support: Backed by complete documentation and support from a developer who has sold over 100,000 software products.

Getting Started

Launching MD DOCS

Launch the application by double-clicking the executable. You can also double-click any .md file directly if you have set up file associations.

Linux Installation

For Linux, download the portable ZIP and extract it. Then run the included install script to set up desktop integration:

bash install.sh

This sets execute permissions on the app binary, creates a launcher script, and adds MD DOCS to your application menu with its icon. See README_LINUX.txt in the ZIP for troubleshooting and uninstall steps.

Welcome Screen

When you first launch MD DOCS, a welcome screen appears.

1. MD DOCS logo — Confirms the app and its tagline, “Edit Markdown Easily.”
2. New / Open buttons — Start a new document or open an existing .md file right away.
3. Recent Files — Your most recently opened files; click any entry to open it immediately.

The welcome screen appears whenever no documents are open.

Basic Operations

📂 Opening a File & Project

1. Click the Open button in the toolbar.
2. Select any markdown (.md) file.
3. Important: The folder containing your file becomes your Active Project. This is critical for features like the local server and image handling to work correctly.

📄 Creating a New Document

1. Click the New button in the toolbar.
2. Choose a destination folder and filename.
3. Your new document opens immediately, ready for editing.

The Workspace Layout

MD DOCS features a synchronous four-panel layout designed to keep your writing and preview in perfect sync.

┌─────────────────────────────────────────────────────────────┐
│  Toolbar: New, Open, Save, Save As, Refresh, Prefs, Help    │
├─────────┬───────────────────────────┬───────────────────────┤
│         │  Tab Bar                  │  Theme Selector       │
│  TOC    ├───────────────────────────┼───────────────────────┤
│   or    │                           │                       │
│  Files  │  Markdown Editor          │  Live Preview         │
│  Panel  │                           │                       │
│         │                           │                       │
├─────────┴───────────────────────────┴───────────────────────┤
│  Status Bar: Folder | Filename | Unsaved indicator | Log    │
└─────────────────────────────────────────────────────────────┘

1. Left Sidebar (Navigation)

• TOC (Table of Contents): Auto-generates a navigation tree from your document’s H1–H4 headings. Click to jump instantly to sections.
• Files: Displays your Active Project folder. Click any .md file to open it in a new tab, or right-click to copy paths.

2. Center Panel (The Editor)

• Monaco Editor: A professional-grade editor (powered by VS Code technology) featuring syntax highlighting and command shortcuts.
• Tab Bar: Manage multiple open documents. A blue dot on the tab indicates you have unsaved changes.

3. Right Panel (The Result)

• Live Preview: Real-time rendering of your HTML output.
• Theme Selector: Instantly switch between built-in themes (like Altuit, GitHub, or Notion) to see your content in different styles.

4. ####Status Bar

• Located at the bottom, this displays your current folder context, filename, and the View Log button for troubleshooting.

User Interface Overview

Header	Description
	Opens a new non-saved document in a new tab.
	Opens an .md document in a new tab. Right-click to see the most recent open versions.
	Saves existing tab. Will turn orange if there have been changes and it needs to be saved.
	Saves As a different md file for the existing tab.
	Refreshes .md from local storage.
	Opens the Preferences dialog to configure app theme, editor font size, spell check, browser path, and file consolidation on Save As.
	About and Help dialog with link to documentation.

Left Panel	Description
	Table of Contents shows H1, H2, H3 and H4 items for .md . Small button on right expands all and contracts all.
	Files area that shows the folder the .md file resides in. Just below is the folder path and clicking on the folder icon opens the folder.

Toolbar	Description
	Bolds selected text.
	Italicized the selected text.
	Highlights the selected text with <mark> and </mark>. Removed using Clear format button.
	H1, H2, H3 headings for selected text.
	Create bullet and numbered lists for selected paragraphs.
	Create a URL link for the selected text. With text selected, opens a picker for pasting a URL or choosing an in-document anchor (heading or custom <a id="...">). See In-Document Anchor Links.
	Create blank table markdown.
	Loads an image from a file requestor. It then copies the image to a folder (with the same prefix) next to the .md file so that all referenced images are stored in the same place.
	Paste image from clipboard: prompts for name (no extension) and then saves image to a folder it creates (if necessary) at the root directory of the original file.
	Create a code block for the selected text. A code block using a monospaced font and has a dark region. Good for code, ascii tables, ascii diagrams.
	Create blank YouTube video markdown.
	Adds a hard return “<br>” so that you can force paragraphs in table cells. Also good for positiong in text like this new line.
	Removes all markdown formatting and custom list HTML from selected text.

Special

Description

Special features menu: Find and Replace Paste as Markdown (Ctrl+Alt+V) — Pastes clipboard content and converts it to clean Markdown formatting. Export Base64 images: When Google Docs exports to Markdown, it embeds the images as base64 encoded text, which makes the md file very large. This feature saves all those images from the md to a file and then removes the base64 encoded text from the md file. Converts sentences to paragraphs using the “.” (period) delimeter. Useful for creating lists from sentences which happens often when Google Docs exports Markdown. HTML Bullet list and HTML Numbered list funtions are helpful when you want to create a list inside a table cell. Markdown does not support paragraphs (line feed or cr) in a cell so use these and \ to create them. These use html to create the lists so there are no paragraphs. Use the Clear formatting button to revert. Mermaid Diagram — Inserts a fenced mermaid code block template for creating diagrams (flowcharts, sequence diagrams, etc.) that render visually in the preview. Line Numbers — Toggles line numbers on or off in the editor gutter. When enabled, line numbers appear on the left side of the Monaco editor. The setting is indicated by a checkmark (✓) in the menu and persists across sessions.

Themes	Description
	MD DOCS comes with several themes that convert Markdown to HTML. These are handy for review purposes, and can also be hosted on file sharing systems like pCloud. Just send people the URL of the resulting HTML file and they will see a fully rendered version of the Markdown file.
	The theme refresh button is used when modifying or creating your own CSS md theme. You can edit or add themes in your MD DOCS-win32-x64\resources\public\themes folder from where you install your MD DOCS application. Shift+click the refresh button in the preview panel to open the themes folder in File Explorer.

Preview	Description
	Previews the rendered HTML in the default browser (or the browser specified in Prefs). When pressed, it generates a same named .html file in the same directory as your .md document and then launches the browser window. If you want to share your html file on a server, you’ll need to make sure all of your images are referenced locally.
	Toggles on and off a local server (if installed). This allows testing of javascript includes, links, and YouTube videos among other things. Only use this if you need this function, other wise the preview button should work just fine. When the server is on, the world icon is green— when off it is disabled. Note: server will automatically shutdown when the app is closed. To operarte: Try the button to see if your computer is already configured to run the server. If configured properly, it will launch the server and load the root page of the folder the current .md file is saved at. If not configured, it will show a dialog telling you so. See appendix for information on how to install a server.
	Locks and unlocks synchronized scrolling.

Footer	Description
	The folder that the current .md file is in an the name of the current .md file.
	Status messages.
	View Log button. MD DOCS creates logs for each session and then erases them the next session. These are helpful for debugging purposes.
	Version information.

Recent Files

Right-click the Open button to see your 10 most recently opened files.

Multiple Tabs

• Open multiple files simultaneously
• Click a tab to switch files
• Middle-click or click the X to close a tab
• Blue dot on tab indicates unsaved changes

Editor Features

Monaco Editor

MD DOCS uses the same editor as VS Code, providing:

• Interactive spell checking (can be toggled in Preferences)
• Syntax highlighting for markdown
• Find and Replace (Ctrl+F, Ctrl+H)
• Word wrap (enabled by default)
• Bracket matching
• Configurable font size

Scroll Sync

The editor and preview panels stay synchronized as you scroll. Toggle this feature with the lock/unlock button in the preview panel header.

Preview Panel

Theme Selector

Choose from several built-in themes:

• Altuit - Dark theme with orange accents (recommended)
• Altuit-TOC - Dark theme with collapsible sidebar table of contents
• Altuit-TOC-LG - Large-format TOC variant with bigger fonts and wider line-height for blog readability
• Altuit-TOC-Light - Light variant of the Altuit-TOC theme
• Altuit-TOC-Sketchnote - Hand-drawn sketchnote style using Comic Neue and Fredoka One fonts on a soft green background (light-only, no dark mode)
• Clean Light - Minimal light theme
• GitHub Dark - GitHub-style dark theme
• GitHub Light - GitHub-style light theme
• Modern Dark - Sleek dark theme
• Notion - Notion-inspired styling

Jump to Source (Double-Click)

Double-click any word in the preview to jump straight to it in the editor. MD DOCS scrolls the editor to that word, selects it, and briefly flashes the line in blue so it’s easy to spot. When the same word appears more than once in a block, MD DOCS counts the occurrence under your cursor so it lands on the right one.

Preview Controls

Export to Browser

Click the export button to:

1. Generate an HTML file with your content
2. Generate a CSS file with theme styling
3. Open in your default browser (or configured browser)

Files are saved as {filename}.html and {filename}.css in your project folder.

Themes

Using Themes

1. Select a theme from the dropdown in the preview panel
2. Your selection is remembered between sessions
3. Themes affect both the in-app preview and browser export

Theme Tag for Browser Export

You can set a default theme for browser export by adding a tag at the top of your markdown file:

When this tag is present and you export to browser using the Altuit-TOC theme, the page will default to the light color scheme instead of dark. The whitespace after the colon is optional. Note: place the tag at the very top of your markdown file, before any content.

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:

/**
 * @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
3. The image is copied to a {filename}_images/ folder
4. A markdown reference is inserted: ![alt](path/to/image.png)

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 image files from the Files panel:

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:

| 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:

<ul><li>Item 1</li><li>Item 2</li></ul>

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:

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:

<a id="my-spot"></a>

Then link to it like any other anchor:

[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:

[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.

Manual Typing

You can always type anchor links by hand using the slug rule above:

[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, 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:

[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).

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:

[![Video Title](https://img.youtube.com/vi/VIDEO_ID/0.jpg)](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:

```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 <br>)
• 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

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:

---
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:

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:

![bg](image.jpg)              <!-- Full background -->
![bg right](image.jpg)        <!-- Background on right half -->
![bg left:40%](image.jpg)     <!-- Background on left 40% -->
![bg opacity:0.3](image.jpg)  <!-- Semi-transparent background -->

Auto-fit Text

Use the <!--fit--> comment inside a heading to scale text to fill the slide width:

# <!--fit--> This text fills the width

Math Equations

Marp supports LaTeX math via MathJax. Enable it in frontmatter with math: mathjax:

---
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

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: ![width:350px](image.jpg) or ![height:7cm](image.jpg)
• Syntax-highlighted code blocks work the same as regular Markdown

Keyboard Shortcuts

File Operations

Editing

Navigation

DocuMark

Preferences

Open preferences by clicking Prefs in the toolbar.

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.

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:

• 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

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.

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)

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
• 10 Themes — All desktop themes available: Altuit, Altuit-TOC, Altuit-TOC-LG, Altuit-TOC-Light, Altuit-TOC-Sketchnote, Clean Light, GitHub Dark, GitHub Light, 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

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

cd mcp-server
npm install

Step 2: Ensure MD DOCS Is Running

The MCP server requires the desktop app to be running:

npm start

Step 3: Configure Your AI Client

For Claude Code

Add to your .claude/settings.json (project or global):

{
  "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):

{
  "mcpServers": {
    "md-docs": {
      "command": "node",
      "args": ["D:/GitHub/md-docs/mcp-server/index.js"]
    }
  }
}

Available Tools (33)

File Operations

Editor Operations

Tab Operations

Project Operations

UI State

Export & Preview

Server Management

Available Resources (7)

Resources provide read-only access to MD DOCS state using the mddocs:// URI scheme:

Port Configuration

The MCP bridge runs on port 8321 by default. This can be changed in src/constants/config.js:

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.