feat(doc-pipeline): add scripts to generate element api docs (#5685)

* feat: generate edge api docs

* feat: generate node,combo style props docs

* refactor: doc pipeline

* docs: remove reference index.md

packages/g6/src/elements/edges/base-edge.ts

@@ -1,8 +1,8 @@
 import type {
   BaseStyleProps,
+  DisplayObject,
   DisplayObjectConfig,
   Group,
-  ImageStyleProps,
   LineStyleProps,
   PathStyleProps,
 } from '@antv/g';
@@ -11,97 +11,146 @@ import type { PathArray } from '@antv/util';
 import { deepMix, isEmpty, isFunction } from '@antv/util';
 import type {
   BaseElementStyleProps,
+  EdgeArrowStyleProps,
   EdgeKey,
   EdgeLabelStyleProps,
   Keyframe,
-  LoopPlacement,
+  LoopStyleProps,
   Node,
   Point,
   PrefixObject,
-  Size,
 } from '../../types';
 import { getBBoxHeight, getBBoxWidth, getNodeBBox } from '../../utils/bbox';
 import { getCubicLoopPath, getLabelPositionStyle } from '../../utils/edge';
 import { findPorts, getConnectionPoint, isSameNode } from '../../utils/element';
 import { omitStyleProps, subStyleProps } from '../../utils/prefix';
 import { parseSize } from '../../utils/size';
-import type { SymbolFactor } from '../../utils/symbol';
 import * as Symbol from '../../utils/symbol';
 import { getWordWrapWidthByEnds } from '../../utils/text';
 import type { LabelStyleProps } from '../shapes';
 import { Label } from '../shapes';
 import { BaseShape } from '../shapes/base-shape';
 
-export type BaseEdgeStyleProps = BaseElementStyleProps &
-  Pick<
-    PathStyleProps,
-    'isBillboard' | 'markerStart' | 'markerStartOffset' | 'markerEnd' | 'markerEndOffset' | 'markerMid'
-  > &
-  PrefixObject<EdgeLabelStyleProps, 'label'> &
-  PrefixObject<PathStyleProps, 'halo'> &
-  PrefixObject<EdgeArrowStyleProps, 'startArrow'> &
-  PrefixObject<EdgeArrowStyleProps, 'endArrow'> &
-  PrefixObject<LoopStyleProps, 'loop'> & {
-    /**
-     * <zh/> 是否显示边的标签
-     *
-     * <en/> Whether to display the label of the edge
-     */
-    label?: boolean;
-    /**
-     * <zh/> 是否显示边的光晕
-     *
-     * <en/> Whether to display the halo of the edge
-     */
-    halo?: boolean;
-    /**
-     * <zh/> 是否显示边的起始箭头
-     *
-     * <en/> Whether to display the start arrow of the edge
-     */
-    startArrow?: boolean;
-    /**
-     * <zh/> 是否显示边的结束箭头
-     *
-     * <en/> Whether to display the end arrow of the edge
-     */
-    endArrow?: boolean;
-    /**
-     * <zh/> 起始箭头的偏移量
-     *
-     * <en/> Offset of the start arrow
-     */
-    startArrowOffset?: number;
-    /**
-     * <zh/> 结束箭头的偏移量
-     *
-     * <en/> Offset of the end arrow
-     */
-    endArrowOffset?: number;
-    /**
-     * <zh/> 边的起点 shape
-     * <en/> The source shape. Represents the start of the edge
-     */
-    sourceNode: Node;
-    /**
-     * <zh/> 边的终点 shape
-     * <en/> The source shape. Represents the start of the edge
-     */
-    targetNode: Node;
-    /**
-     * <zh/> 边起始连接的 port
-     * <en/> The Port of the source node
-     */
-    sourcePort?: string;
-    /**
-     * <zh/> 边终点连接的 port
-     * <en/> The Port of the target node
-     */
-    targetPort?: string;
-  };
+/**
+ * <zh/> 边的基础样式属性
+ *
+ * <en/> Base style properties of the edge
+ */
+export interface BaseEdgeStyleProps
+  extends BaseElementStyleProps,
+    PrefixObject<EdgeLabelStyleProps, 'label'>,
+    PrefixObject<PathStyleProps, 'halo'>,
+    PrefixObject<EdgeArrowStyleProps, 'startArrow'>,
+    PrefixObject<EdgeArrowStyleProps, 'endArrow'>,
+    PrefixObject<LoopStyleProps, 'loop'> {
+  /**
+   * <zh/> 是否显示边的标签
+   *
+   * <en/> Whether to display the label of the edge
+   */
+  label?: boolean;
+  /**
+   * <zh/> 是否显示边的光晕
+   *
+   * <en/> Whether to display the halo of the edge
+   */
+  halo?: boolean;
+  /**
+   * <zh/> 是否显示边的起始箭头
+   *
+   * <en/> Whether to display the start arrow of the edge
+   */
+  startArrow?: boolean;
+  /**
+   * <zh/> 是否显示边的结束箭头
+   *
+   * <en/> Whether to display the end arrow of the edge
+   */
+  endArrow?: boolean;
+  /**
+   * <zh/> 起始箭头的偏移量
+   *
+   * <en/> Offset of the start arrow
+   */
+  startArrowOffset?: number;
+  /**
+   * <zh/> 结束箭头的偏移量
+   *
+   * <en/> Offset of the end arrow
+   */
+  endArrowOffset?: number;
+  /**
+   * <zh/> 边的起点 shape
+   *
+   * <en/> The source shape. Represents the start of the edge
+   */
+  sourceNode: Node;
+  /**
+   * <zh/> 边的终点 shape
+   *
+   * <en/> The source shape. Represents the start of the edge
+   */
+  targetNode: Node;
+  /**
+   * <zh/> 边起始连接的 port
+   *
+   * <en/> The Port of the source node
+   */
+  sourcePort?: string;
+  /**
+   * <zh/> 边终点连接的 port
+   *
+   * <en/> The Port of the target node
+   */
+  targetPort?: string;
+  /**
+   * <zh/> 在 “起始点” 处添加一个标记图形，其中 “起始点” 为边与起始节点的交点
+   *
+   * <en/> Add a marker graphic at the "start point", where the "start point" is the intersection of the edge and the source node
+   */
+  markerStart?: DisplayObject | null;
+  /**
+   * <zh/> 调整 “起始点” 处标记图形的位置，正偏移量向内，负偏移量向外
+   *
+   * <en/> Adjust the position of the marker graphic at the "start point", positive offset inward, negative offset outward
+   * @defaultValue 0
+   */
+  markerStartOffset?: number;
+  /**
+   * <zh/> 在 “终止点” 处添加一个标记图形，其中 “终止点” 为边与终止节点的交点
+   *
+   * <en/> Add a marker graphic at the "end point", where the "end point" is the intersection of the edge and the target node
+   */
+  markerEnd?: DisplayObject | null;
+  /**
+   * <zh/> 调整 “终止点” 处标记图形的位置，正偏移量向内，负偏移量向外
+   *
+   * <en/> Adjust the position of the marker graphic at the "end point", positive offset inward, negative offset outward
+   * @defaultValue 0
+   */
+  markerEndOffset?: number;
+  /**
+   * <zh/> 在路径除了 “起始点” 和 “终止点” 之外的每一个顶点上放置标记图形。在内部实现中，由于我们会把路径中部分命令转换成 C 命令，因此这些顶点实际是三阶贝塞尔曲线的控制点
+   *
+   * <en/> Place a marker graphic on each vertex of the path except for the "start point" and "end point". In the internal implementation, because we will convert some commands in the path to C commands, these vertices are actually the control points of the cubic Bezier curve
+   */
+  markerMid?: DisplayObject | null;
+  /**
+   * <zh/> 3D 场景中生效，始终朝向屏幕，因此线宽不受透视投影影像
+   *
+   * <en/> Effective in 3D scenes, always facing the screen, so the line width is not affected by the perspective projection image
+   * @defaultValue false
+   */
+  isBillboard?: boolean;
+}
 
 type ParsedBaseEdgeStyleProps = Required<BaseEdgeStyleProps>;
 
+/**
+ * <zh/> 基础边元素
+ *
+ * <en/> Base edge element
+ */
 export abstract class BaseEdge extends BaseShape<BaseEdgeStyleProps> {
   public type = 'edge';
 
@@ -323,30 +372,3 @@ export abstract class BaseEdge extends BaseShape<BaseEdgeStyleProps> {
     return result;
   }
 }
-
-type SymbolName = 'triangle' | 'circle' | 'diamond' | 'vee' | 'rect' | 'triangleRect' | 'simple';
-
-type EdgeArrowStyleProps = {
-  type?: SymbolName | SymbolFactor;
-  size?: Size;
-} & PathStyleProps &
-  Omit<ImageStyleProps, 'width' | 'height'> &
-  Record<string, unknown>;
-
-export type LoopStyleProps = {
-  /**
-   * <zh/> 边的位置
-   * <en/> The position of the edge
-   */
-  placement?: LoopPlacement;
-  /**
-   * <zh/> 指定是否顺时针绘制环
-   * <en/> Specify whether to draw the loop clockwise
-   */
-  clockwise?: boolean;
-  /**
-   * <zh/> 从节点 keyShape 边缘到自环顶部的距离，用于指定自环的曲率，默认为宽度或高度的最大值
-   * <en/> Determine the position from the edge of the node keyShape to the top of the self-loop, used to specify the curvature of the self-loop, the default value is the maximum of the width or height
-   */
-  dist?: number;
-};

packages/g6/src/elements/edges/cubic-horizontal.ts

@@ -4,19 +4,33 @@ import type { Point } from '../../types';
 import type { BaseEdgeStyleProps } from './base-edge';
 import { Cubic } from './cubic';
 
+/**
+ * <zh/> 水平方向的三次贝塞尔曲线样式配置项
+ *
+ * <en/> Cubic Bezier curve style properties in horizontal direction
+ */
 export interface CubicHorizontalStyleProps extends BaseEdgeStyleProps {
   /**
    * <zh/> 控制点在两端点连线上的相对位置，范围为`0-1`
+   *
    * <en/> The relative position of the control point on the line, ranging from `0-1`
+   * @defaultValue [0.5, 0.5]
    */
   curvePosition?: number | [number, number];
   /**
    * <zh/> 控制点距离两端点连线的距离，可理解为控制边的弯曲程度
+   *
    * <en/> The distance of the control point from the line
+   * @defaultValue [0, 0]
    */
   curveOffset?: number | [number, number];
 }
 
+/**
+ * <zh/> 水平方向的三次贝塞尔曲线
+ *
+ * <en/> Cubic Bezier curve in horizontal direction
+ */
 export class CubicHorizontal extends Cubic {
   static defaultStyleProps: Partial<CubicHorizontalStyleProps> = {
     curvePosition: [0.5, 0.5],

packages/g6/src/elements/edges/cubic-vertical.ts

@@ -4,19 +4,33 @@ import type { Point } from '../../types';
 import type { BaseEdgeStyleProps } from './base-edge';
 import { Cubic } from './cubic';
 
+/**
+ * <zh/> 垂直方向的三次贝塞尔曲线样式配置项
+ *
+ * <en/> Cubic Bezier curve style properties in vertical direction
+ */
 export interface CubicVerticalStyleProps extends BaseEdgeStyleProps {
   /**
    * <zh/> 控制点在两端点连线上的相对位置，范围为`0-1`
+   *
    * <en/> The relative position of the control point on the line, ranging from `0-1`
+   * @defaultValue [0.5, 0.5]
    */
   curvePosition?: number | [number, number];
   /**
    * <zh/> 控制点距离两端点连线的距离，可理解为控制边的弯曲程度
+   *
    * <en/> The distance of the control point from the line
+   * @defaultValue [0, 0]
    */
   curveOffset?: number | [number, number];
 }
 
+/**
+ * <zh/> 垂直方向的三次贝塞尔曲线
+ *
+ * <en/> Cubic Bezier curve in vertical direction
+ */
 export class CubicVertical extends Cubic {
   static defaultStyleProps: Partial<CubicVerticalStyleProps> = {
     curvePosition: [0.5, 0.5],

packages/g6/src/elements/edges/cubic.ts

@@ -6,26 +6,41 @@ import { getCubicPath, getCurveControlPoint, parseCurveOffset, parseCurvePositio
 import type { BaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
+/**
+ * <zh/> 三次贝塞尔曲线样式配置项
+ *
+ * <en/> Cubic Bezier curve style properties
+ */
 export interface CubicStyleProps extends BaseEdgeStyleProps {
   /**
-   * <zh/> 控制点数组，用于定义曲线的形状。如果不指定，将会通过`curveOffset`和`curvePosition`来计算控制点
+   * <zh/> 控制点数组，用于定义曲线的形状。如果不指定，将会通过 `curveOffset` 和 `curvePosition` 来计算控制点
+   *
    * <en/> Control points. Used to define the shape of the curve. If not specified, it will be calculated using `curveOffset` and `curvePosition`.
    */
   controlPoints?: [Point, Point];
   /**
    * <zh/> 控制点在两端点连线上的相对位置，范围为`0-1`
+   *
    * <en/> The relative position of the control point on the line, ranging from `0-1`
+   * @defaultValue 0.5
    */
   curvePosition?: number | [number, number];
   /**
    * <zh/> 控制点距离两端点连线的距离，可理解为控制边的弯曲程度
+   *
    * <en/> The distance of the control point from the line
+   * @defaultValue 20
    */
   curveOffset?: number | [number, number];
 }
 
 type ParsedCubicStyleProps = Required<CubicStyleProps>;
 
+/**
+ * <zh/> 三次贝塞尔曲线
+ *
+ * <en/> Cubic Bezier curve
+ */
 export class Cubic extends BaseEdge {
   static defaultStyleProps: Partial<CubicStyleProps> = {
     curvePosition: 0.5,
@@ -36,6 +51,9 @@ export class Cubic extends BaseEdge {
     super(deepMix({}, { style: Cubic.defaultStyleProps }, options));
   }
 
+  /**
+   * @inheritdoc
+   */
   protected getKeyPath(attributes: ParsedCubicStyleProps): PathArray {
     const [sourcePoint, targetPoint] = this.getEndpoints(attributes);
     const { controlPoints, curvePosition, curveOffset } = attributes;

packages/g6/src/elements/edges/line.ts

@@ -4,12 +4,19 @@ import { deepMix } from '@antv/util';
 import type { BaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
+/**
+ * <zh/> 直线样式配置项
+ *
+ * <en/> Line style properties
+ */
 export type LineStyleProps = BaseEdgeStyleProps;
 
 type ParsedLineStyleProps = Required<LineStyleProps>;
 
 /**
- * Draw line based on BaseEdge, override drawKeyShape
+ * <zh/> 直线
+ *
+ * <en/> Line
  */
 export class Line extends BaseEdge {
   static defaultStyleProps: Partial<LineStyleProps> = {};

packages/g6/src/elements/edges/polyline.ts

@@ -1,44 +1,63 @@
 import type { DisplayObjectConfig } from '@antv/g';
 import type { PathArray } from '@antv/util';
 import { deepMix } from '@antv/util';
-import type { Padding, Point, Port } from '../../types';
+import type { LoopStyleProps, Padding, Point, Port } from '../../types';
 import { getBBoxHeight, getBBoxWidth, getNodeBBox } from '../../utils/bbox';
 import { getPolylineLoopPath, getPolylinePath } from '../../utils/edge';
 import { findPorts, getConnectionPoint, getPortPosition } from '../../utils/element';
 import { subStyleProps } from '../../utils/prefix';
 import { orth } from '../../utils/router/orth';
-import type { BaseEdgeStyleProps, LoopStyleProps } from './base-edge';
+import type { BaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
+/**
+ * <zh/> 折线样式配置项
+ *
+ * <en/> Polyline style properties
+ */
 export interface PolylineStyleProps extends BaseEdgeStyleProps {
   /**
    * <zh/> 圆角半径
+   *
    * <en/> The radius of the rounded corner
+   * @defaultValue 0
    */
   radius?: number;
   /**
    * <zh/> 控制点数组
+   *
    * <en/> Control point array
    */
   controlPoints?: Point[];
   /**
    * <zh/> 是否启用路由，默认开启且 controlPoints 会自动计入
+   *
    * <en/> Whether to enable routing, it is enabled by default and controlPoints will be automatically included
+   * @defaultValue false
    */
   router?: boolean;
   /**
    * <zh/> 路由名称，目前支持 'orth'
+   *
    * <en/> Routing name, currently supports 'orth'
+   * @defaultValue 'orth'
    */
   routerName?: 'orth';
   /**
    * <zh/> 节点边距
+   *
    * <en/> Padding for routing calculation
+   * @defaultValue 10
    */
   routerPadding?: Padding;
 }
 type ParsedPolylineStyleProps = Required<PolylineStyleProps>;
 
+/**
+ * <zh/> 折线
+ *
+ * <en/> Polyline
+ */
 export class Polyline extends BaseEdge {
   static defaultStyleProps: Partial<PolylineStyleProps> = {
     radius: 0,

packages/g6/src/elements/edges/quadratic.ts

@@ -6,26 +6,41 @@ import { getCurveControlPoint, getQuadraticPath } from '../../utils/edge';
 import type { BaseEdgeStyleProps } from './base-edge';
 import { BaseEdge } from './base-edge';
 
+/**
+ * <zh/> 二次贝塞尔曲线样式配置项
+ *
+ * <en/> Quadratic Bezier curve style properties
+ */
 export interface QuadraticStyleProps extends BaseEdgeStyleProps {
   /**
    * <zh/> 控制点，用于定义曲线的形状。如果不指定，将会通过`curveOffset`和`curvePosition`来计算控制点
+   *
    * <en/> Control point. Used to define the shape of the curve. If not specified, it will be calculated using `curveOffset` and `curvePosition`.
    */
   controlPoint?: Point;
   /**
    * <zh/> 控制点在两端点连线上的相对位置，范围为`0-1`
+   *
    * <en/> The relative position of the control point on the line, ranging from `0-1`
+   * @defaultValue 0.5
    */
   curvePosition?: number;
   /**
    * <zh/> 控制点距离两端点连线的距离，可理解为控制边的弯曲程度
+   *
    * <en/> The distance of the control point from the line
+   * @defaultValue 30
    */
   curveOffset?: number;
 }
 
 type ParsedQuadraticStyleProps = Required<QuadraticStyleProps>;
 
+/**
+ * <zh/> 二次贝塞尔曲线
+ *
+ * <en/> Quadratic Bezier curve
+ */
 export class Quadratic extends BaseEdge {
   static defaultStyleProps: Partial<QuadraticStyleProps> = {
     curvePosition: 0.5,

packages/g6/src/elements/nodes/html.ts

@@ -17,7 +17,7 @@ export type HTMLStyleProps = BaseNodeStyleProps<{
 }>;
 
 /**
- * @see https://github.com/antvis/G/blob/next/packages/g-lite/src/plugins/EventPlugin.ts
+ * @see https://github.com/antvis/G/blob/next/packages/g/src/plugins/EventPlugin.ts
  */
 export class HTML extends BaseNode<HTMLStyleProps> {
   static defaultStyleProps: Partial<HTMLStyleProps> = {

packages/g6/src/elements/shapes/base-shape.ts

@@ -7,7 +7,17 @@ import { updateStyle } from '../../utils/element';
 import { setVisibility } from '../../utils/visibility';
 
 export interface BaseShapeStyleProps extends BaseStyleProps {
+  /**
+   * <zh/> x 坐标
+   *
+   * <en/> x coordinate
+   */
   x?: number | string;
+  /**
+   * <zh/> y 坐标
+   *
+   * <en/> y coordinate
+   */
   y?: number | string;
 }
 

packages/g6/src/elements/shapes/label.ts

@@ -4,15 +4,23 @@ import type { Padding } from '../../types/padding';
 import type { PrefixObject } from '../../types/prefix';
 import { parsePadding } from '../../utils/padding';
 import { omitStyleProps, startsWith, subStyleProps } from '../../utils/prefix';
-import type { BaseShapeStyleProps } from './base-shape';
 import { BaseShape } from './base-shape';
 
-export type LabelStyleProps = BaseShapeStyleProps &
-  TextStyleProps & {
-    background?: boolean;
-  } & PrefixObject<RectStyleProps, 'background'> & {
-    padding?: Padding;
-  };
+export interface LabelStyleProps extends TextStyleProps, PrefixObject<RectStyleProps, 'background'> {
+  /**
+   * <zh/> 是否显示背景
+   *
+   * <en/> Whether to show background
+   */
+  background?: boolean;
+  /**
+   * <zh/> 标签内边距
+   *
+   * <en/> Label padding
+   * @defaultValue 0
+   */
+  padding?: Padding;
+}
 type ParsedLabelStyleProps = Required<LabelStyleProps>;
 type LabelOptions = DisplayObjectConfig<LabelStyleProps>;
 

packages/g6/src/exports.ts

@@ -81,23 +81,6 @@ export { Shortcut } from './utils/shortcut';
 export { parseSize } from './utils/size';
 export { treeToGraphData } from './utils/tree';
 
-export type { BaseStyleProps } from '@antv/g';
-export type {
-  AntVDagreLayoutOptions,
-  CircularLayoutOptions,
-  ComboCombinedLayoutOptions,
-  ConcentricLayoutOptions,
-  D3Force3DLayoutOptions,
-  D3ForceLayoutOptions,
-  DagreLayoutOptions,
-  ForceAtlas2LayoutOptions,
-  ForceLayoutOptions,
-  FruchtermanLayoutOptions,
-  GridLayoutOptions,
-  MDSLayoutOptions,
-  RadialLayoutOptions,
-  RandomLayoutOptions,
-} from '@antv/layout';
 export type {
   BaseBehaviorOptions,
   BrushSelectOptions,
@@ -134,7 +117,7 @@ export type {
   StarStyleProps,
   TriangleStyleProps,
 } from './elements/nodes';
-export type { BaseShapeStyleProps } from './elements/shapes';
+export type { BaseShapeStyleProps, LabelStyleProps } from './elements/shapes';
 export type {
   BasePluginOptions,
   BubbleSetsOptions,
@@ -174,6 +157,8 @@ export type {
   CornerPlacement,
   DirectionalPlacement,
   Edge,
+  EdgeArrowStyleProps,
+  EdgeLabelStyleProps,
   Element,
   ElementDatum,
   ElementType,
@@ -188,6 +173,7 @@ export type {
   IPointerEvent,
   IViewportEvent,
   IWheelEvent,
+  LoopStyleProps,
   Node,
   Placement,
   Point,
@@ -198,3 +184,21 @@ export type {
   ViewportAnimationEffectTiming,
 } from './types';
 export type { ShortcutKey } from './utils/shortcut';
+
+export type {
+  AntVDagreLayoutOptions,
+  CircularLayoutOptions,
+  ComboCombinedLayoutOptions,
+  ConcentricLayoutOptions,
+  D3Force3DLayoutOptions,
+  D3ForceLayoutOptions,
+  DagreLayoutOptions,
+  ForceAtlas2LayoutOptions,
+  ForceLayoutOptions,
+  FruchtermanLayoutOptions,
+  GridLayoutOptions,
+  MDSLayoutOptions,
+  RadialLayoutOptions,
+  RandomLayoutOptions,
+} from '@antv/layout';
+export type { PathArray } from '@antv/util';

packages/g6/src/spec/canvas.ts

@@ -1,4 +1,4 @@
-import type { CanvasConfig, IRenderer } from '@antv/g';
+import type { IRenderer } from '@antv/g';
 import type { Canvas } from '../runtime/canvas';
 
 /**
@@ -7,7 +7,7 @@ import type { Canvas } from '../runtime/canvas';
  * <en/> Canvas spec
  * @public
  */
-export interface CanvasOptions extends Pick<CanvasConfig, 'devicePixelRatio'> {
+export interface CanvasOptions {
   /**
    * <zh/> 画布容器
    *
@@ -44,4 +44,10 @@ export interface CanvasOptions extends Pick<CanvasConfig, 'devicePixelRatio'> {
    * <en/> canvas background color
    */
   background?: string;
+  /**
+   * <zh/> 设备像素比
+   *
+   * <en/> device pixel ratio
+   */
+  devicePixelRatio?: number;
 }

packages/g6/src/types/edge.ts

@@ -1,39 +1,91 @@
-import { Line, Path, Polyline } from '@antv/g';
+import type { ImageStyleProps, Line, Path, PathStyleProps, Polyline } from '@antv/g';
+import type { PathArray } from '@antv/util';
 import type { LabelStyleProps } from '../elements/shapes';
 import type { CardinalPlacement, CornerPlacement } from './placement';
+import type { Size } from './size';
 
 export type EdgeDirection = 'in' | 'out' | 'both';
 
 export type EdgeKey = Line | Path | Polyline;
 
-export type EdgeLabelPlacement = 'start' | 'center' | 'end' | number;
-
-export type EdgeLabelStyleProps = {
+export interface EdgeLabelStyleProps extends LabelStyleProps {
   /**
    * <zh/> 标签相对于边的位置。取值范围为 'start'、'center'、'end' 或特定比率（数字 0-1）
+   *
    * <en/> Label position relative to the edge (keyShape) that can be 'start', 'center', 'end' or a specific ratio (number 0-1)
    */
-  placement?: EdgeLabelPlacement;
+  placement?: 'start' | 'center' | 'end' | number;
   /**
    * <zh/> 标签平行于边的水平偏移量
+   *
    * <en/> The horizontal offset of the label parallel to the edge
    */
   offsetX?: number;
   /**
    * <zh/> 标签垂直于边的垂直偏移量
+   *
    * <en/> The vertical offset of the label perpendicular to the edge
    */
   offsetY?: number;
   /**
    * <zh/> 是否自动旋转以与边的方向对齐
+   *
    * <en/> Indicates whether the label should automatically rotate to align with the edge's direction
    */
   autoRotate?: boolean;
   /**
    * <zh/> 文本的最大宽度，超出会裁减
+   *
    * <en/> maxWidth of label text, which will be clipped if exceeded
    */
   maxWidth?: string | number;
-} & LabelStyleProps;
+}
+
+export interface EdgeArrowStyleProps
+  extends PathStyleProps,
+    Omit<ImageStyleProps, 'width' | 'height'>,
+    Record<string, unknown> {
+  /**
+   * <zh/> 箭头大小
+   *
+   * <en/> Arrow size
+   */
+  size?: Size;
+  /**
+   * <zh/> 箭头类型
+   *
+   * <en/> Arrow type
+   */
+  type?:
+    | 'triangle'
+    | 'circle'
+    | 'diamond'
+    | 'vee'
+    | 'rect'
+    | 'triangleRect'
+    | 'simple'
+    | ((width: number, height: number) => PathArray);
+}
 
 export type LoopPlacement = CardinalPlacement | CornerPlacement;
+
+export interface LoopStyleProps {
+  /**
+   * <zh/> 边的位置
+   *
+   * <en/> The position of the edge
+   */
+  placement?: LoopPlacement;
+  /**
+   * <zh/> 指定是否顺时针绘制环
+   *
+   * <en/> Specify whether to draw the loop clockwise
+   */
+  clockwise?: boolean;
+  /**
+   * <zh/> 从节点 keyShape 边缘到自环顶部的距离，用于指定自环的曲率，默认为宽度或高度的最大值
+   *
+   * <en/> Determine the position from the edge of the node keyShape to the top of the self-loop, used to specify the curvature of the self-loop, the default value is the maximum of the width or height
+   */
+  dist?: number;
+}

packages/g6/src/utils/edge.ts

@@ -2,17 +2,7 @@ import type { AABB } from '@antv/g';
 import type { PathArray } from '@antv/util';
 import { isEqual, isNumber } from '@antv/util';
 import type { EdgeData } from '../spec';
-import type {
-  EdgeKey,
-  EdgeLabelPlacement,
-  EdgeLabelStyleProps,
-  ID,
-  LoopPlacement,
-  Node,
-  Point,
-  Port,
-  Vector2,
-} from '../types';
+import type { EdgeKey, EdgeLabelStyleProps, ID, LoopPlacement, Node, Point, Port, Vector2 } from '../types';
 import { getBBoxHeight, getBBoxSize, getBBoxWidth, getNearestSideToPoint, getNodeBBox } from './bbox';
 import { getAllPorts, getNodeConnectionPoint, getPortConnectionPoint, getPortPosition } from './element';
 import { isCollinear, isHorizontal, moveTo, parsePoint } from './point';
@@ -32,7 +22,7 @@ import { add, distance, manhattanDistance, multiply, normalize, perpendicular, s
  */
 export function getLabelPositionStyle(
   key: EdgeKey,
-  placement: EdgeLabelPlacement,
+  placement: EdgeLabelStyleProps['placement'],
   autoRotate: boolean,
   offsetX: number,
   offsetY: number,

packages/site/.dumirc.ts

@@ -143,28 +143,28 @@ export default defineConfig({
         },
       },
       {
-        slug: 'api/element',
+        slug: 'apis/elements',
         title: {
           zh: 'Element - 元素',
           en: 'Element',
         },
       },
       {
-        slug: 'api/element/node',
+        slug: 'apis/elements/nodes',
         title: {
           zh: 'Node - 节点',
           en: 'Node',
         },
       },
       {
-        slug: 'api/element/edge',
+        slug: 'apis/elements/edges',
         title: {
           zh: 'Edge - 边',
           en: 'Edge',
         },
       },
       {
-        slug: 'api/element/combo',
+        slug: 'apis/elements/combos',
         title: {
           zh: 'Combo - 组合',
           en: 'Combo',

packages/site/docs/apis/element/combo/default.en.md

@@ -1,3 +0,0 @@
----
-title: (Demo)Combo
----

packages/site/docs/apis/element/combo/default.zh.md

@@ -1,3 +0,0 @@
----
-title: (示例)组合
----

packages/site/docs/apis/element/edge/default.en.md

@@ -1,3 +0,0 @@
----
-title: (Demo)Edge
----

packages/site/docs/apis/element/edge/default.zh.md

@@ -1,3 +0,0 @@
----
-title: (示例)边
----

packages/site/docs/apis/element/node/default.en.md

@@ -1,3 +0,0 @@
----
-title: (Demo)Node
----

packages/site/docs/apis/element/node/default.zh.md

@@ -1,3 +0,0 @@
----
-title: (示例)节点
----

packages/site/scripts/generate-api.ts

@@ -39,7 +39,7 @@ export function mangleScopedPackageName(packageName: string): string {
 
 const reportFolderRoot = path.resolve(path.join('support', 'api'));
 const reportTempFolderRoot = path.resolve(reportFolderRoot, 'temp');
-const ignorePackages = new Set<string>(['@antv/g6-react-node', '@antv/g6-plugin-map-view', '@antv/g6-site']);
+const ignorePackages = new Set<string>(['@antv/g6-site', '@antv/g6-extension-3d']);
 
 /**
  * Get all typed packages.
@@ -116,6 +116,7 @@ async function runApiExtractor() {
       // Make `export * from 'other-remirror-packages'` to work
       bundledPackages: [
         ...Object.keys(pkg.packageJson.dependencies ?? {}),
+        ...Object.keys(pkg.packageJson.devDependencies ?? {}),
         ...Object.keys(pkg.packageJson.peerDependencies ?? {}),
       ].filter((name) => packageNameSet.has(name)),
     };

packages/site/src/constants/index.ts

@@ -1,3 +1,2 @@
-export * from './keywords';
-export * from './locale';
-export * from './page';
+export * from './link';
+export * from './locales';

packages/site/src/constants/link.ts

@@ -0,0 +1,15 @@
+export const GLinks: Record<string, string> = {
+  BaseStyleProps: 'https://g.antv.antgroup.com/api/basic/display-object#%E7%BB%98%E5%9B%BE%E5%B1%9E%E6%80%A7',
+  DisplayObject: 'https://g.antv.antgroup.com/api/basic/display-object',
+  GroupStyleProps: 'https://g.antv.antgroup.com/api/basic/group',
+  TextStyleProps: 'https://g.antv.antgroup.com/api/basic/text',
+  CircleStyleProps: 'https://g.antv.antgroup.com/api/basic/circle',
+  EllipseStyleProps: 'https://g.antv.antgroup.com/api/basic/ellipse',
+  RectStyleProps: 'https://g.antv.antgroup.com/api/basic/rect',
+  ImageStyleProps: 'https://g.antv.antgroup.com/api/basic/image',
+  LineStyleProps: 'https://g.antv.antgroup.com/api/basic/line',
+  PolygonStyleProps: 'https://g.antv.antgroup.com/api/basic/polygon',
+  PolylineStyleProps: 'https://g.antv.antgroup.com/api/basic/polyline',
+  PathStyleProps: 'https://g.antv.antgroup.com/api/basic/path',
+  HTMLStyleProps: 'https://g.antv.antgroup.com/api/basic/html',
+};

packages/site/src/constants/locale.ts

@@ -1,4 +0,0 @@
-export enum LocaleLanguage {
-  EN = 'en-US',
-  ZH = 'zh-CN',
-}

packages/site/src/constants/locales/api-category.ts

@@ -1,4 +1,4 @@
-import { LocaleLanguage } from './locale';
+import { getIntl } from './common';
 
 const apiCategoryNames: Record<string, string[]> = {
   option: ['Option', '图配置项'],
@@ -19,12 +19,9 @@ const apiCategoryNames: Record<string, string[]> = {
 };
 
 /**
- * Get the category name of the API
- * @param categoryKey - The key of the category
- * @param locale - The locale
- * @returns The category name
+ * 获取 API 分类名称
+ * @param categoryKey 分类 key
+ * @param locale 语言
+ * @returns 分类名称
  */
-export function getApiCategoryName(categoryKey: string, locale: LocaleLanguage) {
-  const [en, zh] = apiCategoryNames[categoryKey];
-  return locale === LocaleLanguage.ZH ? zh : en;
-}
+export const getApiCategoryIntl = getIntl(apiCategoryNames);

packages/site/src/constants/locales/common.ts

@@ -0,0 +1,11 @@
+export enum LocaleLanguage {
+  EN = 'en-US',
+  ZH = 'zh-CN',
+}
+
+export const getIntl = (obj: Record<string, string[]>) => {
+  return (key: string, language: LocaleLanguage) => {
+    const [en, zh] = obj[key];
+    return language === LocaleLanguage.EN ? en : zh;
+  };
+};

packages/site/src/constants/locales/helper.ts

@@ -0,0 +1,13 @@
+import { getIntl } from './index';
+
+export const helpers = {
+  prefixHelper: [
+    'More about `Prefix` generic usage, please check [here]',
+    '更多关于 `Prefix` 泛型的使用信息，请查看[这里]',
+  ],
+  basePropsStyleHelper: ['More about base style configuration, please check [here]', '了解通用样式配置，请点击[这里]'],
+  includes: ['Includes', '其中的'],
+  excludes: ['Excludes', '除了'],
+};
+
+export const getHelperIntl = getIntl(helpers);

packages/site/src/constants/locales/index.ts

@@ -0,0 +1,5 @@
+export * from './api-category';
+export * from './common';
+export * from './helper';
+export * from './keywords';
+export * from './page';

packages/site/src/constants/locales/keywords.ts

@@ -1,4 +1,4 @@
-import { LocaleLanguage } from './locale';
+import { getIntl } from './index';
 
 export enum Keyword {
   ABSTRACT_CLASS = 'abstract-class',
@@ -7,16 +7,19 @@ export enum Keyword {
   CLASSES = 'classes',
   COLON = 'colon',
   COMMA = 'comma',
+  CONSTRUCTOR = 'constructor',
   CONSTRUCTORS = 'constructors',
   DECORATOR = 'decorator',
   DEFAULT_VALUE = 'defaultValue',
   DESCRIPTION = 'description',
+  ENUMERATION = 'enumeration',
   ENUMERATION_MEMBERS = 'enumeration-members',
   ENUMERATIONS = 'enumerations',
   EVENTS = 'events',
   EXAMPLE = 'example',
   EXCEPTIONS = 'exceptions',
   EXTENDS = 'extends',
+  FUNCTION = 'function',
   FUNCTIONS = 'functions',
   IMPLEMENTS = 'implements',
   INTERFACE = 'interface',
@@ -25,6 +28,7 @@ export enum Keyword {
   METHOD = 'method',
   METHODS = 'methods',
   MODIFIERS = 'modifiers',
+  NAMESPACE = 'namespace',
   NAMESPACES = 'namespaces',
   OPTIONAL = 'optional',
   OPTIONS = 'options',
@@ -38,7 +42,9 @@ export enum Keyword {
   RETURNS = 'returns',
   RIGHT_PARENTHESIS = 'rightParenthesis',
   TYPE = 'type',
+  TYPE_ALIAS = 'type-alias',
   TYPE_ALIASES = 'type-aliases',
+  VARIABLE = 'variable',
   VARIABLES = 'variables',
   VIEW_PARAMETERS = 'view-parameters',
 }
@@ -50,16 +56,19 @@ export const KeywordMapping: Record<Keyword, string[]> = {
   [Keyword.CLASSES]: ['Classes', '类'],
   [Keyword.COLON]: [':', '：'],
   [Keyword.COMMA]: [',', '，'],
+  [Keyword.CONSTRUCTOR]: ['Constructor', '构造函数'],
   [Keyword.CONSTRUCTORS]: ['Constructors', '构造函数'],
   [Keyword.DECORATOR]: ['Decorator', '装饰器'],
   [Keyword.DEFAULT_VALUE]: ['Default Value', '默认值'],
   [Keyword.DESCRIPTION]: ['Description', '描述'],
   [Keyword.ENUMERATION_MEMBERS]: ['Enumeration Members', '枚举成员'],
+  [Keyword.ENUMERATION]: ['Enumeration', '枚举'],
   [Keyword.ENUMERATIONS]: ['Enumerations', '枚举'],
   [Keyword.EVENTS]: ['Events', '事件'],
   [Keyword.EXAMPLE]: ['Example', '示例'],
   [Keyword.EXCEPTIONS]: ['Exceptions', '异常'],
   [Keyword.EXTENDS]: ['Extends', '继承自'],
+  [Keyword.FUNCTION]: ['Function', '函数'],
   [Keyword.FUNCTIONS]: ['Functions', '函数'],
   [Keyword.IMPLEMENTS]: ['Implements', '实现自'],
   [Keyword.INTERFACE]: ['Interface', '接口'],
@@ -68,6 +77,7 @@ export const KeywordMapping: Record<Keyword, string[]> = {
   [Keyword.METHOD]: ['Method', '方法'],
   [Keyword.METHODS]: ['Methods', '方法'],
   [Keyword.MODIFIERS]: ['Modifiers', '修饰符'],
+  [Keyword.NAMESPACE]: ['Namespace', '命名空间'],
   [Keyword.NAMESPACES]: ['Namespaces', '命名空间'],
   [Keyword.OPTIONAL]: ['Optional', '可选'],
   [Keyword.OPTIONS]: ['Options', '配置项'],
@@ -80,13 +90,12 @@ export const KeywordMapping: Record<Keyword, string[]> = {
   [Keyword.REMARKS]: ['Remarks', '备注'],
   [Keyword.RETURNS]: ['Returns', '返回值'],
   [Keyword.RIGHT_PARENTHESIS]: [')', '）'],
+  [Keyword.TYPE_ALIAS]: ['Type Alias', '类型别名'],
   [Keyword.TYPE_ALIASES]: ['Type Aliases', '类型别名'],
   [Keyword.TYPE]: ['Type', '类型'],
+  [Keyword.VARIABLE]: ['Variable', '变量'],
   [Keyword.VARIABLES]: ['Variables', '变量'],
   [Keyword.VIEW_PARAMETERS]: ['View Parameters', '相关参数'],
 };
 
-export const intl = (keyword: Keyword, language: LocaleLanguage) => {
-  const [en, zh] = KeywordMapping[keyword];
-  return language === LocaleLanguage.EN ? en : zh;
-};
+export const getKeywordIntl = getIntl(KeywordMapping);

packages/site/src/constants/locales/page.ts

@@ -1,8 +1,36 @@
+import { getIntl } from './common';
+
 export const PageTitle: Record<string, string[]> = {
   // graph
   GraphOptions: ['Options', '配置项'],
   GraphMethods: ['API', '方法'],
   GraphProperties: ['Properties', '属性'],
+  // element
+  ElementMethods: ['API', '方法'],
+  // element/node
+  BaseNode: ['BaseNode', '节点通用样式属性'],
+  Circle: ['Circle', '圆形'],
+  Diamond: ['Diamond', '菱形'],
+  Donut: ['Donut', '甜甜圈'],
+  Ellipse: ['Ellipse', '椭圆形'],
+  Hexagon: ['Hexagon', '六边形'],
+  Html: ['Html', 'HTML'],
+  Image: ['Image', '图片'],
+  Rect: ['Rect', '矩形'],
+  Star: ['Star', '五角形'],
+  Triangle: ['Triangle', '三角形'],
+  // element/edge
+  BaseEdge: ['BaseEdge', '边通用样式属性'],
+  Cubic: ['Cubic', '三次贝塞尔曲线'],
+  CubicHorizontal: ['CubicHorizontal', '水平三次贝塞尔曲线'],
+  CubicVertical: ['CubicVertical', '垂直三次贝塞尔曲线'],
+  Line: ['Line', '直线'],
+  Polyline: ['Polyline', '折线'],
+  Quadratic: ['Quadratic', '二次贝塞尔曲线'],
+  // element/combo
+  BaseCombo: ['BaseCombo', '组合基础样式属性'],
+  CircleCombo: ['Circle', '圆形'],
+  RectCombo: ['Rect', '矩形'],
   // layout
   AntvDagreLayout: ['AntvDagre', '布局'],
   CircularLayout: ['Circular', '环形布局'],
@@ -43,3 +71,12 @@ export const PageTitle: Record<string, string[]> = {
   Tooltip: ['Tooltip', '提示框'],
   Watermark: ['Watermark', '水印'],
 };
+
+// 节点、边、Combo 的中英文对照
+export const ElementLocale: Record<string, string[]> = {
+  node: ['Node', '节点'],
+  edge: ['Edge', '边'],
+  combo: ['Combo', '组合'],
+};
+
+export const getElementIntl = getIntl(ElementLocale);

packages/site/src/markdown/CustomMarkdownEmitter.ts

@@ -1,5 +1,6 @@
 import type { ApiItem, ApiModel, IResolveDeclarationReferenceResult } from '@microsoft/api-extractor-model';
 import type { DocLinkTag, DocNode, StringBuilder } from '@microsoft/tsdoc';
+import { DocContainer } from 'src/nodes/DocContainer';
 import { CustomDocNodeKind } from '../nodes/CustomDocNodeKind';
 import type { DocDetails } from '../nodes/DocDetails';
 import type { DocEmphasisSpan } from '../nodes/DocEmphasisSpan';
@@ -56,7 +57,10 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
             prefix = '####';
         }
 
-        writer.writeLine(prefix + ' ' + this.getEscapedText(docHeading.title));
+        const _prefix = docHeading.prefix ? docHeading.prefix + ' ' : '';
+        const _suffix = docHeading.suffix ? ' ' + docHeading.suffix : '';
+
+        writer.writeLine(prefix + ' ' + _prefix + this.getEscapedText(docHeading.title) + _suffix);
         writer.writeLine();
         break;
       }
@@ -147,7 +151,7 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
 
         writer.writeLine('---');
         writer.writeLine('title: ' + docPageTitle.title);
-        if (docPageTitle.order) {
+        if (docPageTitle.order !== undefined) {
           writer.ensureNewLine();
           writer.writeLine('order: ' + docPageTitle.order);
         }
@@ -185,6 +189,16 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
         writer.writeLine();
         break;
       }
+      case CustomDocNodeKind.Container: {
+        const container: DocContainer = docNode as DocContainer;
+        writer.ensureSkippedLine();
+        writer.write(`:::${container.status}` + (container.title ? `{title=${container.title}}` : ''));
+        writer.ensureNewLine();
+        this.writeNodes(container.getChildNodes(), context);
+        writer.write(':::');
+        writer.ensureSkippedLine();
+        break;
+      }
       default:
         super.writeNode(docNode, context, docNodeSiblings);
     }

packages/site/src/markdown/MarkdownEmitter.ts

@@ -62,7 +62,7 @@ export class MarkdownEmitter {
   protected getEscapedText(text: string): string {
     const textWithBackslashes: string = text
       .replace(/\\/g, '\\\\') // first replace the escape character
-      .replace(/[*#[\]_|`~]/g, (x) => '\\' + x) // then escape any special characters
+      .replace(/[*#\\_|~]/g, (x) => '\\' + x) // then escape any special characters, except `[`,`]`,```
       .replace(/---/g, '\\-\\-\\-') // hyphens only if it's 3 or more
       .replace(/&/g, '&')
       .replace(/</g, '&lt;')

packages/site/src/nodes/CustomDocNodeKind.ts

@@ -1,4 +1,5 @@
 import { DocNodeKind, TSDocConfiguration } from '@microsoft/tsdoc';
+import { DocContainer } from './DocContainer';
 import { DocDetails } from './DocDetails';
 import { DocEmphasisSpan } from './DocEmphasisSpan';
 import { DocHeading } from './DocHeading';
@@ -22,6 +23,7 @@ export const enum CustomDocNodeKind {
   PageTitle = 'PageTitle',
   Details = 'Details',
   UnorderedList = 'UnorderedList',
+  Container = 'Container',
 }
 
 export class CustomDocNodes {
@@ -53,6 +55,10 @@ export class CustomDocNodes {
           docNodeKind: CustomDocNodeKind.UnorderedList,
           constructor: DocUnorderedList,
         },
+        {
+          docNodeKind: CustomDocNodeKind.Container,
+          constructor: DocContainer,
+        },
       ]);
 
       configuration.docNodeManager.registerAllowableChildren(CustomDocNodeKind.EmphasisSpan, [
@@ -60,12 +66,14 @@ export class CustomDocNodes {
         DocNodeKind.SoftBreak,
         DocNodeKind.Paragraph,
         DocNodeKind.LinkTag,
+        DocNodeKind.CodeSpan,
       ]);
 
       configuration.docNodeManager.registerAllowableChildren(CustomDocNodeKind.UnorderedList, [
         DocNodeKind.PlainText,
         DocNodeKind.LinkTag,
         DocNodeKind.Paragraph,
+        DocNodeKind.CodeSpan,
       ]);
 
       configuration.docNodeManager.registerAllowableChildren(DocNodeKind.Section, [
@@ -74,6 +82,8 @@ export class CustomDocNodes {
         CustomDocNodeKind.Table,
         CustomDocNodeKind.PageTitle,
         CustomDocNodeKind.Details,
+        CustomDocNodeKind.Container,
+        CustomDocNodeKind.UnorderedList,
       ]);
 
       configuration.docNodeManager.registerAllowableChildren(DocNodeKind.Paragraph, [
@@ -81,6 +91,8 @@ export class CustomDocNodes {
         CustomDocNodeKind.UnorderedList,
       ]);
 
+      configuration.docNodeManager.registerAllowableChildren(CustomDocNodeKind.Container, [DocNodeKind.Paragraph]);
+
       CustomDocNodes._configuration = configuration;
     }
     return CustomDocNodes._configuration;

packages/site/src/nodes/DocContainer.ts

@@ -0,0 +1,38 @@
+import type { IDocNodeParameters } from '@microsoft/tsdoc';
+import { DocNode, DocSection } from '@microsoft/tsdoc';
+import { CustomDocNodeKind } from './CustomDocNodeKind';
+
+type ContainerStatus = 'info' | 'success' | 'warning' | 'error';
+/**
+ * Constructor parameters for {@link DocContainer}.
+ */
+export interface IDocContainerParameters extends IDocNodeParameters {
+  status?: ContainerStatus;
+  title?: string;
+}
+
+/**
+ * Represents a note box, which is typically displayed as a bordered box containing informational text.
+ */
+export class DocContainer extends DocNode {
+  public readonly content: DocSection;
+  public readonly status: 'info' | 'success' | 'warning' | 'error';
+  public readonly title: string | undefined;
+
+  public constructor(parameters: IDocContainerParameters, sectionChildNodes?: ReadonlyArray<DocNode>) {
+    super(parameters);
+    this.content = new DocSection({ configuration: this.configuration }, sectionChildNodes);
+    this.status = parameters.status || 'info';
+    this.title = parameters.title;
+  }
+
+  /** @override */
+  public get kind(): string {
+    return CustomDocNodeKind.Container;
+  }
+
+  /** @override */
+  protected onGetChildNodes(): ReadonlyArray<DocNode | undefined> {
+    return [this.content];
+  }
+}

packages/site/src/nodes/DocHeading.ts

@@ -8,6 +8,9 @@ import { CustomDocNodeKind } from './CustomDocNodeKind';
 export interface IDocHeadingParameters extends IDocNodeParameters {
   title: string;
   level?: number;
+  escaped?: boolean;
+  prefix?: string;
+  suffix?: string;
 }
 
 /**
@@ -16,11 +19,17 @@ export interface IDocHeadingParameters extends IDocNodeParameters {
 export class DocHeading extends DocNode {
   public readonly title: string;
   public readonly level: number;
+  public readonly escaped: boolean;
+  public readonly prefix: string;
+  public readonly suffix: string;
 
   public constructor(parameters: IDocHeadingParameters) {
     super(parameters);
     this.title = parameters.title;
     this.level = parameters.level !== undefined ? parameters.level : 1;
+    this.escaped = parameters.escaped || true;
+    this.prefix = parameters.prefix || '';
+    this.suffix = parameters.suffix || '';
 
     if (this.level < 1 || this.level > 5) {
       throw new Error('IDocHeadingParameters.level must be a number between 1 and 5');

packages/site/src/nodes/DocPageTitle.ts

@@ -1,7 +1,6 @@
 import type { IDocNodeParameters } from '@microsoft/tsdoc';
 import { DocNode } from '@microsoft/tsdoc';
-import { LocaleLanguage } from '../constants/locale';
-import { PageTitle } from '../constants/page';
+import { LocaleLanguage, PageTitle } from '../constants/locales';
 import { CustomDocNodeKind } from './CustomDocNodeKind';
 
 /**

packages/site/src/utils/Utilities.ts

@@ -23,7 +23,6 @@ export class Utilities {
   /**
    * Converts bad filename characters to underscores.
    * @param name - The name to convert.
-   * @returns The safe filename.
    */
   public static getSafeFilenameForName(name: string): string {
     // TODO: This can introduce naming collisions.

packages/site/src/utils/excerpt-token.ts

@@ -0,0 +1,139 @@
+import { ApiInterface, ApiModel, ExcerptTokenKind, type ExcerptToken } from '@microsoft/api-extractor-model';
+import { camelCase } from 'lodash';
+
+export type BaseExcerptToken = {
+  text: string;
+  canonicalReference?: ExcerptToken['canonicalReference'];
+  interface?: ApiInterface;
+  children?: ICustomExcerptToken[];
+  parent?: ICustomExcerptToken;
+};
+
+export type ICustomExcerptToken =
+  | ({
+      type: 'Prefix';
+      prefix: string;
+    } & BaseExcerptToken)
+  | ({
+      type: 'Omit' | 'Pick';
+      fields: string[];
+    } & BaseExcerptToken)
+  | ({ type: 'Default' } & BaseExcerptToken);
+
+/**
+ * 将 ExcerptToken 按 'Prefix'、'Omit'、'Pick'、'Default' 分类
+ * @param apiModel
+ * @param apiItem
+ * @param parentToken
+ * @param flatten
+ * @returns
+ */
+export function parseExcerptTokens(
+  apiModel: ApiModel,
+  apiItem: ApiInterface,
+  parentToken?: ICustomExcerptToken,
+  flatten?: boolean,
+): ICustomExcerptToken[] {
+  const customExcerptTokens: ICustomExcerptToken[] = [];
+  let flag = false;
+
+  for (const [index, token] of apiItem.excerptTokens.entries()) {
+    let customToken: ICustomExcerptToken | undefined = undefined;
+    if (token.kind === ExcerptTokenKind.Reference) {
+      const excludeTags = ['Record', 'Partial'];
+      if (excludeTags.includes(token.text)) continue;
+      if (token.text === 'Prefix') {
+        const content = apiItem.excerptTokens[index + 1].text;
+        const prefixMatch = content.match(/<\s*'(\w+)'/)!;
+        const referenceToken = apiItem.excerptTokens[index + 2];
+        customToken = {
+          type: token.text,
+          prefix: prefixMatch[1],
+          fields: undefined,
+          text: referenceToken.text,
+          canonicalReference: referenceToken.canonicalReference,
+        } as ICustomExcerptToken;
+        flag = true;
+      } else if (['Omit', 'Pick'].includes(token.text)) {
+        const content = apiItem.excerptTokens[index + 3].text;
+        const referenceToken = apiItem.excerptTokens[index + 2];
+        const fields = (content.match(/'(\w+)'/g) || []).map((x) => x.replace(/'/g, ''));
+        customToken = {
+          type: token.text,
+          fields: fields,
+          text: referenceToken.text,
+          canonicalReference: referenceToken.canonicalReference,
+        } as ICustomExcerptToken;
+        flag = true;
+      } else {
+        if (!flag) {
+          customToken = { type: 'Default', text: token.text, canonicalReference: token.canonicalReference };
+        }
+        flag = false;
+      }
+    }
+
+    if (customToken && customToken.canonicalReference) {
+      const resolvedApiItem = apiModel.resolveDeclarationReference(
+        customToken.canonicalReference,
+        undefined,
+      ).resolvedApiItem;
+      if (resolvedApiItem instanceof ApiInterface) {
+        customToken.interface = resolvedApiItem;
+        customToken.children = parseExcerptTokens(apiModel, resolvedApiItem, customToken);
+      }
+      customToken.parent = parentToken;
+      customExcerptTokens.push(customToken);
+    }
+  }
+
+  return customExcerptTokens;
+}
+
+export const liftPrefixExcerptTokens = (items: ICustomExcerptToken[]): ICustomExcerptToken[] => {
+  let topLevelPrefixes: ICustomExcerptToken[] = [];
+
+  for (const item of items) {
+    if (item.type === 'Prefix') {
+      const newItem = { ...item, prefix: getAccessorExcerptTokensPrefixes(item) };
+      topLevelPrefixes.push(newItem);
+    }
+
+    if (item.children && item.children.length > 0) {
+      const childPrefixes = liftPrefixExcerptTokens(item.children);
+      topLevelPrefixes = topLevelPrefixes.concat(childPrefixes);
+    }
+  }
+
+  return topLevelPrefixes;
+};
+
+/**
+ *
+ * @param targetToken
+ * @param includeSelf
+ */
+export function findAccessorExcerptTokens(targetToken: ICustomExcerptToken, includeSelf = true): ICustomExcerptToken[] {
+  let path: ICustomExcerptToken[] = [targetToken];
+  let currentToken = targetToken.parent;
+
+  while (currentToken) {
+    path = [currentToken, ...path];
+    currentToken = currentToken.parent;
+  }
+
+  return includeSelf ? path : path.slice(1);
+}
+
+/**
+ *
+ * @param targetToken
+ */
+export function getAccessorExcerptTokensPrefixes(targetToken: ICustomExcerptToken) {
+  const tokens = findAccessorExcerptTokens(targetToken);
+  const tokenString = tokens
+    .map((token) => (token as any).prefix || '')
+    .filter(Boolean)
+    .join(' ');
+  return camelCase(tokenString);
+}

packages/site/src/utils/parser.ts

@@ -1,10 +1,9 @@
 import type { DocBlock, DocComment, DocSection } from '@microsoft/tsdoc';
 
 /**
- * Get the block tag by name
- * @param tagName - The name of the block tag
- * @param docComment - The doc comment
- * @returns The block tag
+ *
+ * @param tagName
+ * @param docComment
  */
 export function getBlockTagByName(tagName: string, docComment: DocComment): DocSection | undefined {
   const tag = docComment.customBlocks.find((customBlock: DocBlock) => customBlock.blockTag.tagName === tagName);