API Extractor and Vitepress ​

Introduction ​

I'm creating a lot of documentation for the projects I'm working on. To keep the quality, each method and interface should be documented. It's a lot of work, but it's worth it. Having good documentation is very important because it helps to understand the project and use it properly.

However, I don't want to write the same documentation twice. I want to have it in the code and the docs. To achieve that, I'm using API Extractor to generate the API reference from the code.

Vitepress is a great tool to generate documentation. It's fast, easy to use, and has a lot of features.

Let's see how to combine these two tools to create great documentation.

Project setup ​

For TypeScript projects, I like to have a file with all the types, that I want to show in the documentation. I call it api-extractor.data.ts and it looks like this:

/**
 * Description of the package.
 *
 * @packageDocumentation
 */
export * from './types';
export * from './methods';
// other exports

During the build, It's compiled to api-extractor.data.d.ts file, which is used by API Extractor to generate the API reference.

To build the project, I'm using rollup.

API Extractor ​

Let's start with the setup of API Extractor.

First, install the necessary packages:

npm install -D @microsoft/api-extractor @microsoft/api-documenter
# op
yarn add -D @microsoft/api-extractor @microsoft/api-documenter

Then, create a config file api-extractor.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "./lib/api-extractor.data.d.ts",
  "projectFolder": ".",
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/api-reference/<unscopedPackageName>.api.json"
  },
  // other options
}

That's the configuration I'm using. As mainEntryPointFilePath I'm using the path to built api-extractor.data.ts file.

I'm also setting the projectFolder to the root of the project, so I don't have to specify the path to the tsconfig.json file.

apiJsonFilePath is the path to the file with the API reference in JSON format. It's used by @microsoft/api-documenter to generate markdown files. In this example, it will be generated in the api-reference folder.

To generate the API reference, run the following command:

npm run api-extractor run --local
# or
yarn api-extractor run --local

The API reference will be generated in the api-reference folder.

To generate the markdown files, I'm using the following command:

npm run api-documenter markdown --i <INPUT> --o <OUTPUT>
# or
yarn api-documenter markdown --i <INPUT> --o <OUTPUT>

<INPUT> is the path to the api-reference folder, and <OUTPUT> is the path to the folder where the markdown files will be generated.

Vitepress ​

Creating a Vitepress documentation from a markdown files is done by default. As soon as the api-documenter generates the markdown files, we can use them in Vitepress.

However, it might be tricky, especially when it comes to the files generated by API Extractor tool. I faced a problem Duplicate attribute. when I tried to build the docs.

Of course, the markdown files were looking good, so it was not so obvious what was wrong.

After some investigation, I found a workaround solution, which is pretty simple.

import { defineConfig } from 'vitepress';

// https://vitepress.dev/reference/site-config
export default defineConfig({

  // ...

  markdown: {
    attrs: { disable: true }
  }
});

Disabling markdown attributes in Vitepress config solves the problem and by doing that, we can enjoy the API reference generated by API Extractor in our Vitepress docs.