Okidoc logo


Tool to document your code easy and flexible


Install using the npm package manager:

$ npm install okidoc-md --save-dev
$ # AND/OR
$ npm install okidoc-site --save-dev

This installs package and put two commands in your ./node_modules/.bin path:

  • okidoc-md - generate human-readable documentation md files using source code with JSDoc and public method markers
  • okidoc-site - run and build documentation site based on md files and site config

NOTE: if you don't need to generate markdown files or don't need a site, install only package you need

You can use these commands in your npm scripts:

"scripts": {
  "documentation": "okidoc-md ./docs.yml ./docs",
  "documentation:gitadd": "npm run documentation && git add ./docs",
  "documentation:site": "okidoc-site develop ./site.yml",
  "documentation:site:build": "npm run documentation && okidoc-site build ./site.yml",
  "precommit": "npm run documentation:gitadd"

Generate documentation

Define what to document

Add @doc TAG_NAME tag to JSDoc of class or function

 * My Super UI
 * @doc UI
class MySuperUI {
   * show UI
   * @example
   * mySuperUI.show();
  show() {}

 * Subscribe on event
 * @param eventName - name of event
 * @param fn - event listener fn
 * @doc Events
function subscribe(eventName: string, fn: Function) {}


Add yaml config (default config path is ./docs.yml):

# Get files using `entry` or/and `glob` (could be `.js` or `.ts` files),
# find api methods by `@doc UI` tag in JSDoc and generate markdown to `partial/ui.md` file.
- path: partial/ui.md
  title: UI API Methods
  # [optional] if provided, only `entry` file dependencies will be parsed
  entry: src/index.ts
  # [optional] required if `entry` not provided
  glob: src/**/*.ts
  # tag name have to match `@doc UI` in JSDoc
  tag: UI

- path: partial/events.md
  title: Events API
  glob: src/**/*.ts
  tag: Events

NOTE: With entry option, all dependency file source will be parsed for doc. Not only imported/exported part.


Run okidoc-md script

$ okidoc-md ./docs.yml ./docs

It will generates docs markdown using configuration from ./docs.yml and put them to ./docs directory

NOTE: ./docs.yml and ./docs are default values for configPath and outputDir arguments and can be omitted. Run okidoc-md --help for help.

To extract api methods with custom rule use visitor prop in docs.yml

Define markdown files

You can combine auto generated markdown files with manually created. Markdown should be written in gfm format.

Each markdown file can be annotated with YAML front matter. Here is a basic example:

title: 'okidoc'
layout: simple
  - ./partial/api.md
# My super API

After this line content from `api.md` will be included.

Supported properties:

titleThe title for the page in <title> tag.
layoutOptionally define or override the layout to use. Available layouts: two-column - default layout, code examples are shown on right side.. simple - one column layout.
includeList of markdown files that will be included after content in the current markdown file.

Build documentation site

Site logic is based on gatsby.

Instead of default gatsby directory src/pages, use your docs path (example):

├── site.yml
├── /docs/                      # Site markdown files
│   ├── /index.md               # [required] site index page
│   ├── /other-markdown-file.md
│   └── ...                     # Other markdown files
└── ...

IMPORTANT: For site index page use index.md file (example). It is required file in your documentation directory. Other pages are available by file name without .md extension.

Only md files are served by okidoc-site.


To configure your site, use yaml config (default config path is ./site.yml):

# Markdown files path
# put index.md with content for site index page
docsPath: ./docs

# [optional] path for site build. Default path is `./site`
distPath: ./sitedist

  # [optional] site metadata (https://www.gatsbyjs.org/docs/gatsby-config/#sitemetadata)
  # [optional] path prefix
  pathPrefix: /my-awesome-lib
  # [optional] algolia apiKey and indexName for docsearch (https://www.algolia.com/ref/docsearch). If empty, search will be hidden
  # [optional] Link to your github repository

# [optional] react components inside markdown
  path: ./docs/playground-components.js

# [optional] navigation config. Use if you need more than one page in navigation block
  - path: /config
    title: Configuration
  - path: /methods
    title: Methods

Add navigation

navigation config

Add react components

react components inside markdown


Run okidoc-site script

$ okidoc-site develop ./site.yml

Site will start a hot-reloading development environment accessible at localhost:8000

$ okidoc-site build ./site.yml

Will perform an optimized production build for your site generating static HTML and per-route JavaScript code bundles.

Read gatsby docs for more information


If you use github for your repository, the easiest way to deploy site is to use gh-pages library:

"scripts": {
  "documentation:site:build": "npm run documentation && okidoc-site build ./site.yml",
  "documentation:site:deploy": "npm run documentation:site:build && gh-pages -d site",

For more deploy options read gatsby docs