[content v2] Readability of MDC Syntax in a naive markdown renderer

[ManUtopiK]

The syntax --- break markdown editor

Some of my customers (writers) complain that MDC Syntax break their markdown editor.

Consider this code taken from the doc:

::icon-card
---
icon: IconNuxt
description: Harness the full power of Nuxt and the Nuxt ecosystem.
title: Nuxt Architecture.
---
::

Now, this is the output generated by github (gfm) :

::icon-card

icon: IconNuxt description: Harness the full power of Nuxt and the Nuxt ecosystem. title: Nuxt Architecture.

::

👉 As we can see, ::icon-card is considered as a title. Also props look ugly.

Additional context

The first intention of John Gruber when he defined the markdown syntax was readability. As he wrote:

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions.

Moreover, I think readability should be important when markdown is also formatted in html with a naive markdown parser.

The solution I'd like : an options to use code block style `\yaml

Note: Below I use github markdown parser (gfm) as «a naive parser» to show examples and explain what's good and bad.

Let's try with this home hero component:

::home-hero
---
primary:
  text: 38K+ GitHub stars
  url: https://github.com/nuxt/nuxt.js
---
::

Below the gfm output:

::home-hero

primary:

text: 38K+ GitHub stars
url: [https://github.com/nuxt/nuxt.js][9]

::

👉 Bad ! It looks ugly and yaml indentation is lost.

Let's try with code block ``` format:

::home-hero
\```yaml
primary:
  text: 38K+ GitHub stars
  url: https://github.com/nuxt/nuxt.js
\```
::

(remove the \, it's break gfm, you got the idea).

Output:

::home-hero

primary:
  text: 38K+ GitHub stars
  url: https://github.com/nuxt/nuxt.js

::

It looks perfectly readable, isn't it?
Indentation isn't lost, and better, we provide the code block language (yaml) to colorize the syntax.

I don't know how you fetch the props of a MDC component. But I know we can configure many frontmatter parser to use a custom delimiter. It could be cool to add an option to change the type of delimiter. In addition, this could be also used to fetch the props in different language (json, toml...)!

What do you think about? Any issue or difficulties about this?

(What a long issue! Thanks for reading.)

Describe alternatives you've considered

Let's try with a blank line at the end:

::home-hero
---
primary:
  text: 38K+ GitHub stars
  url: https://github.com/nuxt/nuxt.js

---
::

Output:

::home-hero

primary:
text: 38K+ GitHub stars
url: [https://github.com/nuxt/nuxt.js][9]

---

::

👉 A bit better. Props don't look like title.

[Benbinbin]

I have created a discussion https://github.com/nuxt/content/discussions/1253 about the MDC syntax, I think the non-invasive way is using the markdown comment syntax like <!-- ::block-component --> as MDC syntax

[ManUtopiK]

@Benbinbin Good to see another idea for solving this problem! Thanks.

Using markdown comment syntax could be nice, but I think it's important to display props of a component in the markdown output. Maybe we could combine both?

VS code editor can fold ``` code block.

[Tahul]

Hello @ManUtopiK ;

While I totally understand your concern, I think this is inevitable for now.

As a new standard raises, it is normal for tooling not to be ready for it straight away.

We've made a first step towards better support of this syntax by providing the MDC plugin for VSCode.

We could probably support this better in web UIs by creating an extension for the syntax.

I would happily review any contributions in that direction by the way!

Just to mention some examples, as this syntax obviously has some equivalents:

• .mdx syntax: https://github.com/mdx-js/mdx/blob/main/docs/index.server.mdx

• MarkDoc syntax: https://github.com/markdoc/docs/blob/main/pages/index.md

Be sure this is one of our concerns to improve that situation in the future!

Thanks for raising this issue, we'll keep this open to track progress on a better integration of MDC syntax in the web!

[ManUtopiK]

.mdx syntax use code block ```mdx which render well with naive markdown parser.

MDC plugin for VSCode is a good idea. But it's mainly for developers, not writers. Many of my customers use their own markdown tools, which are undoubtedly all different. Do you plan to ask github or gitlab to support MDC syntax?

As a new standard, it isn't too late to change before it's raising.

Please, as a developer, consider the end user point of view!

[ManUtopiK]

Do you plan to open source remark-mdc ? It seems if I want to change --- to something else, I have to custom this plugin...

[ManUtopiK]

I have another complaint from one of my customer who doesn't enjoy the readability of the MDC syntax with his foreign markdown editor.

As a developer, I really enjoy the endless possibilities of the MDC components, and fully appreciate the DX!

Have you studied the improvement I propose above? Thanks.

[Benbinbin]

another suggestion is the VSCode MDC plugin don't provide the intellisense in markdown file, like which prop name the MDC can be set while writing in *.md file

[septatrix]

I have used JSX in Vue for some time and also played with Docasaurus (which uses MDX) while contributing to a project. As markdown allows raw HTML it has no problem with the JSX style used by MDX.

JSX is not longer a stranger in the Vue world and fits very well into the vanilla markdown syntax. Are there plans to also support MDX in the future?

[ManUtopiK]

another suggestion is the VSCode MDC plugin don't provide the intellisense in markdown file, like which prop name the MDC can be set while writing in *.md file

Are there plans to also support MDX in the future?

Good catch.

Does the main developers considered this issue or the ideas mentioned here ? Do you plan to open source remark-mdc ?

[maximepvrt]

🚀 https://github.com/nuxtlabs/remark-mdc @ManUtopiK