Skip to content

Commit efa8a24

Browse files
Mister-HopeMister-Hope
authored
feat(plugin-markdown-field): add field container (#839)
1 parent 2ee99bc commit efa8a24

18 files changed

Lines changed: 1077 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[![license](https://badgen.net/github/license/vuepress/ecosystem)](https://github.com/vuepress/ecosystem/blob/main/LICENSE)
77
[![discord](https://badgen.net/discord/online-members/ptFjefy6H5?icon=discord&label=discord)](https://discord.gg/ptFjefy6H5)
88

9-
This repo contains 48 official plugins and 1 official theme.
9+
This repo contains 57 official plugins and 1 official theme.
1010

1111
## Documentation
1212

‎docs/.vuepress/configs/plugins.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import { iconPlugin } from '@vuepress/plugin-icon'
88
import { llmsPlugin } from '@vuepress/plugin-llms'
99
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'
1010
import { markdownExtPlugin } from '@vuepress/plugin-markdown-ext'
11+
import { markdownFieldPlugin } from '@vuepress/plugin-markdown-field'
1112
import { markdownFileTreePlugin } from '@vuepress/plugin-markdown-file-tree'
1213
import { markdownImagePlugin } from '@vuepress/plugin-markdown-image'
1314
import { markdownIncludePlugin } from '@vuepress/plugin-markdown-include'
@@ -67,6 +68,9 @@ export const plugins = [
6768
component: true,
6869
vPre: true,
6970
}),
71+
markdownFieldPlugin({
72+
fields: true,
73+
}),
7074
markdownFileTreePlugin(),
7175
markdownImagePlugin({
7276
figure: true,

‎docs/.vuepress/configs/sidebar/en.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ export const sidebarEn: SidebarOptions = {
125125
},
126126
'markdown-container',
127127
'markdown-ext',
128+
'markdown-field',
128129
'markdown-file-tree',
129130
'markdown-image',
130131
'markdown-include',

‎docs/.vuepress/configs/sidebar/zh.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ export const sidebarZh: SidebarOptions = {
125125
},
126126
'markdown-container',
127127
'markdown-ext',
128+
'markdown-field',
128129
'markdown-file-tree',
129130
'markdown-image',
130131
'markdown-include',

‎docs/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
"@vuepress/plugin-llms": "workspace:*",
2929
"@vuepress/plugin-markdown-chart": "workspace:*",
3030
"@vuepress/plugin-markdown-ext": "workspace:*",
31+
"@vuepress/plugin-markdown-field": "workspace:*",
3132
"@vuepress/plugin-markdown-file-tree": "workspace:*",
3233
"@vuepress/plugin-markdown-image": "workspace:*",
3334
"@vuepress/plugin-markdown-include": "workspace:*",

‎docs/plugins/markdown/markdown-field.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
icon: list-checks
3+
---
4+
5+
# markdown-field
6+
7+
<NpmBadge package="@vuepress/plugin-markdown-field" />
8+
9+
Add fields to your VuePress site.
10+
11+
## Usage
12+
13+
```bash
14+
npm i -D @vuepress/plugin-markdown-field@next
15+
```
16+
17+
```ts title=".vuepress/config.ts"
18+
import { markdownFieldPlugin } from '@vuepress/plugin-markdown-field'
19+
20+
export default {
21+
plugins: [
22+
markdownFieldPlugin({
23+
// Enable fields
24+
fields: true,
25+
}),
26+
],
27+
}
28+
```
29+
30+
## Syntax
31+
32+
You can use `::: fields` container to describe field information, including field name, type, whether it's required, default value, etc.
33+
34+
Inside the container, lines starting with `@name@` are field items. Attributes are appended after the closing `@`.
35+
36+
```md
37+
::: fields
38+
@theme@ type="ThemeConfig" required default="{ base: '/' }"
39+
40+
Theme Config
41+
42+
@enabled@ type="boolean" optional default="true"
43+
44+
Whether it's enabled
45+
46+
:::
47+
```
48+
49+
By default, all attributes are allowed and displayed as-is. Common attributes include `type`, `required`, `optional`, `default` and `deprecated`.
50+
51+
- `type` is displayed as a code block in the field header.
52+
- `default` is displayed as a labeled code block below the field header.
53+
- `required`, `optional` and `deprecated` are displayed as badges, and a deprecated field's name is colored red and struck through.
54+
- Other attributes are displayed as `Name: value` badges.
55+
56+
### Nesting
57+
58+
Fields can be nested to describe fields of an object type. To create a field item inside another field, increase the starting `@` by one for each level of nesting.
59+
60+
```md
61+
::: fields
62+
@options@ type="object"
63+
64+
Options.
65+
66+
@@options.name@ type="string"
67+
68+
Option name.
69+
70+
@other@ type="string"
71+
72+
Other field.
73+
74+
:::
75+
```
76+
77+
For more syntax details, see [@mdit/plugin-field](https://mdit-plugins.github.io/field.html).
78+
79+
## Demo
80+
81+
::: fields
82+
@theme@ type="ThemeConfig" required default="{ base: '/' }"
83+
84+
Theme Config
85+
86+
@enabled@ type="boolean" optional default="true"
87+
88+
Whether it's enabled
89+
90+
@other@ type="string" deprecated
91+
92+
Deprecated field
93+
94+
:::
95+
96+
## Options
97+
98+
### fields
99+
100+
- Type: `boolean`
101+
- Details: Whether to enable fields.
102+
103+
### locales
104+
105+
- Type: `MarkdownFieldPluginLocaleConfig`
106+
107+
```ts
108+
interface MarkdownFieldPluginLocaleData {
109+
/**
110+
* Label text for the `default` attribute
111+
*/
112+
default: string
113+
114+
/**
115+
* Badge text for the `required` attribute
116+
*/
117+
required: string
118+
119+
/**
120+
* Badge text for the `optional` attribute
121+
*/
122+
optional: string
123+
124+
/**
125+
* Badge text for the `deprecated` attribute
126+
*/
127+
deprecated: string
128+
}
129+
```
130+
131+
- Details: Locale config for badge texts.

‎docs/zh/plugins/markdown/markdown-field.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
icon: list-checks
3+
---
4+
5+
# markdown-field
6+
7+
<NpmBadge package="@vuepress/plugin-markdown-field" />
8+
9+
在 VuePress 站点中添加字段容器。
10+
11+
## 使用
12+
13+
```bash
14+
npm i -D @vuepress/plugin-markdown-field@next
15+
```
16+
17+
```ts title=".vuepress/config.ts"
18+
import { markdownFieldPlugin } from '@vuepress/plugin-markdown-field'
19+
20+
export default {
21+
plugins: [
22+
markdownFieldPlugin({
23+
// 启用字段容器
24+
fields: true,
25+
}),
26+
],
27+
}
28+
```
29+
30+
## 语法
31+
32+
你可以使用 `::: fields` 容器描述字段信息，包括字段名称、类型、是否必填、默认值等。
33+
34+
在容器内部，以 `@名称@` 开头的行是字段项目。属性附加在闭合的 `@` 之后。
35+
36+
```md
37+
::: fields
38+
@theme@ type="ThemeConfig" required default="{ base: '/' }"
39+
40+
主题配置
41+
42+
@enabled@ type="boolean" optional default="true"
43+
44+
是否启用
45+
46+
:::
47+
```
48+
49+
默认情况下，所有属性都允许并按原样显示。常见属性包括 `type`、`required`、`optional`、`default` 和 `deprecated`。
50+
51+
- `type` 显示为字段头部中的代码块。
52+
- `default` 显示为字段头部下方带标签的代码块。
53+
- `required`、`optional` 和 `deprecated` 显示为徽章，已弃用字段的名称会标红并划掉。
54+
- 其他属性显示为 `名称: 值` 徽章。
55+
56+
### 嵌套
57+
58+
字段可以嵌套以描述对象类型的字段。要在另一个字段内创建字段项目，每个嵌套级别将起始 `@` 增加一个。
59+
60+
```md
61+
::: fields
62+
@options@ type="object"
63+
64+
选项。
65+
66+
@@options.name@ type="string"
67+
68+
选项名称。
69+
70+
@other@ type="string"
71+
72+
其他字段。
73+
74+
:::
75+
```
76+
77+
更多语法细节，请参考 [@mdit/plugin-field](https://mdit-plugins.github.io/zh/field.html)。
78+
79+
## 演示
80+
81+
::: fields
82+
@theme@ type="ThemeConfig" required default="{ base: '/' }"
83+
84+
主题配置
85+
86+
@enabled@ type="boolean" optional default="true"
87+
88+
是否启用
89+
90+
@other@ type="string" deprecated
91+
92+
已弃用字段
93+
94+
:::
95+
96+
## 选项
97+
98+
### fields
99+
100+
- 类型：`boolean`
101+
- 详情：是否启用字段容器。
102+
103+
### locales
104+
105+
- 类型：`MarkdownFieldPluginLocaleConfig`
106+
107+
```ts
108+
interface MarkdownFieldPluginLocaleData {
109+
/**
110+
* `default` 属性的标签文本
111+
*/
112+
default: string
113+
114+
/**
115+
* `required` 属性的徽章文本
116+
*/
117+
required: string
118+
119+
/**
120+
* `optional` 属性的徽章文本
121+
*/
122+
optional: string
123+
124+
/**
125+
* `deprecated` 属性的徽章文本
126+
*/
127+
deprecated: string
128+
}
129+
```
130+
131+
- 详情：徽章文本的国际化配置。

‎plugins/markdown/plugin-markdown-field/package.json‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
{
2+
"name": "@vuepress/plugin-markdown-field",
3+
"version": "2.0.0-rc.134",
4+
"description": "VuePress plugin - markdown field",
5+
"keywords": [
6+
"field",
7+
"markdown",
8+
"plugin",
9+
"vuepress",
10+
"vuepress-plugin"
11+
],
12+
"homepage": "https://ecosystem.vuejs.press/plugins/markdown/markdown-field.html",
13+
"bugs": {
14+
"url": "https://github.com/vuepress/ecosystem/issues"
15+
},
16+
"license": "MIT",
17+
"author": {
18+
"name": "Mr.Hope",
19+
"email": "mister-hope@outlook.com",
20+
"url": "https://mister-hope.com"
21+
},
22+
"repository": {
23+
"type": "git",
24+
"url": "git+https://github.com/vuepress/ecosystem.git",
25+
"directory": "plugins/markdown/plugin-markdown-field"
26+
},
27+
"files": [
28+
"dist"
29+
],
30+
"type": "module",
31+
"sideEffects": [
32+
"./dist/**/*.css"
33+
],
34+
"main": "./dist/node/index.js",
35+
"types": "./dist/node/index.d.ts",
36+
"exports": {
37+
".": {
38+
"types": "./dist/node/index.d.ts",
39+
"default": "./dist/node/index.js"
40+
},
41+
"./field.css": "./dist/client/styles/field.css",
42+
"./package.json": "./package.json"
43+
},
44+
"publishConfig": {
45+
"access": "public"
46+
},
47+
"scripts": {
48+
"build": "tsdown",
49+
"clean": "rimraf ./dist"
50+
},
51+
"dependencies": {
52+
"@mdit/helper": "^1.1.0",
53+
"@mdit/plugin-field": "^2.0.1",
54+
"@types/markdown-it": "^14.2.0",
55+
"@vuepress/helper": "workspace:*"
56+
},
57+
"devDependencies": {
58+
"markdown-it": "^14.3.1"
59+
},
60+
"peerDependencies": {
61+
"vuepress": "catalog:"
62+
}
63+
}

0 commit comments

Comments
 (0)