Skip to content

A CLI application to convert TSDoc files into Docusaurus documentation

License

Notifications You must be signed in to change notification settings

xpack/tsdoc2docusaurus-cli-ts

Repository files navigation

tsdoc2docusaurus-ts

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

The converter parses the api-extractor files and produces .md files in the /docs/api/ directory. 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.

api-extractor configuration

{
  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/src/tsconfig.json",
  },
  "apiReport": {
    "enabled": true,
    "reportTempFolder": "<projectFolder>/api-extractor/",
    "includeForgottenExports": true
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/api-extractor/<unscopedPackageName>.api.json",
    "includeForgottenExports": true
  }
}

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 top tsconfig.json, for example:

{
  "extends": "@tsconfig/node20/tsconfig.json",
  "compilerOptions": {
    /* Visit https://aka.ms/tsconfig to read more about this file */
    /* https://www.npmjs.com/package/@tsconfig/node20 */

    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    // "removeComments": true,

    "forceConsistentCasingInFileNames": true,
  }
}

Installing the Converter

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

(cd website; npm install @xpack/tsdoc2docusaurus --save-dev)

Alternatively, during development:

(cd website; npm 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": "../api-extractor",
  "apiMarkdownInputFolderPath": "../api-extractor/markdown",
  "baseUrl": "/my-project-ts/",
  "verbose": true,
  "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": {
    "docusaurus": "docusaurus",
    "convert-tsdoc": "tsdoc2docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    ...
  }

To execute the conversion, use:

npm run convert-tsdoc

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 dropdowns.

About

A CLI application to convert TSDoc files into Docusaurus documentation

Resources

License

Stars

Watchers

Forks

Sponsor this project

Packages

No packages published