docusaurus-plugin-typedoc-api
    TypeScript icon, indicating that this package has built-in type declarations

    1.6.1 • Public • Published

    docusaurus-plugin-typedoc-api

    Build Status npm version npm deps

    A Docusaurus plugin for generating source code /api/* routes, powered by TypeDoc.

    The plugin has been designed to document your public API by default (anything exported from a package's entry point), so any private, protected, or internal code will not be generated.

    Requirements

    • typescript >= v4
    • @docusaurus/core >= v2.0.0-beta.7
    • @docusaurus/preset-classic >= v2.0.0-beta.7

    Examples

    Installation

    yarn add --dev docusaurus-plugin-typedoc-api
    

    Open your docusaurus.config.js and make the following changes:

    • Add a link to the API route under themeConfig.navbar.items and themeConfig.footer.links (if desired).
    module.exports = {
    	// ...
    	themeConfig: {
    		// ...
    		navbar: {
    			// ...
    			items: [
    				// ...
    				{
    					to: 'api',
    					label: 'API',
    					position: 'left',
    				},
    			],
    		},
    	},
    };
    • Configure the plugin in your plugins list. The projectRoot and packages options are required.
    module.exports = {
    	// ...
    	plugins: [
    		[
    			'docusaurus-plugin-typedoc-api',
    			{
    				projectRoot: path.join(__dirname, '..'),
    				// Monorepo
    				packages: ['packages/example', 'packages/other'],
    				// Polyrepo
    				packages: ['.'],
    			},
    		],
    	],
    };

    Configuration

    The following options are available to the plugin:

    • projectRoot (string) - Absolute path to the project root where tsconfig.json is located. (Required)
    • packages ((string | PackageConfig)[]) - List of packages relative to the project root. (Required)
    • exclude (string[]) - List of glob patterns to exclude unwanted packages. This is necessary when using TypeScript project references.
    • minimal (boolean) - Render a minimal layout and reduce the amount of information displayed. Defaults to false.
    • packageJsonName (string) - Name of the package.json file. Defaults to package.json.
    • readmeName (string) - Name of the readme file within a package. Defaults to README.md.
    • readmes (boolean) - Include and render the readme file from every package. Defaults to false.
    • tsconfigName (string) - Name of the TypeScript config file in the project root. Defaults to tsconfig.json.
    • typedocOptions (object) - TypeDoc options to pass to the compiler. Only supports a small subset of options, primarily around visibility exclusion.

    Packages

    The packages option has been designed to support multiple packages, with multiple entry points per package. By default the option accepts a list of strings, where each value is a relative path to a package folder, and a default entry point of src/index.ts.

    module.exports = {
    	packages: ['packages/core', 'packages/react'],
    };

    However, an object can be provided to customize the entry point. All entry point file paths are relative to the package folder, and support 2 formats:

    • Index imports - Consumers can only import from the package index. This is typically an entry point like src/index.ts.
    • Deep imports - Consumers can import anything from the package using its file path. Glob the entire package by only passing the folder name like src/. (This is useful for component libraries)
    module.exports = {
    	packages: [
    		'packages/core',
    		{
    			path: 'packages/react',
    			// Index only imports allowed
    			// import {} from 'package'
    			entry: 'src/index.tsx',
    			// Deep imports allowed
    			// import {} from 'package/some/nested/file'
    			entry: 'src/',
    		},
    	],
    };

    When not using deep imports, multiple entry points can be defined by passing a map of objects to entry, where each key is a sub-path that can be imported from the package (excluding the index). Each entry object requires a path and a label, which is used for categorizing and sidebars.

    module.exports = {
    	packages: [
    		'packages/core',
    		{
    			path: 'packages/react',
    			entry: {
    				// import {} from 'package'
    				index: 'src/index.tsx',
    				// import {} from 'package/client'
    				client: { file: 'src/client.tsx', label: 'Client' },
    				// import {} from 'package/server'
    				server: { file: 'src/server.tsx', label: 'Server' },
    				// import {} from 'package/server/test'
    				'server/test': { file: 'src/server/test-utils.tsx', label: 'Server test utils' },
    			},
    		},
    	],
    };

    Index entry points don't require a label, so a file path can be passed directly.

    Install

    npm i docusaurus-plugin-typedoc-api

    DownloadsWeekly Downloads

    150

    Version

    1.6.1

    License

    MIT

    Unpacked Size

    348 kB

    Total Files

    180

    Last publish

    Collaborators

    • milesj