https://github.com/blakmatrix/vitepress-jsdoc
A bridge between Vitepress and JSDoc-style commented codebases for hassle-free documentation.
https://github.com/blakmatrix/vitepress-jsdoc
annotations codebase developer-tools documentation integration jsdoc plugin static vite vitepress vue
Last synced: 2 months ago
JSON representation
A bridge between Vitepress and JSDoc-style commented codebases for hassle-free documentation.
- Host: GitHub
- URL: https://github.com/blakmatrix/vitepress-jsdoc
- Owner: blakmatrix
- Created: 2023-10-03T06:00:35.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-23T20:43:34.000Z (over 1 year ago)
- Last Synced: 2025-09-11T01:55:13.148Z (4 months ago)
- Topics: annotations, codebase, developer-tools, documentation, integration, jsdoc, plugin, static, vite, vitepress, vue
- Language: TypeScript
- Homepage: https://blakmatrix.github.io/vitepress-jsdoc/
- Size: 553 KB
- Stars: 23
- Watchers: 1
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
[](https://blakmatrix.github.io/vitepress-jsdoc/)
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![licenses][licenses]][licenses-url]
[![PR's welcome][prs]][prs-url]
[![XO code style][xo]][xo-url]
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/](https://blakmatrix.github.io/vitepress-jsdoc/)**
## Install
```shell
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:
```shell
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:
```shell
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:
```shell
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`:
```shell
npx concurrently "vitepress dev docs" "vitepress-jsdoc --source path/to/src ... -watch"
```
Here's a partial package.json script to illustrate:
```json
{
"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:
```typescript
// 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](https://blakmatrix.github.io/vitepress-jsdoc/) or browse the files directly on [GitHub](https://github.com/blakmatrix/vitepress-jsdoc).
## 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:
```ts
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: "",
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](https://github.com/blakmatrix/vitepress-jsdoc?sponsor=1)
## License
MIT.
[npm]: https://img.shields.io/npm/v/vitepress-jsdoc.svg
[npm-url]: https://npmjs.com/package/vitepress-jsdoc
[node]: https://img.shields.io/node/v/vitepress-jsdoc.svg
[node-url]: https://nodejs.org
[prs]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
[prs-url]: https://github.com/blakmatrix/vitepress-jsdoc/blob/master/CONTRIBUTING.md
[licenses-url]: https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fblakmatrix%2Fvitepress-jsdoc?ref=badge_shield
[licenses]: https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fblakmatrix%2Fvitepress-jsdoc.svg?type=shield
[xo]: https://shields.io/badge/code_style-5ed9c7?logo=xo&labelColor=gray
[xo-url]: https://github.com/xojs/xo