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!