vitepress-jsdoc

Code More, Document Faster: The Ultimate Vitepress Integration.

vitepress-jsdoc is the definitive bridge between Vitepress and JSDoc-style commented codebases. Crafted for developers seeking a hassle-free documentation experience, it excels in swiftly generating comprehensive docs from your annotations. Beyond just documentation, it's your key to unlocking the full potential of Vitepress, seamlessly integrating your code insights into beautifully rendered pages.

Read the full documentation at blakmatrix.github.io/vitepress-jsdoc/

Install

npm install -D vitepress-jsdoc

Primary Usage: Command Line Tool

The main usage of vitepress-jsdoc is as a command line tool. Here's a generic command line example:

    npx vitepress-jsdoc --source path/to/src --dist ./docs --folder code --title API

Note: You will probably want to grab the handlbar partial and helpers from this project

Prebuild and Build Steps

To ensure your documentation is up-to-date, consider adding a prebuild step using the following command:

vitepress-jsdoc --source path/to/src --dist ./docs --folder code  --readme path/to/README.md --exclude="**/*.json,**/*.hbs,**/*.d.ts,**/*.map,**/interfaces.*" --partials=path/to/handlebars/partials/*.hbs --helpers=path/to/handlebars/helpers/*.hbs

After the prebuild, you can build your documentation with:

vitepress build docs

For development purposes, you can utilize npx concurrently to run both the Vitepress development server and the watch mode of vitepress-jsdoc:

npx concurrently "vitepress dev docs" "vitepress-jsdoc --source path/to/src ... -watch"

Here's a partial package.json script to illustrate:

{
  "scripts": {
    "prebuild": "vitepress-jsdoc --source path/to/dist/esm --dist ./docs --folder code  --readme path/to/README.md --exclude=\"**/*.json,**/*.hbs,**/*.d.ts,**/*.map,**/interfaces.*\" --partials=path/to/handlebars/partials/*.hbs --helpers=path/to/handlebars/helpers/*.hbs",
    "build": "vitepress build docs",
    // OR (using vitepress' default commands 
    // - you might take `prebuild` above and rewrite it to `docs:preview`)
    "docs:build": "npm run prebuild && vitepress build docs",
    "docs:dev": "npx concurrently \"vitepress dev docs\" \"vitepress-jsdoc --source path/to/src ... -watch\""
  }
}

This package.json script provides both the prebuild and build steps combined in the docs:build command using the && approach. The docs:dev command runs both the Vitepress development server and the watch mode of vitepress-jsdoc concurrently.

Plugin Mode (Beta)

While vitepress-jsdoc can be integrated as a plugin into Vitepress, please note that this mode is currently in beta. During development, the module will function as expected. However, due to certain technical challenges in integrating with the default Vitepress transforms for markdown files, there might be limitations in this mode.

For integration into Vitepress, the module mode is recommended:

// Example Vitepress Configuration
import { defineConfig } from "vitepress";
import VitpressJsdocPlugin from "vitepress-jsdoc";

export default defineConfig({
  vite: {
    plugins: [
      VitpressJsdocPlugin({
        folder: "code",
        source: "./src",
        dist: "./docs",
        title: "API",
        partials: ["./partials/*.hbs"],
        helpers: ["./helpers/*.js"],
        readme: "./README.md",
        exclude: "**/*.json,**/*.d.ts,**/*.map",
      }),
    ],
  },
});

Live Example

This entire project serves as a live example. You can view it here or browse the files directly on GitHub.

Vitepress Configuration

For a quick start with Vitepress:

1. Initialize Vitepress in your project with npx vitepress init.
2. Update your config.mts file as shown below.
3. Run the development server with npm run docs:dev.
4. Build for production with npm run docs:build (Note: the watch plugin will not run in this mode).

Sidebar Configuration

While vitepress-jsdoc is agnostic to sidebars, it's recommended to use vitepress-sidebar for a more enhanced experience. Configure your vitepress config.mts file as follows:

import { defineConfig } from "vitepress";
import { generateSidebar } from "vitepress-sidebar";

const getSideBar = (): any => {
  const generatedSidebar = generateSidebar([
    {
      documentRootPath: "docs",
      useTitleFromFileHeading: true,
      hyphenToSpace: true,
      keepMarkdownSyntaxFromTitle: true,
    },
  ]);
  return generatedSidebar ?? [];
};

export default defineConfig({
  title: "<your package title>",
  description: "<your package description>",
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "API", link: "/code/README" },
    ],
    sidebar: getSideBar(),
    outline: { level: [2, 6] },
  },
});

Plugin/Command Options

These are plugin/command options:

Option	Description
folder	Folder name
source	Source directory
dist	Destination directory
title	Title of your documentation
partials	Path to partial templates for JSDoc config
helpers	Path to helper scripts for JSDoc config
readme	Path to custom README
exclude	Pattern to exclude files/folders

Contributions

We welcome and appreciate contributions from the community. If you have improvements, bug fixes, or other suggestions, please submit a pull request.

If you find value in this project and wish to show your support in other ways, consider sponsoring us. Your sponsorship will help ensure the continued development and improvement of this project.

Sponsor this project

License

MIT.