npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@apify/docusaurus-plugin-typedoc-api

v4.2.10

Published

Docusaurus plugin that provides source code API documentation powered by TypeDoc.

Downloads

731

Readme

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
  • @docusaurus/preset-classic >= v2.0.0

Examples

  • Boost - https://boostlib.dev/api

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)
  • banner (string) - Banner message to display at the top of the index page. Supports HTML.
  • changelogName (string) - Name of the changelog file within a package. Defaults to CHANGELOG.md.
  • changelogs (boolean) - Include and render the changelog file from every package. Defaults to false.
  • exclude (string[]) - List of glob patterns to exclude unwanted packages. This is necessary when using TypeScript project references.
  • gitRefName (string) - GitHub repository ref name to point the API links to. Defaults to master.
  • 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.
  • rehypePlugins (MDXPlugin[]) - List of rehype plugins to use for MDX compilation.
  • remarkPlugins (MDXPlugin[]) - List of remark plugins to use for MDX compilation.
  • removeScopes (string[]) - Package scopes and prefixes to remove when displaying the package name in the sidebar and index. For example, boost will remove @boost/ and boost-.
  • sortPackages ((a, d) => number) - Function to sort the package list in the sidebar and on the index page. Defaults to alphabetical.
  • sortSidebar ((a, d) => number) - Function to sort the categories and items within each sidebar, excluding "Overview" and "Changelog". Defaults to alphabetical.
  • 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: { path: 'src/client.tsx', label: 'Client' },
        // import {} from 'package/server'
        server: { path: 'src/server.tsx', label: 'Server' },
        // import {} from 'package/server/test'
        'server/test': { path: '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.

Linking

This plugin supports API and documentation linking within source code docblocks via the @apilink and @doclink tokens respectively. This works in a similar fashion to TypeDoc's @link resolution, but also supports Docusaurus versioning and routing patterns.

@apilink

When linking to other APIs, you must reference them by class name, function name, property, etc, instead of the actual /api route.

# Maps to /api/<package>/class/Registry#register
{@apilink Registry.register}
{@apilink Registry.register | Text to use as the label}

@doclink

When linking to documentation pages, you must reference the article by its URL identifier without the /docs prefix.

# Maps to /docs/commands/setup
{@doclink commands/setup}
{@doclink commands/setup | Text to use as the label}

Versioning

This plugin supports API versioning by piggy-backing off the built-in docs versioning implementation, which is a requirement for this to work correctly.

To begin, version your docs with the built-in command:

yarn docusaurus docs:version 1.2.3

Once the markdown files are generated, run our versioning command with the same version used previously:

yarn docusaurus api:version 1.2.3

This will create multiple JSON files in the versioned_docs/version-1.2.3 directory. Be sure to commit these files to your repo.

When versioning, the current state of your branch will be used as that version's API. To update/regenerate old versions, you'll need to checkout an old commit, re-version, and copy the generated files to the latest branch.

Navigation

Our API is unable to use the docsVersionDropdown navigation type, as it's hardcoded in Docusaurus core. However, you can create a custom version dropdown like so:

const versions = require('./versions.json');

module.exports = {
  // ...
  themeConfig: {
    // ...
    navbar: {
      // ...
      items: [
        // ...
        {
          type: 'dropdown',
          to: 'api',
          label: 'API',
          position: 'left',
          items: [
            { label: 'Next', to: 'api/next' },
            ...versions.map((version, i) => ({
              label: version,
              to: i === 0 ? 'api' : `api/${version}`,
            })),
          ],
        },
      ],
    },
  },
};

This workaround isn't perfect and may be buggy. Use at your own risk!

Sidebars

When we generate API routes, we also dynamically generate and associate a sidebar with each route. This cannot be overridden, but can be customized with some basic options (like categories and sorting).

If you'd like to reference the generated sidebar in your sidebars.ts, we write the sidebar to a file located at .docusaurus/api-sidebar-<id>-<version>.js. The <id> token defaults to "default" and <version> to "current".

import apiSidebar from './.docusaurus/api-sidebar-default-current';

export default {
  api: apiSidebar,
};

Caveats

  • Each version in versioned_docs (or versions.json) must contain the generated API JSON files, otherwise the build will fail.
  • The header/footer API links are not version aware, as their values are static.
  • We suggest only versioning major versions, as the size of these JSON files and the webpack build will get very large very fast.

Comparison

There's another plugin called docusaurus-plugin-typedoc, that offers a similar solution. However, there are many differences between that package and this one, with the biggest being that theirs generates markdown files and /docs/api/... styled routes, while ours renders custom React pages with /api/... styled routes. Some other differences are:

  • An index of all packages.
  • Readme inclusion and rendering.
  • Custom styles, sections, and headings.
  • Multiple function and method signatures.
  • Versioning!
  • And probably more....