Field

Field container plugin for rendering structured API fields and properties documentation in Markdown, with support for field grouping and JSDoc-style tag annotations.

Installation

pnpm

pnpm add vitepress-plugin-field

npm

npm install vitepress-plugin-field

bun

bun add vitepress-plugin-field

deno

deno add vitepress-plugin-field

yarn

yarn add vitepress-plugin-field

Usage

vitepress-tuck Mode Recommended

.vitepress/config.ts

import { defineConfig } from 'vitepress-tuck'
import field from 'vitepress-plugin-field'

export default defineConfig({
  plugins: [field()],
})

Learn more about vitepress-tuck

Native Mode

.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { fieldMarkdownPlugin } from 'vitepress-plugin-field'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(fieldMarkdownPlugin)
    },
  },
})

.vitepress/theme/index.ts

import type { Theme } from 'vitepress'
import { enhanceAppWithField } from 'vitepress-plugin-field/client'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceAppWithField(ctx)
  },
} satisfies Theme

Syntax

Use the ::: field container to document API fields and properties, with JSDoc-style tags for metadata.

Basic Field

::: field count
@type Number
@default 0
Total number of users.
:::

Field Tags

Supported tags: @name, @type, @default, @required, @deprecated, @optional, @description.

::: field userName
@type String
@required
Unique identifier for the user.
:::

::: field email
@type String
@optional
@default [email protected]
Contact email address.
:::

::: field oldField
@type String
@deprecated
This field is deprecated, please use the new field instead.
:::

Rendered Result:

userNameRequiredString

Unique identifier for the user.

emailOptionalString

[email protected]

Contact email address.

oldFieldDeprecatedString

This field is deprecated, please use the new field instead.

Tag Reference

Tag	Description
@name	Override the field name (defaults to the name from info)
@type	Field type annotation
@default	Default value for the field
@required	Mark the field as required
@optional	Mark the field as optional
@deprecated	Mark the field as deprecated
@description	Explicit description text; any non-tag line also becomes description

Field Group

Use the ::: field-group container to group related fields together.

:::: field-group

::: field id
@type Number
@required
Unique identifier.
:::

::: field name
@type String
@optional
Display name.
:::

::: field createdAt
@type Date
@default Date.now()
Creation timestamp.
:::

::::

Rendered Result:

idRequiredNumber

Unique identifier.

nameOptionalString

Display name.

createdAtDate

Date.now()

Creation timestamp.

Explicit Description

Use the @description tag to specify description text explicitly. Any non-tag lines are also automatically treated as description content.

::: field count
@description Total number of users. This field represents the count of active users in the system.
@type Number
@default 0
:::