/**
 * @license
 * Copyright 2022 Google Inc.
 * SPDX-License-Identifier: Apache-2.0
 */

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the
// MIT license. See LICENSE in the project root for license information.

// Taken from
// https://github.com/microsoft/rushstack/blob/main/apps/api-documenter/src/documenters/MarkdownDocumenter.ts
// This file has been edited to morph into Docusaurus's expected inputs.

import * as path from 'node:path';

import type {DocumenterConfig} from '@microsoft/api-documenter/lib/documenters/DocumenterConfig.js';
import {CustomMarkdownEmitter as ApiFormatterMarkdownEmitter} from '@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter.js';
import {CustomDocNodes} from '@microsoft/api-documenter/lib/nodes/CustomDocNodeKind.js';
import {DocEmphasisSpan} from '@microsoft/api-documenter/lib/nodes/DocEmphasisSpan.js';
import {DocHeading} from '@microsoft/api-documenter/lib/nodes/DocHeading.js';
import {DocNoteBox} from '@microsoft/api-documenter/lib/nodes/DocNoteBox.js';
import {DocTable} from '@microsoft/api-documenter/lib/nodes/DocTable.js';
import {DocTableCell} from '@microsoft/api-documenter/lib/nodes/DocTableCell.js';
import {DocTableRow} from '@microsoft/api-documenter/lib/nodes/DocTableRow.js';
import {MarkdownDocumenterAccessor} from '@microsoft/api-documenter/lib/plugin/MarkdownDocumenterAccessor.js';
import {
  type IMarkdownDocumenterFeatureOnBeforeWritePageArgs,
  MarkdownDocumenterFeatureContext,
} from '@microsoft/api-documenter/lib/plugin/MarkdownDocumenterFeature.js';
import {PluginLoader} from '@microsoft/api-documenter/lib/plugin/PluginLoader.js';
import {Utilities} from '@microsoft/api-documenter/lib/utils/Utilities.js';
import {
  ApiClass,
  ApiDeclaredItem,
  ApiDocumentedItem,
  type ApiEnum,
  ApiInitializerMixin,
  ApiInterface,
  type ApiItem,
  ApiItemKind,
  type ApiModel,
  type ApiNamespace,
  ApiOptionalMixin,
  type ApiPackage,
  ApiParameterListMixin,
  ApiPropertyItem,
  ApiProtectedMixin,
  ApiReadonlyMixin,
  ApiReleaseTagMixin,
  ApiReturnTypeMixin,
  ApiStaticMixin,
  ApiTypeAlias,
  type Excerpt,
  type ExcerptToken,
  ExcerptTokenKind,
  type IResolveDeclarationReferenceResult,
  ReleaseTag,
} from '@microsoft/api-extractor-model';
import {
  type DocBlock,
  DocCodeSpan,
  type DocComment,
  DocFencedCode,
  DocLinkTag,
  type DocNodeContainer,
  DocNodeKind,
  DocParagraph,
  DocPlainText,
  DocSection,
  StandardTags,
  StringBuilder,
  DocHtmlStartTag,
  DocHtmlEndTag,
  DocHtmlAttribute,
  type TSDocConfiguration,
} from '@microsoft/tsdoc';
import {
  FileSystem,
  NewlineKind,
  PackageName,
} from '@rushstack/node-core-library';

export interface IMarkdownDocumenterOptions {
  apiModel: ApiModel;
  documenterConfig: DocumenterConfig | undefined;
  outputFolder: string;
}

export class CustomMarkdownEmitter extends ApiFormatterMarkdownEmitter {
  protected override getEscapedText(text: string): string {
    const textWithBackslashes = text
      .replace(/\\/g, '\\\\') // first replace the escape character
      .replace(/[*#[\]_|`~]/g, x => {
        return '\\' + x;
      }) // then escape any special characters
      .replace(/---/g, '\\-\\-\\-') // hyphens only if it's 3 or more
      .replace(/&/g, '&')
      .replace(/</g, '&lt;')
      .replace(/>/g, '&gt;')
      .replace(/\{/g, '&#123;')
      .replace(/\}/g, '&#125;');
    return textWithBackslashes;
  }
}

/**
 * Renders API documentation in the Markdown file format.
 * For more info: https://en.wikipedia.org/wiki/Markdown
 */
export class MarkdownDocumenter {
  private readonly _apiModel: ApiModel;
  private readonly _documenterConfig: DocumenterConfig | undefined;
  private readonly _tsdocConfiguration: TSDocConfiguration;
  private readonly _markdownEmitter: CustomMarkdownEmitter;
  private readonly _outputFolder: string;
  private readonly _pluginLoader: PluginLoader;

  public constructor(options: IMarkdownDocumenterOptions) {
    this._apiModel = options.apiModel;
    this._documenterConfig = options.documenterConfig;
    this._outputFolder = options.outputFolder;
    this._tsdocConfiguration = CustomDocNodes.configuration;
    this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);

