Okidoc logo


A flexible tool to document your code easily


Install using the npm package manager:

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

This installs the package and puts 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 the site config

NOTE: if you don't need to generate markdown files or don't need a site, you can only install the 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 JSDoc tags to your classes or functions

 * 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 a 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 searching for `@doc UI` JSDoc tags and generate markdown into a `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` is not provided
  glob: src/**/*.ts
  # tag name has to match `@doc UI` in JSDoc
  tag: UI

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

NOTE: With the entry option specified, all source code of the dependency file will be parsed, not just the imported/exported part.


Run the okidoc-md script.

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

This will generate the docs markdown using configuration from ./docs.yml and put them into ./docs directory.

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

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

Define markdown files

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

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

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

After this line the contents of `api.md` will be included.

Supported properties:

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

Build the documentation site

Site logic is based on gatsby.

Instead of the default gatsby directory src/pages, make sure to 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: Use index.md file for the site index page (example). It's a required file in your documentation directory. Other pages are available by file name without the .md extension.

Only md files are served by okidoc-site.


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

# Path for markdown files
# add index.md with content for the site index page
docsPath: ./docs

# [optional] path for the site build. Default 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 this if you need more than one page in the navigation block
  - path: /config
    title: Configuration
  - path: /methods
    title: Methods

Add navigation

navigation config

Add react components

react components inside markdown


Run the okidoc-site script

$ okidoc-site develop ./site.yml

This will launch a hot-reloading development environment accessible at localhost:8000

$ okidoc-site build ./site.yml

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

Read on gatsby docs for more information


If you use GitHub to host your repository, the easiest way to deploy your site is to use the 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 the gatsby docs