Support for MyST

[alcarney]

MyST is a flavour of markdown that is compatible with Sphinx. It should be possible to add just by calling out to the existing directive/roles logic where applicable

[haiyangToAI]

Hi @alcarney,

I like the idea of Esbonio to support Sphinx directives and roles for MyST/Markdown files. It will be helpful.

Directives and roles in MyST/Markdown look like this, see MyST Docs:

• directive patterns:

  • Using YAML frontmatter for directive options:

     ```{directivename} arguments
     ---
     key1: val1
     key2: val2
     ---
     This is
     directive content
     ```
    

  • Using short-hand options with : characters

     ```{directivename} arguments
     :key1: val1
     :key2: val2
    
     This is
     directive content
     ```
    

  • Using eval-rst directive

     ```{eval-rst}
     .. {directivename}:: arguments
        :key1: val1
        :key2: val2
    
        This is directive content.
     ```
    

• role pattern

  • {role-name}role content

To support directives and roles for MyST/Markdown, Esbonio need to:

• For directives:

  * if {eval-rst} used, then it's no different as rst file. Esbonio language server doesn't need to do anything.
  
  * if pattern ```{directive} used, then Esbonio need to add new trigger, the { character,  left curly bracket, then check string pattern starts with ```{.
  
  * if directive option using YAML frontmatter, the triger for options can be tricky, maybe need another trigger, but don't know how yet.
  
  * if directive option using : character, then it's the same for rst file. Esbonio does not need to do anything.
  

• For roles:

  • Esbonio need to add new trigger, the { character.

What do you think this approach? @alcarney @danwos

By adding a new trigger {, then Esbonio can already support roles and directives that using short-hand options and eval-rst. If you think this is the way, then I will prepare a PR.

[alcarney]

Overall it makes sense, though I did do a very basic proof of concept for roles a while ago and so have some thoughts on how I think the implementation should look :)

• It should be a separate LanguageFeature, that way it can easily be enabled/disabled by the user
• On the note of trigger characters, I'd like to tweak the LanguageFeature API so that features can declare the trigger characters they'd like to use. This should prevent features from being limited by whatever the 'core' has decided a trigger character should be. I've opened #413 to track this.
• I wondering if completions in the Roles and Directives features should be split into two stages - perhaps suggest and complete. Where suggest simply generates a list of candidates and complete converts them into CompletionItems. This would allow the MyST feature to call out to the Roles and Directives features for suggestions but handle the markdown formatting itself.

Of course, it would take quite a while to line all that up and probably only the first point is necessary to get something shipped so happy to go and forth on this a bit.

Let me know your thoughts :smile:

[davbeek]

I am completely new to MyST, had a look at some online documentation and must say that it looks very promising. I would like to try and switch to MyST, when supported by esbonio.

[astrojuanlu]

Yes please 🙏🏽 I've been using MyST for 2 years and I'm not looking back (disclaimer: I wrote the Sphinx tutorial https://www.sphinx-doc.org/en/master/tutorial/ and worked at Read the Docs for 1 year)

[alcarney]

It's definitely on the list for the 1.0 release :)

[alcarney]

There is now a hint of MyST support in the current pre-release of the language server v1.0.0b1

To quote myself from another thread

The beginnings of MyST support!

• Assuming you have the relevant dependencies installed, builds and previews of MyST source files should mostly "Just Work"TM
• Document symbols, workspace symbols and diagnostics should also mostly work
• Limited support for completions of directives (::: syntax and nested directives not currently supported)

[chrisjsewell]

FYI you might want to consider adding https://github.com/chrisjsewell/vscode-myst-syntax in the extensionDependencies

[alcarney]

Thanks, that looks useful! :)

[alcarney]

Closing in favour of smaller, focused issues. The current pre-release has MyST support for all currently implemented features