Help test and implement the markdown custom editor preview

[mjbvz]

Background

Users would like the markdown preview to be opened when they open a markdown file. Feature requests #2766 and #54776 track a few different use cases, but the main one we are interested in right now is: when I open a markdown file, instead of opening the normal text editor, the markdown preview is opened instead.

This can now be implemented using custom editors: #77131

Current Status

The current insiders (1.41) contributes a custom editor for the markdown preview. It is not enabled by default by can be selected by running View: Reopen with with a markdown file open. You can also use the following setting to always open markdown files in preview mode instead of in the editor:

"workbench.editorAssociations": [
    {
        "viewType": "vscode.markdown.preview.editor",
        "filenamePattern": "*.md"
    }
]

The custom editor should look identical to the existing markdown preview.

How to help

The markdown custom editor needs testing and polish before it can be shipped. We are looking for the community to drive this. I've created this issue to collect feedback and discussion of this work.

Before we ship this feature, we need to make sure that custom editor based previews work as existing VS Code users would expect and work with the existing markdown preview's behavior and settings. This issue is intentionally open ended. Try playing around with the custom editor based markdown preview and exploring what works as expected and what doesn't

Some starting areas to focus on:

• How do custom editor based previews Integrate with existing markdown previews?
• Switching editors.
• Scrolling.
• Links. (For example, where do links open?)
• Markdown security settings.

[jcgerhard]

Expression of thanks

First of all: thank you very much for taking this feature request serious and starting first attemps implementing it!
It goes exactly in the direction I had in mind when I created the (currently closed) request #82331!

Experimental Setup

System

• Operating System: Mac OS 10.14.6 (Mojave)
• Hardware: MacBook Pro (15-inch, 2017)

Settings

For setting it up as realistic as possible - in relation of how I am using markdown files every day - I created an example "wiki" that I would like to use as a place for every-day note-taking and as a knowledge-base. I had also enabled the custom editor settings permanently by adding...

"workbench.experimental.editorAssociations": [
    {
        "viewType": "vscode.markdown.preview.editor",
        "filenamePattern": "*.md"
    }
]

...to the user setting.json.

Opening markdown files

It does exactly what it should: opening markdown files directly in preview mode! Perfect! At this (early) point it is already possible to read through my notes in a "wiki-style" way...just click and read without an additional distracting source-code view.

Links. (For example, where do links open?)

I linked my example markdown files with...

