Skip to content
On this page

API Extractor and Vitepress


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 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 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": "",
  "mainEntryPointFilePath": "./lib/",
  "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 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.


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';

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.