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

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

    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

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

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"

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\""
  }
}

{
  "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",
      }),
    ],
  },
});

// 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] },
  },
});

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:

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.