docstrap

A clean, responsive documentation template theme for JSDoc inspired by lodash and minami.

Features

• Clean and responsive design based on Bootstrap
• Comprehensive navigation with collapsible menus
• Syntax highlighting for code examples
• Support for JSDoc tutorials
• Customizable source code linking
• Modular documentation organization
• Mobile-friendly layout
• Search functionality
• Custom CSS and JS support
• Website registration information display (ICP and police registration)
• Automatic code example generation - Code examples are now generated and displayed by default in documentation
• Custom logo support - Easily replace the default logo with your own
• Namespace configuration - Configure namespace prefix for classes and static members
• Dark theme support - Supports both light and dark themes with toggle switch
• Quick configuration generation - Generate default configuration file with a single command

Quick Start

Installation

Install via npm:

$ npm install docstrap

Generate Configuration File

Use the npx docstrap init command to quickly generate a default configuration file:

$ npx docstrap init

This will create a complete jsdoc.json configuration file in the current directory with all available options and their default values.

Generate Documentation

Generate documentation using JSDoc with the docstrap template:

$ npx jsdoc -c jsdoc.json

Or add a script to your package.json:

{
  "scripts": {
    "docs": "jsdoc -c jsdoc.json"
  }
}

Then run:

$ npm run docs

Configuration Options

All template options are specified in the templates section of your JSDoc configuration file.

Basic Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | cleverLinks | Boolean | false | Automatically link types and members | | monospaceLinks | Boolean | false | Use monospace font for links | | default.outputSourceFiles | Boolean | true | Include source files in output |

Logo Configuration

You can customize the logo displayed in the documentation:

{
  "templates": {
    "logo": "path/to/your/logo.png",
    "logoAlt": "Your Company Name"
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | logo | String | icons/logo.png | Path to your logo image (relative to the template directory) | | logoAlt | String | Logo | Alternative text for the logo image |

Namespace Configuration

You can configure a namespace prefix for classes and static members in the documentation:

{
  "templates": {
    "namespace": "MyNamespace"
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | namespace | String | "" | Namespace prefix for classes and static members |

Website Registration Information

You can configure website registration information that will be displayed in the footer:

{
  "templates": {
    "beian": {
      "icp": "京ICP备12345678号",
      "police": "京公网安备12345678901234号",
      "redirect": "https://beian.miit.gov.cn/"
    }
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | beian.icp | String | 京ICP备XXXXXXXX号 | ICP registration number | | beian.police | String | null | Public security registration number | | beian.redirect | String | null | Redirect URL for ICP registration link |

Source Code Links

{
  "templates": {
    "sourceUrl": "https://github.com/user/repo/blob/main/{filename}#L{line}"
  }
}

Available placeholders:

• {filename}: Path to the source file
• {line}: Line number in the source file
• {version}: Version from environment variable

Navigation Options

{
  "templates": {
    "navType": "vertical",
    "theme": "cosmo",
    "linenums": true,
    "collapseSymbols": true,
    "inverseNav": true
  }
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | navType | String | vertical | Navigation layout (vertical or inline) | | theme | String | cosmo | Bootstrap theme to use | | linenums | Boolean | true | Show line numbers in code examples | | collapseSymbols | Boolean | true | Collapse symbol navigation by default | | inverseNav | Boolean | true | Use inverse navigation bar style |

Template Structure

docstrap/
├── publish.js              # Main publishing script
├── package.json           # Package metadata
├── bin/
│   └── docstrap.js        # Command line tool
├── static/                # Static assets
│   ├── css/               # Stylesheets
│   │   └── jsdoc-default.css
│   └── javascript/        # JavaScript files
│       ├── doc.js
│       ├── html5.js
│       └── prism.js
└── tmpl/                  # Template files
    ├── layout.tmpl        # Main layout template
    ├── index.tmpl         # Index page template
    ├── class.tmpl         # Class documentation template
    └── ...

Generated Output

The template generates the following files and directories:

docs/
├── index.html             # Main page
├── global.html            # Global objects
├── modules/               # Module documentation
├── classes/               # Class documentation
├── namespaces/            # Namespace documentation
├── tutorials/             # Tutorial files
├── styles/                # CSS files
├── scripts/               # JavaScript files
├── fonts/                 # Web fonts
└── types.txt              # Type index (JSON)

Code Examples

docstrap automatically generates and displays code examples in the documentation by default. To take advantage of this feature, simply write JSDoc comments with @example tags in your source code:

/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @example
 * // Basic usage
 * const result = sum(2, 3);
 * console.log(result); // 5
 * 
 * @example
 * // With negative numbers
 * const result = sum(-1, 4);
 * console.log(result); // 3
 */
function sum(a, b) {
  return a + b;
}

The examples will automatically appear in the generated documentation under the "Examples" section for each documented function or class.

Customization

CSS Customization

To customize the appearance, you can override the default styles:

1. Create a custom.css file
2. Add it to your JSDoc config:

{
  "templates": {
    "customCss": "path/to/custom.css"
  }
}

Template Customization

To modify the template structure:

1. Copy the tmpl/ directory from docstrap to your project
2. Modify the template files as needed
3. Update your JSDoc config to point to your custom template:

{
  "opts": {
    "template": "./custom-docstrap-template"
  }
}

Troubleshooting

Common Issues

1. Template not found: Ensure the template path in jsdoc.json is correct
2. No documentation generated: Check that your source files match the includePattern
3. Missing navigation: Verify that your JSDoc comments are properly formatted

Debugging

Enable verbose output:

$ jsdoc -c jsdoc.json --verbose

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Apache-2.0 License. See LICENSE for more information.

Acknowledgements

• JSDoc - API documentation generator
• Bootstrap - Front-end framework
• lodash - JavaScript utility library
• minami - Original inspiration