gulp-todo
v7.1.1
Published
Generate a TODO.md file from comments of files in stream
Downloads
7,869
Maintainers
Readme
gulp-todo
Parse and output TODOs and FIXMEs from comments in your file in a stream
Parse your files in a gulp-stream, extracting todos/fixmes from comments and reporting them in a reporter to your choosing using leasot.
Issues with the output should be reported on the leasot issue tracker
Supports latest leasot
version 7.0.0
.
Please upgrade carefully to version 7.0.0
, there were breaking changes in the gulp-todo
API
Install
Install with npm
$ npm install --save-dev gulp-todo
Usage
const gulp = require('gulp');
const todo = require('gulp-todo');
// generate a todo.md from your javascript files
gulp.task('todo', function() {
gulp.src('js/**/*.js')
.pipe(todo())
.pipe(gulp.dest('./'));
// -> Will output a TODO.md with your todos
});
// generate todo from your jade files
gulp.task('todo-jade', function() {
gulp.src('partials/**/*.jade')
.pipe(todo({ fileName: 'jade-todo.md' }))
.pipe(gulp.dest('./'));
// -> Will output a jade-todo.md with your todos
});
// get filenames relative to project root (where your gulpfile is)
gulp.task('todo-absolute', function() {
gulp.src('js/**/*.js')
.pipe(todo({
absolute: true
}))
.pipe(gulp.dest('./'));
});
// get relative path filenames
gulp.task('todo-absolute', function() {
gulp.src('js/**/*.js', { base: '/' })
.pipe(todo())
.pipe(gulp.dest('./'));
});
// create a json output of the comments (useful for CI such as jenkins)
gulp.task('todo-json', function () {
gulp.src('./**/*.js', {
base: './'
})
.pipe(todo({
fileName: 'todo.json',
reporter: 'json'
}))
.pipe(gulp.dest('./'));
});
// output once in markdown and then output a json file as well
gulp.task('todo-reporters', function() {
gulp.src('js/**/*.js')
.pipe(todo())
.pipe(gulp.dest('./')) //output todo.md as markdown
.pipe(todo.reporter('json', {fileName: 'todo.json'}))
.pipe(gulp.dest('./')) //output todo.json as json
});
// Delete the todo.md file if no todos were found
const gulpIf = require('gulp-if');
const del = require('del');
const vinylPaths = require('vinyl-paths');
gulp.task('todo-delete', function() {
gulp.src('js/**/*.js')
.pipe(todo())
.pipe(gulpIf(function (file) {
return file.todos && Boolean(file.todos.length);
}, gulp.dest('./'), vinylPaths(del)));
});
Injecting the todo generated file into another template
If you want to inject the generated todo stream into another file (say a readme.md.template
)
you can do the following:
- Create
readme.md.template
file that contains the following marker, marking where you want to inject the generated todo file:
### some previous content
<%= marker %>
- Use the following code to inject into that markdown, creating a markdown file with the generated todo:
const fs = require('fs');
const path = require('path');
const gulp = require('gulp');
const todo = require('gulp-todo');
const template = require('lodash.template');
const through = require('through2');
gulp.task('default', function () {
gulp.src('./js/**/*.js')
.pipe(todo())
.pipe(through.obj(function (file, enc, cb) {
//read and interpolate template
const tmpl = fs.readFileSync('./readme.md.template', 'utf8');
const compiledTpl = template(tmpl);
const newContents = compiledTpl({
'marker': file.contents.toString()
});
//change file name
file.path = path.join(file.base, 'readme-new.md');
//replace old contents
file.contents = Buffer.from(newContents);
//push new file
this.push(file);
cb();
}))
.pipe(gulp.dest('./'));
});
Supported Filetypes
See https://github.com/pgilad/leasot#supported-languages
API
todo(options)
options
is an optional configuration object, see https://github.com/pgilad/gulp-todo/blob/master/index.js#L22-L32
todo.reporter(reporter, options)
options
is an optional configuration object, see https://github.com/pgilad/gulp-todo/blob/master/lib/reporter.js#L10-L16
Use another reporter in stream, will replace the contents of the output file.
Must be used after todo()
, since it uses the file.todos
that are passed along.
See the example in the usage
License
MIT © Gilad Peleg