Skip to content

citkane/typedoc-plugin-hot-dev

Repository files navigation

codecov RELEASE AND PUBLISH GitHub Npm docs stable docs dev

🔥 Typedoc-Plugin-Hot-Dev

This is a helper for TypeDoc theme development.

Think 'create-react-app' live server - just for TypeDoc.

  • Quick compile for media asset updates (eg. css)
  • Slow(er) compile for source files (documents get rebuilt).
  • Works with all typedoc entrypoint strategies.
  • Automatically opens in your browser



Hot development usage

npm i -D typedoc-plugin-hot-dev
npx hot-dev #please set up options first

Programatic usage

import { init } from 'typedoc-hot-plugin-hot-dev';

// do your pre-processing logic, sass, etc.

init([, options]);



Options

Options can be passed into init(options) or defined in typedoc.json under the key of "hot-dev":{...}

key Description Type Required Default Value
sourceDist The relative path to the root of your theme's tsc compiled code. Hot-dev watches here for source changes, so if it is not the default you must define it. string no "dist"
targetCwd The relative path to the root of the project that you want to build documentation for. The default is documentation for the theme you are developing. string no "./"
npmScripts Scripts defined in your package.json.scripts which you may want to run in a non-blocking fashion, eg. sass in watch mode. string[] no []



Footnote

When, and only when, targeting an external project to build docs for your development theme (ie. targetCwd is pointing to a project that is not the theme you are developing), at that location you are likely to install the theme you are developing as so:

npm install ../path/to/typedoc-theme-yourtheme/dist

This will create a symlink to your theme in the ./node_modules folder of your external project.

This will cause Typedoc's peerdependency to fail when running hot-dev. This is an issue with node.

To work around this, from your theme directory directory, do:

npm install ../some/other/project/node_modules/typedoc

This will ensure that typedoc instance is always from the highest level.

After hot development work is done , do something like this in your theme to restore sanity:

npm remove typedoc
npm i -D typedoc

and fix package.json with:

	"peerDependencies": {
		"typedoc": "^0.23.0" //or whatever version is relevant
	}



Development Guidelines and howto's

Please refer to the Wiki Page.