Docusaurus Yarn Typedoc Watch

Introduction

Docusaurus is a modern static site generator developed by Facebook. It allows you to build, deploy, and maintain static websites with ease. Yarn is a package manager that optimizes the installation process of JavaScript packages. Typedoc is a documentation generator for TypeScript projects. In this article, we will explore how to use Docusaurus, Yarn, and Typedoc together to generate and watch documentation for your TypeScript project.

Prerequisites

Before we begin, make sure you have the following installed:

  • Node.js (version 12 or above)
  • Yarn (version 1.x)
  • Docusaurus (version 2.x)

Setting Up a Docusaurus Project

To start, let's create a new Docusaurus project by running the following commands in your terminal:

npx @docusaurus/init@latest init my-docs classic
cd my-docs

This will create a new Docusaurus project in the my-docs directory. You can replace my-docs with your preferred project name.

Installing Typedoc

Next, let's install Typedoc as a dev dependency in your project:

yarn add --dev typedoc

This will add Typedoc to your project's devDependencies in the package.json file.

Configuring Typedoc

Create a typedoc.json file in the root of your project and add the following configuration:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "mode": "modules",
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeExternals": true,
  "excludeNotExported": true,
  "excludeInternal": true,
  "theme": "default"
}

Here, we are specifying the entry point of our TypeScript files (src/index.ts), the output directory for the generated documentation (docs), and various exclusion options.

Generating Initial Documentation

Before setting up the watch command, let's generate the initial documentation using Typedoc. Add the following script to your package.json file:

{
  "scripts": {
    "docs:generate": "typedoc"
  }
}

Now, you can generate the documentation by running:

yarn docs:generate

This will create the documentation in the docs directory.

Watching for Changes

To watch for changes in your TypeScript files and automatically regenerate the documentation, we will use a combination of Docusaurus and Typedoc. Add the following script to your package.json file:

{
  "scripts": {
    "docs:watch": "yarn docusaurus start --port 3000 & yarn typedoc --watch"
  }
}

Here, we are using the start command of Docusaurus to run the development server on port 3000 (yarn docusaurus start --port 3000) and the --watch flag of Typedoc to watch for changes in your TypeScript files (yarn typedoc --watch).

Now, you can start the development server with watch mode by running:

yarn docs:watch

This will start both Docusaurus and Typedoc in watch mode. Any changes made to your TypeScript files will trigger the regeneration of the documentation, and you can view the updated documentation in your browser at http://localhost:3000.

Conclusion

In this article, we have learned how to use Docusaurus, Yarn, and Typedoc together to generate and watch documentation for your TypeScript project. With this setup, you can easily maintain and update your project's documentation as you develop. Remember to run yarn docs:generate initially to generate the documentation and yarn docs:watch to start watching for changes. Happy documenting!