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.
{
"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,
}
}
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)
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 inpackage.json
- the
tsdoc2docusaurus
object inpackage.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
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'
},
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'
],
},
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,
],
};
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.