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

$3

Install via npm:

``bash
$ npm install docstrap
`

$3

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

`bash
$ npx docstrap init
`

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

$3

Generate documentation using JSDoc with the docstrap template:

`bash
$ npx jsdoc -c jsdoc.json
`

Or add a script to your package.json:

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

Then run:

`bash
$ npm run docs
`

Configuration Options

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

$3

| 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 |

$3

You can customize the logo displayed in the documentation:

`json
{
"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 |

$3

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

`json
{
"templates": {
"namespace": "MyNamespace"
}
}
`

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

$3

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

`json
{
"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 |

$3

`json
{
"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

$3

`json
{
"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:

`javascript
/**
* 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

$3

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

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

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

$3

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:

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

Troubleshooting

$3

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

$3

Enable verbose output:

`bash
$ 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