tsdoc2docusaurus-ts

A CLI application to convert TSDoc files generated by api-extractor/api-documenter into Docusaurus documentation.

The converter parses the files generated by the api-documenter and produces .md files in the /docs/api/ folder. For precise control over presentation, the generated content is Markdown & HTML. As Docusaurus only parses Markdown section headers to automatically generate the Table of Contents, the converter outputs these headers in Markdown.

Work in progress.

Prerequisites

npm --prefix website @microsoft/api-extractor @microsoft/api-documenter --save-dev

In website/package.json

    "compile-tsdoc": "del-cli --force tsdoc/dist && tsc --project config/tsconfig-api-extractor.json",
    "api-extractor-init": "api-extractor init",
    "api-extractor": "api-extractor run --local --verbose",
    "patch-doc-model-json": "bash config/patch-doc-model-json.sh tsdoc/doc-model/website.api.json website @xpack/xpm-lib",
    "api-documenter": "del-cli --force tsdoc/markdown && api-documenter markdown --input-folder tsdoc/doc-model --output-folder tsdoc/markdown",
    "tsdoc2docusaurus": "tsdoc2docusaurus --id website",
    "generate-website-tsdoc": "npm run compile-tsdoc && npm run api-extractor && npm run patch-doc-model-json && npm run api-documenter && npm run tsdoc2docusaurus",

TypeScript configuration

api-extractor starts the project parsing from the compiled index.d.ts, and requires the original comments not be removed. For this be sure the compilerOptions.removeComments is not defined in the website/config/tsconfig-api-extractor.json!

  "compilerOptions": {
    "outDir": "../tsdoc/dist",
    // api-extractor reads the documentation from the comments in the compiled files.
    "removeComments": false, 
    // To show internal docs in the generated API reference.
    "stripInternal": false,
    // Only output d.ts files and not JavaScript files.
    "emitDeclarationOnly": true,
    // https://api-extractor.com/pages/setup/invoking/
    // This enables generation of the .d.ts files that API Extractor will 
    // analyze. By design, TypeScript source files are not directly analyzed, 
    // but instead must be first processed by your compiler.
    "declaration": true,
    // This enables generation of .d.ts.map files that allow API Extractor 
    // errors to be reported using line numbers from your original source 
    // files; without this, the error locations will instead refer to the 
    // generated .d.ts files.
    "declarationMap": true, 
    "sourceMap": false,

The api-extractor configuration

Add the config/api-extractor.json file.

{
  "mainEntryPointFilePath": "<projectFolder>/tsdoc/dist/index.d.ts",
  "bundledPackages": [],
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/config/tsconfig-api-extractor.json"
  },
  "apiReport": {
    "enabled": false
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/tsdoc/doc-model/website.api.json",
    "includeForgottenExports": true,
    "projectFolderUrl": "https://github.com/xpack/xpm-lib-ts.git/tree/development"
  },
  "dtsRollup": {
    "enabled": false
  },
  "tsdocMetadata": {
    "enabled": false
  },
  "messages": {
    "compilerMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    },
    "extractorMessageReporting": {
      "ae-missing-release-tag": {
        "logLevel": "none"
      },
      "default": {
        "logLevel": "warning"
      }
    },
    "tsdocMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    }
  }
}

Installing the Converter

• https://api-extractor.com/pages/overview/demo_docs/

To install the converter in your project’s website directory, run:

npm --prefix website install @xpack/tsdoc2docusaurus --save-dev

Alternatively, during development:

npm --prefix website link @xpack/tsdoc2docusaurus)

Converter Configuration

By default, the converter attempts to retrieve its configuration from the following places:

• the config/tsdoc2docusaurus.json file
• the tsdoc2docusaurus.json file
• the config.tsdoc2docusaurus object in package.json
• the tsdoc2docusaurus object in package.json

For example:

{
    "apiJsonInputFolderPath": "tsdoc/doc-model",
    "apiMarkdownInputFolderPath": "tsdoc/markdown",
    "apiFolderPath": "api",
    "baseUrl": "/xpm-lib-ts/",
    "apiBaseUrl": "api",
    "navbarFilePath": "docusaurus-config-navbar-tsdoc.json",
    "sidebarCategoryFilePath": "sidebar-category-tsdoc.json",
    "customCssFilePath": "src/css/custom-tsdoc2docusaurus.css",
    "navbarLabel": "API Reference",
    "navbarPosition": "left",
    "verbose": false,
    "debug": false
}