• internal Links like [Go to header *](#header)
• "among-each-other" Links like [Go to file *](file.md)
• and something like [Go to files' header](file.md#header)

I also added external links and images.

The result is what I expected...

• Internal links will jump to the section in the current window
• among-each-other Links will open the linked file in the current window
• External links will open in the systems' default browser
• Images are shown as expected

This behavior should not be changed. This way you can read through (a collection of) markdown files like reading a book without distracting new windows popping up every time you click on another file.

Switching editors

This is not implemented yet. Switching editors - meaning switching between view and edit mode - should be realized with keyboard shortcuts. For example we could use...

• CMD+E = Toggle edit mode
• CMD+S = Save and automatically toggle back to view mode

Toggling between modes should take place in the same current window. This way you'll get a smooth create-read-modify experience. For references have a look at typora.io or notable.md where this is perfectly implemented.

As an alternative, toggling to edit mode could open the well-known side-by-side preview mode. When saving the changes (by pressing CMD+S) the side-by-side view closes and you'll have only the preview mode again.

Outline View

The outline view in the sidebar has no entries at the moment. This should be visible in the same way as it is when one is editing a markdown file in source mode. This could be a good way to have a table of content.

I hope this first brief testing experience could help you with upcoming attemps for implementing this highly desirable feature.

[mjbvz]

Thanks. Can you please split individual problems to separate issue so we can track them better (link them back to this issue).

Also note that I am looking for the community to implement this, so please submit PRs with fixes if you want to see this stabilized.

[sverg1]

@mjbvz @jcgerhard I am considering tackling the editor toggle; this will be my first dive into open-source and could use a quick pointer as to where I should be looking! I have the preview Markdown editor up and running on my fork, but where may I look in src? I can make and link an issue once I get my bearings.

[mjbvz]

@sverg1 This should likely not be a markdown specific command but a generic for custom editors. Something like: toggle custom editor that would switch between VS Code's standard text editor and the custom one (i.e. the markdown preview)

Here's where the custom editor commands live:

vscode/src/vs/workbench/contrib/customEditor/browser/commands.ts

Line 60 in 27a33ee

const REOPEN_WITH_COMMAND_ID = 'reOpenWith';

The ICustomEditorService and IEditorService should have the functionality you need to implement this:

• Getting the currently active editor.
• Switching it to the custom editor or to the default text editor.

Since this change would be going into core VS Code, it should not hardcode anything markdown specific

[msindone]

@mjbvz @jcgerhard Is help still wanted on the Outline View? This would also be my first dive into open source, so I was wondering if this would be a good task to work on and if I could have quick pointer as to where I should be looking in src? I have the preview Markdown editor up and running on my fork. Thanks!

[thadras]

Usage notes of odd and errant behavior when double clicking within an md file
that has been opened within a preview viewport.

Given that the Markdown extension allows clicking links of other md files to open the target file, such is done within the tab of the referrer. Whereas, one might suspect another tab would have been opened to preview the target file.

Further, when double-clicking regular text within the file's preview, rather than open a tab with an editor view, the application throws an error:

  ERR Failed to show text document file://<currently-previewed>.md, should show in editor #undefined: Error: Failed to show text document file://<currently-previewed>.md, should show in editor #undefined
	at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\services\extensions\node\extensionHostProcess.js:641:878

Also, the scroll position of the preview tab does not persist after changing away from, and then returning to the tab, as the above mentioned reference links to a known issue.

Otherwise, the experimental feature works as expected.

[s1-en]

I want to report that Markdown files opened by default in the preview that have links that point to other Markdown files do not seem to load the other file. No matter how many times I click the link just wouldn't work.

However, if I double-click the preview (hence entering edit mode) and then open up the preview again from the icon in the top right, then the links work fine.

[jcgerhard]

I can confirm what @s1-en described. Could this be fixed? Links only working in edit mode...NOT in preview mode!

[jasonwilliams]

Hey @mjbvz i really like this, does this work on stable VSCode? I can see the View: Reopen with option that does work, but that config doesn't work in the settings.json.

I agree with @jcgerhard there needs to be some variable bindings to switch back and forth between preview and code.
But apart from that, what's holding this up?

[mjbvz]

Yes it should work in stable but the setting is no longer experimental

Still waiting for community help with the know issues, such as saving and restoring scroll position

[jasonwilliams]

Thanks. Can you please split individual problems to separate issue so we can track them better (link them back to this issue).

Also note that I am looking for the community to implement this, so please submit PRs with fixes if you want to see this stabilized.

I agree, a lot of fixes here can be broken up.
@mjbvz can I make an issue for toggling preview/editing mode with a keybinding? (in the background this would call View: Reopen with). This sounds like it could be done in isolation

[jasonwilliams]

CMD+E = Toggle edit mode

CMD + E is already assigned to "Find with selection" We would need another shortcut that lets you toggle between edit mode and preview. Suggestions welcome.

"ctrl + cmd + p" could work

[jasonwilliams]

As per @mjbvz advice I've created a scoped-down issue which just focuses on being able to toggle back and forth from the custom editor to the normal one.

#113298

@mjbvz do you know how hard/easy it is to keep state so when opening a new document you're still using the custom editor of vice versa?

[ssmooncoder]

Find widget Cmd/Ctrl + F doesn't seem to work in preview.

[ssmooncoder]

vscode/extensions/markdown-language-features/src/features/previewManager.ts

Line 78 in 6533d46

this._register(vscode.window.registerCustomEditorProvider(this.customEditorViewType, this));

Passing webviewOptions: {enableFindWidget: true} as the third param seems to fix this problem.