Sublime Forum

Provide Markdown Preview mode using folded source and phantom

#1

I’d like to know whether it makes sense to provide a new markdown preview mode. A new plugin to hide the Markdown source and display a rendered preview in the same Sublime Text tab view. It’s similar to vscode markdown preview mode.

Idea is from the gbird’s post . This approach is to provide formatted Markdown preview directly inside the original Sublime Text view. It preserves the markdown source in the text buffer, but fold and hide it temporarily and replacing its visual presentation with a read-only minihtml phantom.

The design is simple:

…folded Markdown source…
┌────────────────────────────┐
│      Phantom Preview       │
└────────────────────────────┘

And user can toggle the phantom review by some kind of button or command.

The screenshot here has folded source code and use minihtml to render a markdown preview.

preview%20demo
preview demo.png1936×1284 418 KB

Folding the markdown source isn’t elegant. But could provide a way to display the preview over the original source code without making major changes.

The extension: https://github.com/flashmodel/MarkdownPreviewOverlay

0 Likes
Back to Sublime Text 4 with Agentic Coding
#2

I can certainly see value in this, esp. when it comes to visual presentation of complex layout like MD tables.

One thing that VSCODE does well is the live side-by-side preview of MD documents. This might bridge the gap somewhat, although it might add some friction, with toggling between “Edit Source” and preview.

It might be better as a separate column/view, so you could get a true live-as-you-type preview.

But I wouldn’t use me as a case-study - my practices are very highly tuned for the work I do (create eLearning content for LMS systems like Moodle).

Locally I have sorted this problem with a modified version of OmniMarkupPreviewer, which I had to re-tool for py3.14 support.

This combo works really really for me, as I use a lot of HTML snippets that include Bootstrap for layout. This way, I get a true, live in the browser rendering, which I fully appreciate is a very niche set of requirements and beyond any rational expectation of an editor.

image
image.png4750×1629 2.39 MB

0 Likes
#3

This is really interesting. I like the idea of keeping the actual content in the buffer while using phantoms as a presentation layer.

Do you see this approach as something that could be useful beyond Markdown preview? I’m wondering how far phantoms could be pushed as a general presentation layer for plugins, rather than specifically for Markdown.

0 Likes
#4

Given ST’s minihtml engine which drives phantoms, popups or HtmlSheets is rather limited with regards to create arbitrarily complex layouts. It is only a basic subset of html/css and thus may not be ideal for all use cases.

Instead of using phantoms in the same view a dedicated HtmlSheet displayed side-by-side would maybe be more useful as it doesn’t disturb or interact with the text in possibly unwanted ways.

MarkdownLivePreview makes use of this approach.

0 Likes
#5

Other plugins already provide side-by-side previews. The goal of this new markdown preview is to avoid opening a separate window. It instead allow users to quickly switch between the source and preview directly within the current file tab.

The HTML rendering does not need to achieve the full appearance of a web page.

table-phantom
table-phantom.png1586×1550 295 KB

This is an example of markdown table. It simply uses alignment and adjusts to the width of the window.

0 Likes
#6

I’ve put together a working PoC extension that renders the markdown preview directly inside the active file tab (by folding the source and displaying rendered HTML via phantom).

https://github.com/flashmodel/MarkdownPreviewOverlay

It provides an inline, in-tab reading experience without having to open a separate browser tab or split pane.

md_preview
md_preview.gif2098×1436 740 KB

Before taking it further, I’d appreciate any suggestions. Is this something you would find useful in practice, or prefer existing split-pane preview

0 Likes
#7

I think it is useful, not necessarily for the whole document but for “hard to decipher” parts of a document, and eg. to check if I’ve written these parts correctly.

I usually don’t need a preview as long as the markdown is simple. (And I’m not a technical writer.) But a quick check section for section would be top.

(I would love this for rst because its syntax is a bit different; and switching between markup lang you always get them wrong until memory kicks in again. Even links are hard as everyone does them a bit different.)

1 Like
#8

Bringing this to .rst is a great idea—rst syntax is easy to mix up when switching between markup languages.

In-editor overlay preview would be helpful for verifying syntax quickly without breaking workflow

section-by-section preview is a bit complex from the implementation standpoint. Handling partial sections and source ranges can be difficult to toggle preview action.

0 Likes
#9

Updates on MarkdownPreviewOverlay: just added automatic scroll synchronization between edit mode and preview mode.

Previously, entering preview mode on a long file always stay at the very top, forcing you to manually scroll down to find your place.


Now whenever you switch to preview mode, the overlay automatically scrolls to the corresponding section you are currently viewing in the source buffer. Switching back to edit mode similarly restores your previous cursor position and viewport.

output
output.gif2064×1344 817 KB

While this estimation of minihtml height isn’t perfect, it gets you very close to where you were and saving you from scrolling from top on long documents. Markdown authors can frequently toggle preview to inspect a specific table or code block, matching the position where you were working.

1 Like
#10

I just wanted to remind you of that. I think it is crucial UX to scroll the viewport here. Still, not easy to use just the keyboard. Personally, I have scroll key bindings but I think these are custom plugins of mine. So the UX for other users might be worse if only mouse scrolling is available.

I still think a render per block would – for this kind of plugin – be a good try. Eg each block gets when the cursor is in it a preview button (easy for reading and when I’m on mymouse), or I bind ctrl+h (whatever of course) for the preview toggle and have the cursors pretty much intact.

I’ve also seen rendering the whole document at once but divided in one phantom per block. Then you still have the cursor as well and moderately normal movements.

Iff you render the whole document, you can likely say that this is an editor mode. Hence, tag the view for that mode, then bind and implement movement on your own. Also e.g. enter to exit the mode etc.

In fact, I could do that just using key bindings I guess if you tag the view as “in_preview_mode”.

0 Likes
#11

“This approach is to provide formatted Markdown preview directly inside the original Sublime Text view.”
I know that everyone is trying to squeeze Markdown and Preview into a competing, crowded x,y constraint. But unless you want to see Preview whilst typing does not the possibility of using z plane attract? For example a stack of switchable windows? Flaggers are not welcome. I keep my against the grain experiments now in a datavault.

0 Likes
#12

Sublime normally runs move text command to move the text cursor.

Instead of letting move run, the plugin intercepts it and dynamically converts it into a viewport scroll command with scroll_lines. By shifting the viewport, the preview phantom scrolls across the screen rather than the cursor.

0 Likes