From 52401a0784d9c7be03b4096f0d82e571f08f62d0 Mon Sep 17 00:00:00 2001
From: 0xKermini <67284748+lukebaze@users.noreply.github.com>
Date: Tue, 31 Mar 2026 10:52:53 +0700
Subject: [PATCH] feat: create docheading node type for markdown headings

Create a new DocNode type to represent Markdown headings in the TSDoc AST. This will be similar to DocParagraph but will store heading level and text content.

Affected files: DocHeading.ts

Signed-off-by: 0xKermini <67284748+lukebaze@users.noreply.github.com>
---
 tsdoc/src/nodes/DocHeading.ts | 63 +++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 tsdoc/src/nodes/DocHeading.ts

diff --git a/tsdoc/src/nodes/DocHeading.ts b/tsdoc/src/nodes/DocHeading.ts
new file mode 100644
index 00000000..70c59ae3
--- /dev/null
+++ b/tsdoc/src/nodes/DocHeading.ts
@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { DocNode, type IDocNodeParameters } from './DocNode';
+import { DocNodeContainer, type IDocNodeContainerParameters } from './DocNodeContainer';
+import { DocNodeKind } from './DocNodeKind';
+
+/**
+ * Constructor parameters for {@link DocHeading}.
+ */
+export interface IDocHeadingParameters extends IDocNodeContainerParameters {
+  /**
+   * The heading level from 1 to 6, similar to Markdown headings.
+   */
+  headingLevel?: number;
+}
+
+/**
+ * Represents a heading section in the documentation, similar to Markdown headings (#, ##, etc.).
+ *
+ * @remarks
+ * This node type stores a heading level (1-6) and contains the heading content as child nodes.
+ */
+export class DocHeading extends DocNodeContainer {
+  private static _kind: string = DocNodeKind.Heading;
+  private _headingLevel: number;
+
+  public constructor(parameters: IDocHeadingParameters | DocHeading) {
+    super(parameters);
+    if (parameters instanceof DocHeading) {
+      this._headingLevel = parameters._headingLevel;
+    } else {
+      this._headingLevel = parameters.headingLevel ?? 1;
+    }
+  }
+
+  /** @override */
+  public get kind(): string {
+    return DocHeading._kind;
+  }
+
+  /**
+   * The heading level from 1 to 6.
+   */
+  public get headingLevel(): number {
+    return this._headingLevel;
+  }
+
+  /**
+   * Sets the heading level (must be between 1 and 6).
+   */
+  public set headingLevel(value: number) {
+    if (value < 1 || value > 6) {
+      throw new Error('Heading level must be between 1 and 6');
+    }
+    this._headingLevel = value;
+  }
+
+  /** @override */
+  protected onGetChildNodes(): ReadonlyArray<DocNode> {
+    return this.nodes;
+  }
+}