If your api-extractor files are located elsewhere, update the apiJsonInputFolderPath and apiMarkdownInputFolderPath properties accordingly.

The converter will process all .api.json files available within the input folder.

To simplify running the conversion, add a npm script to your website/package.json:

  "scripts": {
    "compile-tsdoc": "del-cli --force tsdoc/dist && tsc --project config/tsconfig-api-extractor.json",
    "api-extractor-init": "api-extractor init",
    "api-extractor": "api-extractor run --local --verbose",
    "patch-doc-model-json": "bash config/patch-doc-model-json.sh tsdoc/doc-model/website.api.json website @xpack/xpm-lib",
    "api-documenter": "del-cli --force tsdoc/markdown && api-documenter markdown --input-folder tsdoc/doc-model --output-folder tsdoc/markdown",
    "tsdoc2docusaurus": "tsdoc2docusaurus --id website",
    "generate-website-tsdoc": "npm run compile-tsdoc && npm run api-extractor && npm run patch-doc-model-json && npm run api-documenter && npm run tsdoc2docusaurus",
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    ...
  }

To execute the conversion, use:

npm run convert-tsdoc

If a web preview is the website/config/tsdoc2docusaurus.json can be:

{
  "webpreview": {
    "apiJsonInputFolderPath": "../api-extractor",
    "apiMarkdownInputFolderPath": "../api-extractor/markdown",
    "apiFolderPath": "api",
    "baseUrl": "/doxygen2docusaurus-cli-ts/",
    "apiBaseUrl": "api",
    "navbarFilePath": "docusaurus-config-navbar-tsdoc.json",
    "sidebarCategoryFilePath": "sidebar-category-tsdoc.json",
    "customCssFilePath": "src/css/custom-tsdoc2docusaurus.css",
    "navbarLabel": "API Reference",
    "navbarPosition": "left",
    "verbose": false,
    "debug": false
  },
  "website": {
    "apiJsonInputFolderPath": "../api-extractor",
    "apiMarkdownInputFolderPath": "../api-extractor/markdown",
    "apiFolderPath": "api",
    "baseUrl": "/doxygen2docusaurus/",
    "apiBaseUrl": "api",
    "navbarFilePath": "docusaurus-config-navbar-tsdoc.json",
    "sidebarCategoryFilePath": "sidebar-category-tsdoc.json",
    "customCssFilePath": "src/css/custom-tsdoc2docusaurus.css",
    "navbarLabel": "API Reference",
    "navbarPosition": "left",
    "verbose": false,
    "debug": false
  }
}

Common Markdown

As MDX syntax is particularly strict and does not support all HTML content, the output is Common Markdown.

To configure Docusaurus to parse .md files as Common Markdown, add the following to your docusaurus-config.ts file:

  markdown: {
    format: 'detect'
  },

CSS

The converter generates a file containing custom CSS definitions.

To include this in Docusaurus, edit your docusaurus-config.ts file and add the following line to the theme configuration:

  theme: {
    customCss: [
      './src/css/custom.css',
      './src/css/custom-tsdoc2docusaurus.css'
    ],
  },

Sidebar

The converter generates a dedicated sidebar for the TSDoc pages.

To integrate this into Docusaurus, edit your sidebars.ts file and add the following import at the top:

import tsdocSidebarItems from './sidebar-category-tsdoc2docusaurus.json';

Subsequently, add a new property to the sidebars object:

const sidebars: SidebarsConfig = {

  docsSidebar: [
    // ...
  ],

  tsdocSidebar: [
    tsdocSidebarItems,
  ],
};

Top Menu

The converter also generates a dropdown menu entry for integration into the top navigation bar.

To incorporate this into Docusaurus, first edit your docusaurus-config.ts file and add the following import at the top:

import tsdocApiMenu from './docusaurus-config-navbar-tsdoc.json'

Subsequently, add tsdocApiMenu to the navbar.items array, for example, between the Documentation and Blog drop-downs.

TSDoc Guide

See the separate TSDOC-GUIDE file.