gulp-comments-to-md

Table of content

• About
• Installation
• How to use?
• Supported comment formats
• License

About

This gulp plugin parses comments from logic or styles files and generates a markup document file (e.g. README.md)

For example you have file file-a.scss with contents:

/**
 * ### Color 1
 * - `Is:` Red!
 */

.color-red {
  color: red;
}

And file-b.scss with contents:

/**
 * ### Color 2
 * - `Is:` Blue!
 */

.color-blue {
  color: blue;
}

This plugin will extract comments from file-a.scss & file-b.scss and generate a new DOCUMENTATION.md (name of the file is on you!) file which in this case would contain:

### Color 1
- `Is:` Red!

### Color 2
- `Is:` Blue!

Installation

• If you are using yarn run yarn add gulp-comments-to-md --save
• If you prefer npm run npm install gulp-comments-to-md --save

How to use

1. Once installed modify your gulpfile.js file to include the gulp-comments-to-md plugin like this:

   const commentsToDocFile = require('gulp-comments-to-md')

2. Define the task like this:

   gulp.task('generate-documentation', () => {
     return gulp.src([
       'src/**/*.scss'
     ])
     .pipe(commentsToDocFile('README.md'))
     .pipe(gulp.dest('./'))
   })

• ['src/**/*.scss'] - change to your selected target files (you can target all file types supporting required comment formatting) 📌
• README.md - name of the generated document (not limited to .md!) 📌
• ./ - destination folder 📌

Supported comment formats

At the moment it works perfectly with /** ... */ comment format. Perfectly formatted comment example:

/**
 * ## Animations
 * - [Float](#float)
 * - [Pulse](#pulse)
 * - [Spin](#spin)
 */

$('.btn-toggler').on('click', () => {
  $('.header').toggle()
});

❗ Pay attention to the details: each inner comment line (including last one) must start with space ( ) and asterisk (*).

License

The repository code is open-sourced software licensed under the MIT license.