# docstrap

**Repository Path**: docstrap/docstrap

## Basic Information

- **Project Name**: docstrap
- **Description**: docstrap
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# docstrap

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

[![npm version](https://badge.fury.io/js/docstrap.svg)](https://badge.fury.io/js/docstrap)
[![License](https://img.shields.io/npm/l/docstrap.svg)](LICENSE)

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

```bash
$ npm install docstrap
```

### Generate Configuration File

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.

### Generate Documentation

Generate documentation using JSDoc with the docstrap template:

```bash
$ npx jsdoc -c jsdoc.json
```

Or add a script to your [package.json](file:///Users/xianhao/jvy/docstrap-master/docstrap/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](file:///Users/xianhao/jvy/docstrap-master/docstrap/bin/docstrap.js#L19-L74) 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:

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

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `logo` | String | [icons/logo.png](file:///Users/xianhao/jvy/docstrap-master/docstrap/static/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:

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

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

### Source Code Links

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

### Navigation Options

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

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

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

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

```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](LICENSE) for more information.

## Acknowledgements

- [JSDoc](https://github.com/jsdoc/jsdoc) - API documentation generator
- [Bootstrap](https://getbootstrap.com/) - Front-end framework
- [lodash](https://lodash.com/) - JavaScript utility library
- [minami](https://github.com/nijikokun/minami) - Original inspiration