How to Create TypeScript Documentation Websites

When you're building a TypeScript project, it's crucial to document your code for better understanding and collaboration with other developers. Documentation ensures that anyone working on or reviewing your code, especially those unfamiliar with certain aspects, can easily follow along.

Luckily, there are tools that can help you create professional documentation websites with just a few commands. In this guide, we’ll walk through the steps of creating documentation websites using TypeDoc.

Step 1: Add TSDoc to Your TypeScript Project

Before using TypeDoc, you need to incorporate TSDoc into your code. TSDoc is a standard for writing documentation comments in TypeScript, enabling tools like TypeDoc to extract and generate accurate documentation.

Here’s an example of what TSDoc comments look like:

/**
 * Returns the average of two numbers.
 * 
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 */
public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
}

If you're unfamiliar with TSDoc, it's worth reading the official documentation to get a deeper understanding.

Step 2: Install TypeDoc

Once you've added TSDoc comments to your project, it's time to install TypeDoc, the tool that will generate the documentation website. Run the following command in your terminal:

npm i typedoc --save-dev

This installs TypeDoc as a development dependency in your project.

Step 3: Add a Script to Generate Documentation

After installing TypeDoc, you can create a script to generate your documentation website. TypeDoc will look for your tsconfig.json file automatically, so you just need to specify the entry point of your project.

Edit your package.json and add the following script under the scripts field (replace src/index.ts with your actual entry point):

{
  "scripts": {
    "generate-docs": "typedoc src/index.ts"
  }
}

Customizing Documentation Generation

You can customize the documentation generation using TypeDoc's command-line arguments. For a full list of options, run typedoc --help or check out the TypeDoc documentation.

Here are a few useful options:

• --out <path/to/documentation/>: Defines where the documentation will be generated. By default, it’s written to ./docs.
• --json <path/to/output.json>: Generates a JSON file describing the project. No HTML documentation is created unless --out is also specified.
• --options <path/to/options.json>: Specifies a JSON configuration file for TypeDoc options.
• --tsconfig <path/to/tsconfig.json>: Manually specify the TypeScript config file. TypeDoc will automatically look for tsconfig.json if not provided.
• --exclude <pattern>: Exclude specific files or patterns from the documentation.

Step 4: Generate Your Documentation Website

Once your script is set up, you can generate your documentation by running the following command:

npm run generate-docs

TypeDoc will create a folder called docs in the root of your project. This folder contains all the necessary files for your documentation website.

Step 5: View the Documentation Website

After generating the documentation, open the docs folder, which will contain an index.html file—the entry point of your website.

To view your documentation:

1. Double-click the index.html file to open it in your browser.
2. Alternatively, copy the file path into your web browser’s address bar.

You’ll see a homepage similar to this:

The homepage typically displays your project’s README.md, with a sidebar listing all your project’s functions and classes. For example, here's the documentation for the isBoolean function from my project type-guards-ts:

Conclusion

By following these steps, you’ll create a fully functional documentation website for your TypeScript project, making it much easier for others to understand, navigate, and contribute. Proper documentation isn't just a good practice—it's essential for ensuring your project's long-term success.

While TypeDoc is a powerful tool, there are other packages that offer similar functionality, like TSDoc, Compodoc, and @microsoft/tsdoc. Each has its own strengths, so it’s worth exploring them to see which one fits your project best.

But enough from me I’d love to hear from you! Have you used any of these tools to generate documentation? Share your experiences in the comments below! 😄