Seamless Markdown

A Markdown editor for VS Code that removes the need for a separate preview. You edit one document and choose how much of the syntax you want to see.

Switching modes is instant and keeps your place. The mode is remembered per file.

In half preview, the element under the cursor shows its Markdown. Here the cursor is in the image path, and the image stays visible:

Tables are edited in place, with a bar for rows, columns and alignment:

Full preview hides all syntax; links and images are edited in a popover. It follows your colour theme:

The file on disk is always plain Markdown. The editor never rewrites text you did not touch: opening and saving a file leaves it byte for byte the same. The only reformatting it does is to re-align the pipes of a table whose cell you edited (this can be turned off).

Getting started

1. Install the packaged extension:

   code --install-extension seamless-markdown-0.1.1.vsix
   

2. Open a Markdown file, then click the preview icon in the editor title bar, or run Seamless Markdown: Open with Seamless Markdown from the Command Palette.

3. To use it for every Markdown file, run Seamless Markdown: Use as Default Editor for Markdown. Seamless Markdown: Stop Using as Default Editor reverts this.

The extension never becomes the default by itself, and it is not used in diff views.

To try it without installing, run it from this folder:

code --extensionDevelopmentPath="$PWD" sample

Features

• Formatting: bold, italic, strikethrough, inline code, headings, bullet, numbered and task lists, quotes, code blocks, links, rules. By typing Markdown, by shortcut, or from the toolbar.
• Tables: rendered as a grid in both preview modes. Click a cell to edit it. Tab and Shift+Tab move between cells, Enter moves down, and both add a row at the end. Arrow keys move in and out of the table. A small bar above the table inserts, deletes and moves rows and columns, sets column alignment, and shows the table's Markdown source.
• Images: shown inline, with relative paths resolved from the document. Paste an image from the clipboard or drop one in and it is saved to an assets folder next to the document and linked. Dragging a file from the Explorer links it without copying (hold Shift while dropping, as VS Code requires). File paths are completed as you type the target of a link or image.
• Slash menu: type / at the start of a line to insert a heading, list, quote, code block, table, image, link or divider.
• Smart paste: pasting a URL over selected text makes a link; pasting cells copied from a spreadsheet makes a table.
• Links: Cmd/Ctrl+click opens web links in the browser, relative .md links in this editor, and #heading links jump within the document.
• Task lists with clickable checkboxes, GitHub alerts (> [!NOTE]), code blocks with syntax colours and a copy button, front matter shown as a tidy block.
• Find and replace, Go to Heading, folding of the section under a heading (hover a heading and click the arrow in the margin), word count and reading time in the status bar.
• Follows the VS Code colour theme, and works with undo, redo, save, hot exit, split editors and source control exactly like a text file, because it edits the same text document.

Shortcuts

Mod is Cmd on macOS and Ctrl elsewhere. All of them apply only while this editor has focus and can be changed in Keyboard Shortcuts.

Mod+K is not used for links because it starts VS Code's two-key shortcuts.

Settings

Known limitations

• VS Code does not offer the Outline view, breadcrumb symbols or its own find widget to custom editors. Use Go to Heading and the built-in find panel instead.
• HTML is shown as source. <img> tags get an image preview next to them. Mermaid diagrams and math are not rendered.
• Tables that are indented or sit inside a list or quote are shown as source.
• In full preview, a reference-style link ([text][label]) shows its target read-only; edit it in half preview. An empty code block cannot be entered with the arrow keys; use the toolbar button, which puts the cursor inside.
• Typing is sent to VS Code in short bursts so that one burst is one undo step. If you have both files.autoSave with a delay and files.trimTrailingWhitespace on, a trailing space can be trimmed while you pause in the middle of a sentence, because VS Code cannot see the cursor of a custom editor.
• Very large documents (several thousand lines) are slower to type in for the first few seconds after opening, while the document is still being parsed.

Development

npm install
npm run build              # bundles into dist/
npm test                   # unit tests
npm run test:integration   # runs the editor inside a real VS Code
npm run package            # produces the .vsix
npm run screenshots        # regenerates the icon and README images

npm run harness serves the project on port 5173. http://localhost:5173/harness/index.html?doc=features.md&mode=half&theme=dark runs the editor in a plain browser against a stand-in for the extension host, which is the quickest way to work on rendering.

How it is put together:

• src/extension is the extension host side: a CustomTextEditorProvider, document sync, image and link handling, commands.
• src/webview is the editor: CodeMirror 6 with the Lezer Markdown parser. The three modes are three levels of decoration over the same text, so nothing is ever converted to another format and back.
• src/shared holds the message protocol between the two.

Checks that still need a person

The automated tests cover document sync, undo and redo, CRLF files, split editors, CSP, image saving and link handling inside a real VS Code. These need a human at the keyboard:

• Mod+B formats text and does not toggle the side bar; Mod+S saves; Mod+Z undoes one burst of typing.
• Pasting an image from the clipboard and dropping one from the desktop with Shift held.
• The look of the editor in your own colour theme.

Credits

Built on CodeMirror 6 and Lezer, both MIT licensed. See THIRD-PARTY-NOTICES.md.