    this._pluginLoader = new PluginLoader();
  }

  public generateFiles(): void {
    if (this._documenterConfig) {
      this._pluginLoader.load(this._documenterConfig, () => {
        return new MarkdownDocumenterFeatureContext({
          apiModel: this._apiModel,
          outputFolder: this._outputFolder,
          documenter: new MarkdownDocumenterAccessor({
            getLinkForApiItem: (apiItem: ApiItem) => {
              return this._getLinkFilenameForApiItem(apiItem);
            },
          }),
        });
      });
    }

    this._deleteOldOutputFiles();

    this._writeApiItemPage(this._apiModel.members[0]!);

    if (this._pluginLoader.markdownDocumenterFeature) {
      this._pluginLoader.markdownDocumenterFeature.onFinished({});
    }
  }

  private _getBaseApiItemPage(apiItem: ApiItem): DocSection {
    const configuration = this._tsdocConfiguration;
    const output = new DocSection({
      configuration,
    });

    const scopedName = apiItem.getScopedNameWithinPackage();
    switch (apiItem.kind) {
      case ApiItemKind.Class:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} class`}),
        );
        break;
      case ApiItemKind.Enum:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} enum`}),
        );
        break;
      case ApiItemKind.Interface:
        output.appendNode(
          new DocHeading({
            configuration,
            title: `${scopedName} interface`,
          }),
        );
        break;
      case ApiItemKind.Constructor:
      case ApiItemKind.ConstructSignature:
        output.appendNode(new DocHeading({configuration, title: scopedName}));
        break;
      case ApiItemKind.Method:
      case ApiItemKind.MethodSignature:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} method`}),
        );
        break;
      case ApiItemKind.Function:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} function`}),
        );
        break;
      case ApiItemKind.Model:
        output.appendNode(
          new DocHeading({configuration, title: `API Reference`}),
        );
        break;
      case ApiItemKind.Namespace:
        output.appendNode(
          new DocHeading({
            configuration,
            title: `${scopedName} namespace`,
          }),
        );
        break;
      case ApiItemKind.Package:
        console.log(`Writing ${apiItem.displayName} package`);
        output.appendNode(
          new DocHeading({
            configuration,
            title: `API Reference`,
          }),
        );
        break;
      case ApiItemKind.Property:
      case ApiItemKind.PropertySignature:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} property`}),
        );
        break;
      case ApiItemKind.TypeAlias:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} type`}),
        );
        break;
      case ApiItemKind.Variable:
        output.appendNode(
          new DocHeading({configuration, title: `${scopedName} variable`}),
        );
        break;
      default:
        throw new Error('Unsupported API item kind: ' + apiItem.kind);
    }

    return output;
  }

  private _getApiItemPage(apiItem: ApiItem): DocSection {
    const configuration = this._tsdocConfiguration;
    const output = new DocSection({
      configuration,
    });

    if (
      apiItem instanceof ApiDeclaredItem &&
      apiItem.excerpt.text.length > 0 &&
      ApiParameterListMixin.isBaseClassOf(apiItem) &&
      ApiReturnTypeMixin.isBaseClassOf(apiItem) &&
      apiItem.getMergedSiblings().length > 1
    ) {
      const overloadId = this._getOverloadElementId(apiItem.overloadIndex);

      // TODO: See if we don't need to create all of the on our own.
      const overLoadHeader = `${apiItem.displayName}(): ${apiItem.returnTypeExcerpt.text}`;
      output.appendNode(
        new DocParagraph({configuration}, [
          new DocHtmlStartTag({
            configuration,
            name: 'h2',
            htmlAttributes: [
              new DocHtmlAttribute({
                configuration,
                name: 'id',
                value: `"${overloadId}"`,
              }),
            ],
          }),
          new DocPlainText({
            configuration,
            text: overLoadHeader,
          }),
          new DocHtmlEndTag({
            configuration,
            name: 'h2',
          }),
        ]),
      );
    }

    if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) {
      if (apiItem.releaseTag === ReleaseTag.Beta) {
        this._writeBetaWarning(output);
      }
    }

    const decoratorBlocks: DocBlock[] = [];

    if (apiItem instanceof ApiDocumentedItem) {
      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;

      if (tsdocComment) {
        decoratorBlocks.push(
          ...tsdocComment.customBlocks.filter(block => {
            return (
              block.blockTag.tagNameWithUpperCase ===
              StandardTags.decorator.tagNameWithUpperCase
            );
          }),
        );

        if (tsdocComment.deprecatedBlock) {
          output.appendNode(
            new DocNoteBox({configuration: this._tsdocConfiguration}, [
              new DocParagraph({configuration: this._tsdocConfiguration}, [
                new DocPlainText({
                  configuration,
                  text: 'Warning: This API is now obsolete. ',
                }),
              ]),
              ...tsdocComment.deprecatedBlock.content.nodes,
            ]),
          );
        }

        this._appendSection(output, tsdocComment.summarySection);
      }
    }

    if (apiItem instanceof ApiDeclaredItem && apiItem.excerpt.text.length > 0) {
      let code: string | undefined;
      switch (apiItem.parent?.kind) {
        case ApiItemKind.Class:
          code = `class ${
            apiItem.parent.displayName
          } {${apiItem.getExcerptWithModifiers()}}`;
          break;
        case ApiItemKind.Interface:
          code = `interface ${
            apiItem.parent.displayName
          } {${apiItem.getExcerptWithModifiers()}}`;
          break;
        default:
          code = apiItem.getExcerptWithModifiers();
      }
      if (code) {
        output.appendNode(
          new DocHeading({
            configuration,
            title: 'Signature',
            level: 3,
          }),
        );
        output.appendNode(
          new DocFencedCode({
            configuration,
            code: code,
            language: 'typescript',
          }),
        );
      }

      this._writeHeritageTypes(output, apiItem);
    }

    if (decoratorBlocks.length > 0) {
      output.appendNode(
        new DocHeading({configuration, title: 'Decorators:', level: 4}),
      );
      for (const decoratorBlock of decoratorBlocks) {
        output.appendNodes(decoratorBlock.content.nodes);
      }
    }

    let appendRemarks = true;
    switch (apiItem.kind) {
      case ApiItemKind.Class:
      case ApiItemKind.Interface:
      case ApiItemKind.Namespace:
      case ApiItemKind.Package:
        this._writeRemarksSection(output, apiItem);
        appendRemarks = false;
        break;
    }

    switch (apiItem.kind) {
      case ApiItemKind.Class:
        this._writeClassTables(output, apiItem as ApiClass);
        break;
      case ApiItemKind.Enum:
        this._writeEnumTables(output, apiItem as ApiEnum);
        break;
      case ApiItemKind.Interface:
        this._writeInterfaceTables(output, apiItem as ApiInterface);
        break;
      case ApiItemKind.Constructor:
      case ApiItemKind.ConstructSignature:
      case ApiItemKind.Method:
      case ApiItemKind.MethodSignature:
      case ApiItemKind.Function:
        this._writeParameterTables(output, apiItem as ApiParameterListMixin);
        this._writeThrowsSection(output, apiItem);
        break;
      case ApiItemKind.Namespace:
        this._writePackageOrNamespaceTables(output, apiItem as ApiNamespace);
        break;
      case ApiItemKind.Model:
        this._writeModelTable(output, apiItem as ApiModel);
        break;
      case ApiItemKind.Package:
        this._writePackageOrNamespaceTables(output, apiItem as ApiPackage);
        break;
      case ApiItemKind.Property:
      case ApiItemKind.PropertySignature:
        break;
      case ApiItemKind.TypeAlias:
        break;
      case ApiItemKind.Variable:
        break;
      default:
        throw new Error('Unsupported API item kind: ' + apiItem.kind);
    }

    this._writeDefaultValueSection(output, apiItem);

    if (appendRemarks) {
      this._writeRemarksSection(output, apiItem);
    }

    return output;
  }

  private _writeApiItemPage(apiItem: ApiItem) {
    const output = this._getBaseApiItemPage(apiItem);
    if (ApiParameterListMixin.isBaseClassOf(apiItem)) {
      if (apiItem.overloadIndex > 1) {
        return;
      }

      for (const item of apiItem.getMergedSiblings()) {
        const itemOutput = this._getApiItemPage(item);
        output.appendNodes(itemOutput.nodes);
      }
    } else {
      const itemOutput = this._getApiItemPage(apiItem);
      output.appendNodes(itemOutput.nodes);
    }

    const filename = path.join(
      this._outputFolder,
      this._getFilenameForApiItem(apiItem),
    );
    const stringBuilder = new StringBuilder();
    this._markdownEmitter.emit(stringBuilder, output, {
      contextApiItem: apiItem,
      onGetFilenameForApiItem: (apiItemForFilename: ApiItem) => {
        return this._getLinkFilenameForApiItem(apiItemForFilename);
      },
    });

    let pageContent = stringBuilder.toString();

    if (this._pluginLoader.markdownDocumenterFeature) {
      // Allow the plugin to customize the pageContent
      const eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs = {
        apiItem: apiItem,
        outputFilename: filename,
        pageContent: pageContent,
      };
      this._pluginLoader.markdownDocumenterFeature.onBeforeWritePage(eventArgs);
      pageContent = eventArgs.pageContent;
    }

    pageContent =
      `---\nsidebar_label: ${this._getSidebarLabelForApiItem(apiItem)}\n---` +
      pageContent;
    pageContent = pageContent.replace('##', '#');
    pageContent = pageContent.replace(/<!-- -->/g, '');
    pageContent = pageContent.replace(/\\\*\\\*/g, '**');
    pageContent = pageContent.replace(/<b>|<\/b>/g, '**');
    FileSystem.writeFile(filename, pageContent, {
      convertLineEndings: this._documenterConfig
        ? this._documenterConfig.newlineKind
        : NewlineKind.CrLf,
    });
  }

  private _writeHeritageTypes(
    output: DocSection,
    apiItem: ApiDeclaredItem,
  ): void {
    const configuration = this._tsdocConfiguration;

    if (apiItem instanceof ApiClass) {
      if (apiItem.extendsType) {
        const extendsParagraph = new DocParagraph({configuration}, [
          new DocEmphasisSpan({configuration, bold: true}, [
            new DocPlainText({configuration, text: 'Extends: '}),
          ]),
        ]);
        this._appendExcerptWithHyperlinks(
          extendsParagraph,
          apiItem.extendsType.excerpt,
        );
        output.appendNode(extendsParagraph);
      }
      if (apiItem.implementsTypes.length > 0) {
        const extendsParagraph = new DocParagraph({configuration}, [
          new DocEmphasisSpan({configuration, bold: true}, [
            new DocPlainText({configuration, text: 'Implements: '}),
          ]),
        ]);
        let needsComma = false;
        for (const implementsType of apiItem.implementsTypes) {
          if (needsComma) {
            extendsParagraph.appendNode(
              new DocPlainText({configuration, text: ', '}),
            );
          }
          this._appendExcerptWithHyperlinks(
            extendsParagraph,
            implementsType.excerpt,
          );
          needsComma = true;
        }
        output.appendNode(extendsParagraph);
      }
    }

    if (apiItem instanceof ApiInterface) {
      if (apiItem.extendsTypes.length > 0) {
        const extendsParagraph = new DocParagraph({configuration}, [
          new DocEmphasisSpan({configuration, bold: true}, [
            new DocPlainText({configuration, text: 'Extends: '}),
          ]),
        ]);
        let needsComma = false;
        for (const extendsType of apiItem.extendsTypes) {
          if (needsComma) {
            extendsParagraph.appendNode(
              new DocPlainText({configuration, text: ', '}),
            );
          }
          this._appendExcerptWithHyperlinks(
            extendsParagraph,
            extendsType.excerpt,
          );
          needsComma = true;
        }
        output.appendNode(extendsParagraph);
      }
    }

    if (apiItem instanceof ApiTypeAlias) {
      const refs: ExcerptToken[] = apiItem.excerptTokens.filter(token => {
        return (
          token.kind === ExcerptTokenKind.Reference &&
          token.canonicalReference &&
          this._apiModel.resolveDeclarationReference(
            token.canonicalReference,
            undefined,
          ).resolvedApiItem
        );
      });
      if (refs.length > 0) {
        const referencesParagraph = new DocParagraph({configuration}, [
          new DocEmphasisSpan({configuration, bold: true}, [
            new DocPlainText({configuration, text: 'References: '}),
          ]),
        ]);
        let needsComma = false;
        const visited = new Set<string>();
        for (const ref of refs) {
          if (visited.has(ref.text)) {
            continue;
          }
          visited.add(ref.text);

          if (needsComma) {
            referencesParagraph.appendNode(
              new DocPlainText({configuration, text: ', '}),
            );
          }

          this._appendExcerptTokenWithHyperlinks(referencesParagraph, ref);
          needsComma = true;
        }
        output.appendNode(referencesParagraph);
      }
    }
  }

  private _writeDefaultValueSection(output: DocSection, apiItem: ApiItem) {
    if (apiItem instanceof ApiDocumentedItem) {
      const block = apiItem.tsdocComment?.customBlocks.find(block => {
        return (
          block.blockTag.tagNameWithUpperCase ===
          StandardTags.defaultValue.tagNameWithUpperCase
        );
      });
      if (block) {
        output.appendNode(
          new DocHeading({
            configuration: this._tsdocConfiguration,
            title: 'Default value:',
            level: 4,
          }),
        );
        this._appendSection(output, block.content);
      }
    }
  }

  private _writeRemarksSection(output: DocSection, apiItem: ApiItem): void {
    const configuration = this._tsdocConfiguration;

    if (apiItem instanceof ApiDocumentedItem) {
      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;

      if (tsdocComment) {
        // Write the @remarks block
        if (tsdocComment.remarksBlock) {
          output.appendNode(
            new DocHeading({
              configuration,
              title: 'Remarks',
            }),
          );
          this._appendSection(output, tsdocComment.remarksBlock.content);
        }

        // Write the @example blocks
        const exampleBlocks: DocBlock[] = tsdocComment.customBlocks.filter(
          x => {
            return (
              x.blockTag.tagNameWithUpperCase ===
              StandardTags.example.tagNameWithUpperCase
            );
          },
        );

        let exampleNumber = 1;
        for (const exampleBlock of exampleBlocks) {
          const heading: string =
            exampleBlocks.length > 1 ? `Example ${exampleNumber}` : 'Example';

          output.appendNode(
            new DocHeading({
              configuration,
              title: heading,
            }),
          );

          this._appendSection(output, exampleBlock.content);

          ++exampleNumber;
        }
      }
    }
  }

  private _writeThrowsSection(output: DocSection, apiItem: ApiItem): void {
    if (apiItem instanceof ApiDocumentedItem) {
      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;

      if (tsdocComment) {
        // Write the @throws blocks
        const throwsBlocks: DocBlock[] = tsdocComment.customBlocks.filter(x => {
          return (
            x.blockTag.tagNameWithUpperCase ===
            StandardTags.throws.tagNameWithUpperCase
          );
        });

        if (throwsBlocks.length > 0) {
          const heading = 'Exceptions';
          output.appendNode(
            new DocHeading({
              configuration: this._tsdocConfiguration,
              title: heading,
            }),
          );

          for (const throwsBlock of throwsBlocks) {
            this._appendSection(output, throwsBlock.content);
          }
        }
      }
    }
  }

  /**
   * GENERATE PAGE: MODEL
   */
  private _writeModelTable(output: DocSection, apiModel: ApiModel): void {
    const configuration = this._tsdocConfiguration;

    const packagesTable = new DocTable({
      configuration,
      headerTitles: ['Package', 'Description'],
    });

    for (const apiMember of apiModel.members) {
      const row = new DocTableRow({configuration}, [
        this._createTitleCell(apiMember),
        this._createDescriptionCell(apiMember),
      ]);

      switch (apiMember.kind) {
        case ApiItemKind.Package:
          packagesTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;
      }
    }

    if (packagesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Packages',
        }),
      );
      output.appendNode(packagesTable);
    }
  }

  /**
   * GENERATE PAGE: PACKAGE or NAMESPACE
   */
  private _writePackageOrNamespaceTables(
    output: DocSection,
    apiContainer: ApiPackage | ApiNamespace,
  ): void {
    const configuration = this._tsdocConfiguration;

    const classesTable = new DocTable({
      configuration,
      headerTitles: ['Class', 'Description'],
    });

    const enumerationsTable = new DocTable({
      configuration,
      headerTitles: ['Enumeration', 'Description'],
    });

    const functionsTable = new DocTable({
      configuration,
      headerTitles: ['Function', 'Description'],
    });

    const interfacesTable = new DocTable({
      configuration,
      headerTitles: ['Interface', 'Description'],
    });

    const namespacesTable = new DocTable({
      configuration,
      headerTitles: ['Namespace', 'Description'],
    });

    const variablesTable = new DocTable({
      configuration,
      headerTitles: ['Variable', 'Description'],
    });

    const typeAliasesTable = new DocTable({
      configuration,
      headerTitles: ['Type Alias', 'Description'],
    });

    const apiMembers: readonly ApiItem[] =
      apiContainer.kind === ApiItemKind.Package
        ? (apiContainer as ApiPackage).entryPoints[0]!.members
        : (apiContainer as ApiNamespace).members;

    for (const apiMember of apiMembers) {
      const row = new DocTableRow({configuration}, [
        this._createTitleCell(apiMember),
        this._createDescriptionCell(apiMember),
      ]);

      switch (apiMember.kind) {
        case ApiItemKind.Class:
          classesTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;

        case ApiItemKind.Enum:
          enumerationsTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;

        case ApiItemKind.Interface:
          interfacesTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;

        case ApiItemKind.Namespace:
          namespacesTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;

        case ApiItemKind.Function:
          functionsTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;

        case ApiItemKind.TypeAlias:
          typeAliasesTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;

        case ApiItemKind.Variable:
          variablesTable.addRow(row);
          this._writeApiItemPage(apiMember);
          break;
      }
    }

    if (classesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Classes',
        }),
      );
      output.appendNode(classesTable);
    }

    if (enumerationsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Enumerations',
        }),
      );
      output.appendNode(enumerationsTable);
    }
    if (functionsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Functions',
        }),
      );
      output.appendNode(functionsTable);
    }

    if (interfacesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Interfaces',
        }),
      );
      output.appendNode(interfacesTable);
    }

    if (namespacesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Namespaces',
        }),
      );
      output.appendNode(namespacesTable);
    }

    if (variablesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Variables',
        }),
      );
      output.appendNode(variablesTable);
    }

    if (typeAliasesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Type Aliases',
        }),
      );
      output.appendNode(typeAliasesTable);
    }
  }

  /**
   * GENERATE PAGE: CLASS
   */
  private _writeClassTables(output: DocSection, apiClass: ApiClass): void {
    const configuration = this._tsdocConfiguration;

    const eventsTable = new DocTable({
      configuration,
      headerTitles: ['Property', 'Modifiers', 'Type', 'Description'],
    });

    const constructorsTable = new DocTable({
      configuration,
      headerTitles: ['Constructor', 'Modifiers', 'Description'],
    });

    const propertiesTable = new DocTable({
      configuration,
      headerTitles: ['Property', 'Modifiers', 'Type', 'Description'],
    });

    const methodsTable = new DocTable({
      configuration,
      headerTitles: ['Method', 'Modifiers', 'Description'],
    });

    for (const apiMember of apiClass.members) {
      switch (apiMember.kind) {
        case ApiItemKind.Constructor: {
          constructorsTable.addRow(
            new DocTableRow({configuration}, [
              this._createTitleCell(apiMember),
              this._createModifiersCell(apiMember),
              this._createDescriptionCell(apiMember),
            ]),
          );

          this._writeApiItemPage(apiMember);
          break;
        }
        case ApiItemKind.Method: {
          methodsTable.addRow(
            new DocTableRow({configuration}, [
              this._createTitleCell(apiMember),
              this._createModifiersCell(apiMember),
              this._createDescriptionCell(apiMember),
            ]),
          );

          this._writeApiItemPage(apiMember);
          break;
        }
        case ApiItemKind.Property: {
          if ((apiMember as ApiPropertyItem).isEventProperty) {
            eventsTable.addRow(
              new DocTableRow({configuration}, [
                this._createTitleCell(apiMember, true),
                this._createModifiersCell(apiMember),
                this._createPropertyTypeCell(apiMember),
                this._createDescriptionCell(apiMember),
              ]),
            );
          } else {
            propertiesTable.addRow(
              new DocTableRow({configuration}, [
                this._createTitleCell(apiMember, true),
                this._createModifiersCell(apiMember),
                this._createPropertyTypeCell(apiMember),
                this._createDescriptionCell(apiMember),
              ]),
            );
          }
          break;
        }
      }
    }

    if (eventsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Events',
        }),
      );
      output.appendNode(eventsTable);
    }

    if (constructorsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Constructors',
        }),
      );
      output.appendNode(constructorsTable);
    }

    if (propertiesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Properties',
        }),
      );
      output.appendNode(propertiesTable);
    }

    if (methodsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Methods',
        }),
      );
      output.appendNode(methodsTable);
    }
  }

  /**
   * GENERATE PAGE: ENUM
   */
  private _writeEnumTables(output: DocSection, apiEnum: ApiEnum): void {
    const configuration = this._tsdocConfiguration;

    const enumMembersTable = new DocTable({
      configuration,
      headerTitles: ['Member', 'Value', 'Description'],
    });

    for (const apiEnumMember of apiEnum.members) {
      enumMembersTable.addRow(
        new DocTableRow({configuration}, [
          new DocTableCell({configuration}, [
            new DocParagraph({configuration}, [
              new DocPlainText({
                configuration,
                text: Utilities.getConciseSignature(apiEnumMember),
              }),
            ]),
          ]),
          this._createInitializerCell(apiEnumMember),
          this._createDescriptionCell(apiEnumMember),
        ]),
      );
    }

    if (enumMembersTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Enumeration Members',
        }),
      );
      output.appendNode(enumMembersTable);
    }
  }

  /**
   * GENERATE PAGE: INTERFACE
   */
  private _writeInterfaceTables(
    output: DocSection,
    apiClass: ApiInterface,
  ): void {
    const configuration = this._tsdocConfiguration;

    const eventsTable = new DocTable({
      configuration,
      headerTitles: ['Property', 'Modifiers', 'Type', 'Description'],
    });

    const propertiesTable = new DocTable({
      configuration,
      headerTitles: ['Property', 'Modifiers', 'Type', 'Description', 'Default'],
    });

    const methodsTable = new DocTable({
      configuration,
      headerTitles: ['Method', 'Description'],
    });

    for (const apiMember of apiClass.members) {
      switch (apiMember.kind) {
        case ApiItemKind.ConstructSignature:
        case ApiItemKind.MethodSignature: {
          methodsTable.addRow(
            new DocTableRow({configuration}, [
              this._createTitleCell(apiMember),
              this._createDescriptionCell(apiMember),
            ]),
          );

          this._writeApiItemPage(apiMember);
          break;
        }
        case ApiItemKind.PropertySignature: {
          if ((apiMember as ApiPropertyItem).isEventProperty) {
            eventsTable.addRow(
              new DocTableRow({configuration}, [
                this._createTitleCell(apiMember, true),
                this._createModifiersCell(apiMember),
                this._createPropertyTypeCell(apiMember),
                this._createDescriptionCell(apiMember),
              ]),
            );
          } else {
            propertiesTable.addRow(
              new DocTableRow({configuration}, [
                this._createTitleCell(apiMember, true),
                this._createModifiersCell(apiMember),
                this._createPropertyTypeCell(apiMember),
                this._createDescriptionCell(apiMember),
                this._createDefaultCell(apiMember),
              ]),
            );
          }
          break;
        }
      }
    }

    if (eventsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Events',
        }),
      );
      output.appendNode(eventsTable);
    }

    if (propertiesTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Properties',
        }),
      );
      output.appendNode(propertiesTable);
    }

    if (methodsTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Methods',
        }),
      );
      output.appendNode(methodsTable);
    }
  }

  /**
   * GENERATE PAGE: FUNCTION-LIKE
   */
  private _writeParameterTables(
    output: DocSection,
    apiParameterListMixin: ApiParameterListMixin,
  ): void {
    const configuration = this._tsdocConfiguration;

    const parametersTable = new DocTable({
      configuration,
      headerTitles: ['Parameter', 'Type', 'Description'],
    });
    for (const apiParameter of apiParameterListMixin.parameters) {
      const parameterDescription = new DocSection({configuration});

      if (apiParameter.isOptional) {
        parameterDescription.appendNodesInParagraph([
          new DocEmphasisSpan({configuration, italic: true}, [
            new DocPlainText({configuration, text: '(Optional)'}),
          ]),
          new DocPlainText({configuration, text: ' '}),
        ]);
      }

      if (apiParameter.tsdocParamBlock) {
        this._appendAndMergeSection(
          parameterDescription,
          apiParameter.tsdocParamBlock.content,
        );
      }

      parametersTable.addRow(
        new DocTableRow({configuration}, [
          new DocTableCell({configuration}, [
            new DocParagraph({configuration}, [
              new DocPlainText({configuration, text: apiParameter.name}),
            ]),
          ]),
          new DocTableCell({configuration}, [
            this._createParagraphForTypeExcerpt(
              apiParameter.parameterTypeExcerpt,
            ),
          ]),
          new DocTableCell({configuration}, parameterDescription.nodes),
        ]),
      );
    }

    if (parametersTable.rows.length > 0) {
      output.appendNode(
        new DocHeading({
          configuration,
          title: 'Parameters',
        }),
      );
      output.appendNode(parametersTable);
    }

    if (ApiReturnTypeMixin.isBaseClassOf(apiParameterListMixin)) {
      const returnTypeExcerpt: Excerpt =
        apiParameterListMixin.returnTypeExcerpt;
      output.appendNode(
        new DocParagraph({configuration}, [
          new DocEmphasisSpan({configuration, bold: true}, [
            new DocPlainText({configuration, text: 'Returns:'}),
          ]),
        ]),
      );

      output.appendNode(this._createParagraphForTypeExcerpt(returnTypeExcerpt));

      if (apiParameterListMixin instanceof ApiDocumentedItem) {
        if (
          apiParameterListMixin.tsdocComment &&
          apiParameterListMixin.tsdocComment.returnsBlock
        ) {
          this._appendSection(
            output,
            apiParameterListMixin.tsdocComment.returnsBlock.content,
          );
        }
      }
    }
  }

  private _createParagraphForTypeExcerpt(excerpt: Excerpt): DocParagraph {
    const configuration = this._tsdocConfiguration;

    const paragraph = new DocParagraph({configuration});
    if (!excerpt.text.trim()) {
      paragraph.appendNode(
        new DocPlainText({configuration, text: '(not declared)'}),
      );
    } else {
      this._appendExcerptWithHyperlinks(paragraph, excerpt);
    }

    return paragraph;
  }

  private _appendExcerptWithHyperlinks(
    docNodeContainer: DocNodeContainer,
    excerpt: Excerpt,
  ): void {
    for (const token of excerpt.spannedTokens) {
      this._appendExcerptTokenWithHyperlinks(docNodeContainer, token);
    }
  }

  private _appendExcerptTokenWithHyperlinks(
    docNodeContainer: DocNodeContainer,
    token: ExcerptToken,
  ): void {
    const configuration = this._tsdocConfiguration;

    // Markdown doesn't provide a standardized syntax for hyperlinks inside code
    // spans, so we will render the type expression as DocPlainText.  Instead of
    // creating multiple DocParagraphs, we can simply discard any newlines and
    // let the renderer do normal word-wrapping.
    const unwrappedTokenText = token.text.replace(/[\r\n]+/g, ' ');

    // If it's hyperlinkable, then append a DocLinkTag
    if (token.kind === ExcerptTokenKind.Reference && token.canonicalReference) {
      const apiItemResult: IResolveDeclarationReferenceResult =
        this._apiModel.resolveDeclarationReference(
          token.canonicalReference,
          undefined,
        );

      if (apiItemResult.resolvedApiItem) {
        docNodeContainer.appendNode(
          new DocLinkTag({
            configuration,
            tagName: StandardTags.link.tagName,
            linkText: unwrappedTokenText,
            urlDestination: this._getLinkFilenameForApiItem(
              apiItemResult.resolvedApiItem,
            ),
          }),
        );
        return;
      }
    }

    // Otherwise append non-hyperlinked text
    docNodeContainer.appendNode(
      new DocPlainText({configuration, text: unwrappedTokenText}),
    );
  }

  private _createTitleCell(apiItem: ApiItem, plain = false): DocTableCell {
    const configuration = this._tsdocConfiguration;

    const text = Utilities.getConciseSignature(apiItem);

    return new DocTableCell({configuration}, [
      new DocParagraph({configuration}, [
        new DocHtmlStartTag({
          configuration,
          name: 'span',
          htmlAttributes: [
            new DocHtmlAttribute({
              configuration,
              name: 'id',
              value: `"${Utilities.getSafeFilenameForName(apiItem.displayName)}"`,
            }),
          ],
        }),
        plain
          ? new DocPlainText({configuration, text})
          : new DocLinkTag({
              configuration,
              tagName: '@link',
              linkText: text,
              urlDestination: this._getLinkFilenameForApiItem(apiItem),
            }),
        new DocHtmlEndTag({
          configuration,
          name: 'span',
        }),
      ]),
    ]);
  }

  /**
   * This generates a DocTableCell for an ApiItem including the summary section
   * and "(BETA)" annotation.
   *
   * @remarks
   * We mostly assume that the input is an ApiDocumentedItem, but it's easier to
   * perform this as a runtime check than to have each caller perform a type
   * cast.
   */
  private _createDescriptionCell(apiItem: ApiItem): DocTableCell {
    const configuration = this._tsdocConfiguration;

    const section = new DocSection({configuration});

    if (ApiReleaseTagMixin.isBaseClassOf(apiItem)) {
      if (apiItem.releaseTag === ReleaseTag.Beta) {
        section.appendNodesInParagraph([
          new DocEmphasisSpan({configuration, bold: true, italic: true}, [
            new DocPlainText({configuration, text: '(BETA)'}),
          ]),
          new DocPlainText({configuration, text: ' '}),
        ]);
      }
    }

    if (apiItem instanceof ApiDocumentedItem) {
      const isExperimental =
        apiItem.tsdocComment?.modifierTagSet.isExperimental();
      if (isExperimental) {
        section.appendNodesInParagraph([
          new DocEmphasisSpan({configuration, bold: true, italic: true}, [
            new DocPlainText({configuration, text: '(Experimental)'}),
          ]),
          new DocPlainText({configuration, text: ' '}),
        ]);
      }
    }

    if (apiItem instanceof ApiDocumentedItem) {
      if (apiItem.tsdocComment !== undefined) {
        this._appendAndMergeSection(
          section,
          apiItem.tsdocComment.summarySection,
        );

        if (apiItem.tsdocComment.deprecatedBlock) {
          section.appendNode(
            new DocParagraph({configuration}, [
              new DocEmphasisSpan({configuration, bold: true}, [
                new DocPlainText({configuration, text: 'Deprecated: '}),
              ]),
            ]),
          );

          section.appendNodes(
            apiItem.tsdocComment.deprecatedBlock.content.getChildNodes(),
          );
        }
      }
    }

    if (apiItem instanceof ApiDocumentedItem) {
      const remarks = apiItem.tsdocComment?.remarksBlock;
      if (remarks) {
        section.appendNode(
          new DocParagraph({configuration}, [
            new DocEmphasisSpan({configuration, bold: true}, [
              new DocPlainText({configuration, text: 'Remarks: '}),
            ]),
          ]),
        );

        section.appendNodes(remarks.content.getChildNodes());
      }
    }

    return new DocTableCell({configuration}, section.nodes);
  }

  private _createDefaultCell(apiItem: ApiItem): DocTableCell {
    const configuration = this._tsdocConfiguration;

    if (apiItem instanceof ApiDocumentedItem) {
      const block = apiItem.tsdocComment?.customBlocks.find(block => {
        return (
          block.blockTag.tagNameWithUpperCase ===
          StandardTags.defaultValue.tagNameWithUpperCase
        );
      });
      if (block !== undefined) {
        return new DocTableCell({configuration}, block.content.getChildNodes());
      }
    }

    return new DocTableCell({configuration}, []);
  }

  private _createModifiersCell(apiItem: ApiItem): DocTableCell {
    const configuration = this._tsdocConfiguration;

    const section = new DocSection({configuration});

    const codes = [];

    if (ApiProtectedMixin.isBaseClassOf(apiItem)) {
      if (apiItem.isProtected) {
        codes.push('protected');
      }
    }

    if (ApiReadonlyMixin.isBaseClassOf(apiItem)) {
      if (apiItem.isReadonly) {
        codes.push('readonly');
      }
    }

    if (ApiStaticMixin.isBaseClassOf(apiItem)) {
      if (apiItem.isStatic) {
        codes.push('static');
      }
    }

    if (ApiOptionalMixin.isBaseClassOf(apiItem)) {
      if (apiItem.isOptional) {
        codes.push('optional');
      }
    }

    if (apiItem instanceof ApiDocumentedItem) {
      if (apiItem.tsdocComment?.deprecatedBlock) {
        codes.push('deprecated');
      }
    }
    if (codes.length) {
      section.appendNode(
        new DocParagraph({configuration}, [
          new DocCodeSpan({configuration, code: codes.join(', ')}),
        ]),
      );
    }

    return new DocTableCell({configuration}, section.nodes);
  }

  private _createPropertyTypeCell(apiItem: ApiItem): DocTableCell {
    const configuration = this._tsdocConfiguration;

    const section = new DocSection({configuration});

    if (apiItem instanceof ApiPropertyItem) {
      section.appendNode(
        this._createParagraphForTypeExcerpt(apiItem.propertyTypeExcerpt),
      );
    }

    return new DocTableCell({configuration}, section.nodes);
  }

  private _createInitializerCell(apiItem: ApiItem): DocTableCell {
    const configuration = this._tsdocConfiguration;

    const section = new DocSection({configuration});

    if (ApiInitializerMixin.isBaseClassOf(apiItem)) {
      if (apiItem.initializerExcerpt) {
        section.appendNodeInParagraph(
          new DocCodeSpan({
            configuration,
            code: apiItem.initializerExcerpt.text,
          }),
        );
      }
    }

    return new DocTableCell({configuration}, section.nodes);
  }

  private _writeBetaWarning(output: DocSection): void {
    const configuration = this._tsdocConfiguration;
    const betaWarning =
      'This API is provided as a preview for developers and may change' +
      ' based on feedback that we receive.  Do not use this API in a production environment.';
    output.appendNode(
      new DocNoteBox({configuration}, [
        new DocParagraph({configuration}, [
          new DocPlainText({configuration, text: betaWarning}),
        ]),
      ]),
    );
  }

  private _appendSection(output: DocSection, docSection: DocSection): void {
    for (const node of docSection.nodes) {
      output.appendNode(node);
    }
  }

  private _appendAndMergeSection(
    output: DocSection,
    docSection: DocSection,
  ): void {
    let firstNode = true;
    for (const node of docSection.nodes) {
      if (firstNode) {
        if (node.kind === DocNodeKind.Paragraph) {
          output.appendNodesInParagraph(node.getChildNodes());
          firstNode = false;
          continue;
        }
      }
      firstNode = false;

      output.appendNode(node);
    }
  }

  private _getSidebarLabelForApiItem(apiItem: ApiItem): string {
    if (apiItem.kind === ApiItemKind.Package) {
      return 'API';
    }

    let baseName = '';
    for (const hierarchyItem of apiItem.getHierarchy()) {
      // For overloaded methods, add a suffix such as "MyClass.myMethod_2".
      let qualifiedName = hierarchyItem.displayName;
      if (ApiParameterListMixin.isBaseClassOf(hierarchyItem)) {
        if (hierarchyItem.overloadIndex > 1) {
          // Subtract one for compatibility with earlier releases of API Documenter.
          qualifiedName += `_${hierarchyItem.overloadIndex - 1}`;
        }
      }

      switch (hierarchyItem.kind) {
        case ApiItemKind.Model:
        case ApiItemKind.EntryPoint:
        case ApiItemKind.EnumMember:
        case ApiItemKind.Package:
          break;
        default:
          baseName += qualifiedName + '.';
      }
    }
    return baseName.slice(0, baseName.length - 1);
  }

  private _getFilenameForApiItem(apiItem: ApiItem, link = false): string {
    if (apiItem.kind === ApiItemKind.Package) {
      return 'index.md';
    }

    let baseName = '';
    let suffix = '';
    for (const hierarchyItem of apiItem.getHierarchy()) {
      // For overloaded methods, add a suffix such as "MyClass.myMethod_2".
      const qualifiedName = Utilities.getSafeFilenameForName(
        hierarchyItem.displayName,
      );

      switch (hierarchyItem.kind) {
        case ApiItemKind.Model:
        case ApiItemKind.EntryPoint:
        case ApiItemKind.EnumMember:
        // Properties don't have separate pages
        case ApiItemKind.Property:
        case ApiItemKind.PropertySignature:
          break;
        case ApiItemKind.Package:
          baseName = Utilities.getSafeFilenameForName(
            PackageName.getUnscopedName(hierarchyItem.displayName),
          );
          break;
        default:
          baseName += '.' + qualifiedName;
      }

      if (link) {
        switch (hierarchyItem.kind) {
          case ApiItemKind.Property:
          case ApiItemKind.PropertySignature:
            suffix =
              '#' +
              Utilities.getSafeFilenameForName(
                PackageName.getUnscopedName(hierarchyItem.displayName),
              );
            break;
        }
      }
    }

    if (
      ApiParameterListMixin.isBaseClassOf(apiItem) &&
      apiItem.overloadIndex > 1
    ) {
      suffix = `#${this._getOverloadElementId(apiItem.overloadIndex)}`;
    }

    return `${baseName}.md${suffix}`;
  }

  private _getLinkFilenameForApiItem(apiItem: ApiItem): string {
    return './' + this._getFilenameForApiItem(apiItem, true);
  }

  private _deleteOldOutputFiles(): void {
    console.log('Deleting old output from ' + this._outputFolder);
    FileSystem.ensureEmptyFolder(this._outputFolder);
  }

  private _getOverloadElementId(overloadIndex: number): string {
    return `overload-${overloadIndex}`;
  }
}