[Feature request] add field container into vuepress ecosystem as a plugin

[Mister-Hope]

Clear and concise description of the problem

Improving readability of config reference documentation

Suggested solution

A possible solution can be found at https://theme-plume.vuejs.press/guide/markdown/field/#%E7%A4%BA%E4%BE%8B

We just need to extract it into a plugin and move it here.

However, the syntax SHALL be adjusted. Required nesting and useless ending marker (in a field group) is pretty annoying.

Again, we shall introduce the tab syntax. See: https://mdit-plugins.github.io/tab.html

::: fields

@field name="theme" type="ThemeConfig" required default="{ base: '/' }"

Theme Config

@field name="enabled" type="boolean" optional default="true"

Whether it's enabled

:::

Also I would like to discuss the name. Shall "option" or "props" be better than "field"?

[Mister-Hope]

Also I would like to discuss the name. Shall "option" or "props" be better than "field"?

CC @pengzhanbo. I am planning to finish this tonight.

The first thing to discuss is the outer container name:

field/fields/prop/props/option/options

The second thing is the item marker:

@item name="theme" type="ThemeConfig" required default="{ base: '/' }"
@field/item/prop/option

or just make it simple:

@theme@
@multiple words@
@\@name-starts-with-at-and-ends-with-at\@@
\@ecaped-content-starting-with-at

[pengzhanbo]

@Mister-Hope
I think using fields / field would be more appropriate, because, for example, options / props might intuitively feel like function parameters or component properties, which could seem odd when used as API interface parameters.
Alternatively, supporting options/props as aliases could also be considered to suit different scenarios.

From a syntax perspective, I use field-group + field containers, taking into account scenarios where fields might be of object type and require nesting. The container implementation can easily achieve this purpose.
Additionally, I’ve also considered something similar to JSDoc’s @link syntax for associating fields or types.

[Mister-Hope]

We can support nesting with this syntax making a 2 space indent.

This gives more readability. Any ideas?

[pengzhanbo]

Like:

::: fields
@field name="options" type="object"
descriptions

  @field name="options.name" type="string"
  description

@field name="other" type="string"
descriptions
:::

It looks pretty good, so how should it be rendered?
Given a proper indentation, then as collapsible content?

[Mister-Hope]

::: fields
@options@ type="object"
descriptions

  @options.name@ type="string"
  description

@other@ type="string"
descriptions
:::

[Mister-Hope]

@mdit/plugin-field is released, so we can build this one now.