vuepress-jsdoc
Generate jsdoc markdown files for vuepress
Last updated 2 months ago by phlp .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install vuepress-jsdoc 
SYNC missed versions from official npm registry.

vuepress-jsdoc

Codacy Badge npm now

This npm package is a command line script, which scans your JavaScript, Vue or Typescript source code and generates markdown files for vuepress with the help of jsdoc-to-markdown and vue-docgen-api.

CLI ./example

How to

yarn global add vuepress-jsdoc
npm i vuepress-jsdoc -g

Example:

# search code in src and move it to code (./documentation/code) in your vuepress folder (./documentation)
vuepress-jsdoc --source ./src --dist ./documentation --folder code --title API --exclude *.test.js,exclude.js

Commands

If no command passed it will run generate as default

Name Alias Description
generate gen, g search code in src and move it to code (./documentation/code) in your vuepress folder (./documentation)

Options

Name Alias Default Description
--source -s ./src Source folder with .js or .ts files
--dist -d ./documentation Destination folder
--folder -f ./code Folder inside destination folder. Gets overwritten everytime
--title -t API Title of your documentation
--help -h Show help
--version -v Show current version
--readme -r Path to custom readme file
--exclude -e Pattern to exclude files/folders (Comma seperated) - *.test.js,exclude.js
--rmPattern -rm Pattern when removing files. You can ex- and include files. (glob pattern)
--partials -p jsdoc2markdown partial templates (overwrites default ones)
--jsDocConfigPath -c Path to JsDoc Config (experimental)

config.js

Inside your generated folder, you can find a config.js. This file includes a complete filetree and an vuepress sidebar tree.

How to configure vuepress

Vuepress is a static site generator by Evan You. You can add all generated documentation files to your existing vuepress project or create a new one.

# First install vuepress
yarn  global add vuepress

# Run the CLI
vuepress-jsdoc

# Run vuepress dev server
vuepress dev ./documentation

# Run vuepress build, if you want to ship it
vuepress build ./documentation

Access it via: http://localhost:8080/code/

Now you need the sidebar. Create a .vuepress folder inside the documentation folder and add the following config.js.

config.js:

// auto generated sidebar
const { sidebarTree } = require("../code/config");

module.exports = {
  dest: "dist",
  locales: {
    "/": {
      title: "vuepress-jsdoc",
      description: "Generate jsdoc markdown files for vuepress"
    }
  },
  themeConfig: {
    editLinks: true,
    sidebarDepth: 4,
    docsDir: "code",
    locales: {
      "/": {
        nav: [
          {
            text: "Home",
            link: "/"
          }
        ],
        // Add the generated sidebar
        sidebar: Object.assign({}, sidebarTree("Mainpage title"))
      }
    }
  }
};

Custom readme

You can easily add a custom path to your readme by using the --readme ./path/to/file.md parameter. If you move a README.md inside your source folder, it should resolve it automatically. You can set the title by passing it to the sidebarTree('Mainpage title') function inside your ./.vuepress/config.js.

Once the README.md has been added, it is no longer overwritten! If you want it to be overwritten, set --rmPattern=./documentation/code/README.md.

@vuepress comment block

You can add custom meta data your pages by using the @vuepress block:

/*
 * @vuepress
 * ---
 * title: Your custom title
 * headline: You custom headline
 * ---
 */

Use headline to add a custom h1 title.

More information

Typescript

To use typescript, you have to install these dev-dependencies:

yarn add -D typescript jsdoc-babel @babel/cli @babel/core @babel/preset-env @babel/preset-typescript jsdoc-to-markdown

Next, you have to add a jsdoc.json to your project with some settings and add it with the -c parameter. You can find a full working example with all settings inside the ./example folder. The example shows also how to use babel-plugins.

Example

The ./example folder includes a full working vuepress-jsdoc example.

# Install dependencies
yarn

# Run the CLI
vuepress-jsdoc

# Generate docs
yarn docs

# Run dev server
yarn dev

# Generate dist folder
yarn build

Contribute

PRs are always welcome (:

Current Tags

  • 3.0.0                                ...           latest (2 months ago)

37 Versions

  • 3.0.0                                ...           2 months ago
  • 2.1.1                                ...           3 months ago
  • 2.1.0                                ...           3 months ago
  • 2.0.2                                ...           5 months ago
  • 2.0.1                                ...           6 months ago
  • 2.0.0                                ...           6 months ago
  • 1.8.1                                ...           9 months ago
  • 1.8.0                                ...           10 months ago
  • 1.7.4                                ...           10 months ago
  • 1.7.3                                ...           a year ago
  • 1.7.2                                ...           a year ago
  • 1.7.1                                ...           a year ago
  • 1.7.0                                ...           a year ago
  • 1.6.0                                ...           a year ago
  • 1.5.0                                ...           a year ago
  • 1.4.1                                ...           a year ago
  • 1.4.0                                ...           a year ago
  • 1.3.1                                ...           a year ago
  • 1.3.0                                ...           a year ago
  • 1.2.2                                ...           a year ago
  • 1.2.1                                ...           a year ago
  • 1.2.0                                ...           a year ago
  • 1.1.1                                ...           a year ago
  • 1.1.0                                ...           a year ago
  • 1.0.3                                ...           a year ago
  • 1.0.2                                ...           a year ago
  • 1.0.1                                ...           a year ago
  • 1.0.0                                ...           a year ago
  • 0.3.0                                ...           2 years ago
  • 0.2.1                                ...           2 years ago
  • 0.2.0                                ...           2 years ago
  • 0.1.3                                ...           2 years ago
  • 0.1.2                                ...           2 years ago
  • 0.1.1                                ...           2 years ago
  • 0.1.0                                ...           2 years ago
  • 0.0.2                                ...           2 years ago
  • 0.0.1                                ...           2 years ago
Maintainers (1)
Downloads
Today 1
This Week 75
This Month 75
Last Day 73
Last Week 1
Last Month 5
Dependencies (11)
Dev Dependencies (6)

Copyright 2014 - 2016 © taobao.org |