Editor Support

[ScottAwesome]

Great work here by the Stripe team! Really like this as a documentation generating tool.

My question (and idea) is I am wondering if there is any plans to support a VS Code and IntelliJ extension for the syntax? Since its "non-standard" markdown syntax and doesn't use any the pre-existing syntax of say, Liquid or Handlebars, the developer experience isn't as robust as something like say, MDX.

[segphault]

Yes, we built a Visual Studio Code extension for our internal use at Stripe that supports Markdoc syntax highlighting, validation, AST visualization, and a range of other features. It is currently a Stripe-specific solution, but we are planning to refactor it this year to make an open source Markdoc language server protocol implementation for the community, with support for VSCode and other LSP-compatible editors.

[addisonj]

@segphault Thanks so much for your work on markdoc.

I have started looking at building my own tooling for vscode to support some of these use cases and then came across this thread.

I was curious if this is still planned? Or if you might have more details to share on what you have built?

I am doing some PoC work to help validate using Markdoc with a team of technical writers and being able to show what that editing experience could look like is a big piece.

Thanks again for this great project, looking forward to using it more :)

[rpaul-stripe]

This is still planned, but we don't have a timeline that we can share at this time. I'm happy to answer specific questions about the feature set if that would be helpful.

One of the challenges with providing a good tooling experience around Markdoc is that a lot of the functionality relies on the schema, which is arbitrary user-supplied code that can potentially have complicated dependencies. For our internal tooling, we generate a static build of our schema and bundle it directly into the extension, which is obviously not a viable solution for other users.

What we'd like to do instead is create a library that speaks the VSCode language server protocol and make it so that you can embed it directly in your own application, passing in your schema as a parameter. This would make it so that when you run your Markdoc site locally for preview purposes it also starts up a language service that the VSCode extension can attach to so you get validation etc with your own schema.

[romanr]

What could be a reason for not releasing it? It's not like there's abundance of tools supporting it, none so far after more than a year.
Why release Markdoc to public at all if you are deliberately withholding the toolset that would help the adoption?

[mfix-stripe]

@romanr, @rpaul-stripe shared reasons above for why we aren't releasing our internal solution—it is not a viable one for Markdoc users outside of Stripe. Good news is, we are working on much better editor support that anyone can use, and we are hoping to release it it sometime in middle of this year.

[rpaul-stripe]

@romanr the official language server and VSCode extension are now available: #407

The internal VSCode extension that we used at Stripe included our own schema as a hard-coded dependency and also hard-coded many assumptions about our routing system, metadata, and other characteristics of our publishing pipeline. It was simply not suitable for distribution to the outside world and would not have been useful to anyone else. The new version that we're releasing today is a complete rewrite that is designed to dynamically load an external Markdoc schema. It's significantly better and more complete than the tools that we've been using internally up to this point. I can appreciate frustration with the long wait for us to release this, but I can assure you that we were not arbitrarily withholding anything that would have been useful.

[mohitsinghs]

For anyone else looking for syntax highlighting in VSCode, I've released one extension till official one is out. It's not great and have bugs but highlights are there for most of the things. The code lives here.

[mohitsinghs]

Thanks, I got formatter and part of completions working as well.

[mohitsinghs]

If anyone is missing it in neovim like me, I created tree-sitter-markdoc.

[mfix-stripe]

This deserves it's own show and tell post in the Discussions forum 🙂

[mohitsinghs]

Thanks @mfix-stripe , started a discussion for this.

[louiss0]

This deserves it's own show and tell post in the Discussions forum 🙂

For anyone else looking for syntax highlighting in VSCode, I've released one extension till official one is out. It's not great and have bugs but highlights are there for most of the things. The code lives here.

When you finish refactoring this extension can you please tell Ben Holmes from the Astro Team or the Next.js people. They both need this extension because Astro is going to support Markdoc soon.

[louiss0]

When you finish refactoring this extension can you please tell Ben Holmes from the Astro Team or the Next.js people. They both need this extension because Astro is going to support Markdoc soon.

[rpaul-stripe]

The official Visual Studio Code extension and language server are now available: #407