{"id":19607874,"url":"https://github.com/mkdoc/mktask","last_synced_at":"2025-09-15T23:30:45.426Z","repository":{"id":57298979,"uuid":"54249782","full_name":"mkdoc/mktask","owner":"mkdoc","description":"Task runner","archived":false,"fork":false,"pushed_at":"2016-05-22T02:20:27.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-11T11:17:43.856Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkdoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-19T05:48:33.000Z","updated_at":"2016-03-19T23:41:01.000Z","dependencies_parsed_at":"2022-08-26T18:12:41.977Z","dependency_job_id":null,"html_url":"https://github.com/mkdoc/mktask","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmktask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmktask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmktask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmktask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkdoc","download_url":"https://codeload.github.com/mkdoc/mktask/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233165114,"owners_count":18634870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T10:12:45.092Z","updated_at":"2025-09-15T23:30:40.080Z","avatar_url":"https://github.com/mkdoc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Task Runner\n\n[![Build Status](https://travis-ci.org/mkdoc/mktask.svg?v=3)](https://travis-ci.org/mkdoc/mktask)\n[![npm version](http://img.shields.io/npm/v/mktask.svg?v=3)](https://npmjs.org/package/mktask)\n[![Coverage Status](https://coveralls.io/repos/mkdoc/mktask/badge.svg?branch=master\u0026service=github\u0026v=3)](https://coveralls.io/github/mkdoc/mktask?branch=master)\n\n\u003e Run build tasks\n\nRuns named task functions that return streams, arrays of deferred task functions or invoke the callback function.\n\n## Install\n\nInstall the [mkdoc][] tools for the `mk` program:\n\n```\nnpm i -g mkdoc\n```\n\n---\n\n- [Install](#install)\n- [Usage](#usage)\n- [Example](#example)\n- [Guide](#guide)\n  - [Creating Tasks](#creating-tasks)\n  - [Task Documentation](#task-documentation)\n  - [Task Names](#task-names)\n  - [Main Task](#main-task)\n  - [Deferred Tasks](#deferred-tasks)\n  - [Stream Tasks](#stream-tasks)\n  - [Task Dependencies](#task-dependencies)\n  - [Task Arguments](#task-arguments)\n- [Sample](#sample)\n- [Help](#help)\n- [API](#api)\n  - [mk](#mk)\n  - [#task](#task)\n  - [Task](#task-1)\n  - [.task](#task-2)\n  - [.get](#get)\n  - [.run](#run)\n  - [#src](#src)\n  - [#dest](#dest)\n  - [runner](#runner)\n  - [Runner](#runner-1)\n    - [Options](#options)\n  - [.get](#get-1)\n  - [.series](#series)\n  - [.parallel](#parallel)\n  - [.resolve](#resolve)\n  - [.exec](#exec)\n  - [.each](#each)\n- [License](#license)\n\n---\n\n## Usage\n\nCreate a `mkdoc.js` task file like this one ([source file](https://github.com/mkdoc/mktask/blob/master/mkdoc.js)):\n\n```javascript\nvar mk = require('mktask');\n\n// @task readme build the readme file.\nfunction readme(cb) {\n  mk.doc('doc/readme.md')         // read markdown source document\n    .pipe(mk.pi())                // parse processing instructions\n    .pipe(mk.ref())               // include link references\n    .pipe(mk.abs())               // make links absolute\n    .pipe(mk.msg())               // append generator message\n    .pipe(mk.toc({depth: 2}))     // inject table of contents list\n    .pipe(mk.out())               // convert abstract syntax tree to markdown\n    .pipe(mk.dest('README.md'))   // write the result to a file\n    .on('finish', cb);            // proceed to next task\n}\n\nmk.task(readme);\n```\n\nNote that you **should not install** the `mktask` dependency, it is resolved by the command line program.\n\n## Example\n\nBuild all tasks (or a main task when defined):\n\n```shell\nmk\n```\n\nBuild specific tasks:\n\n```shell\nmk api readme\n```\n\nUse a specific build file:\n\n```shell\nmk -f ~/mkdoc.js readme\n```\n\nTo see a list of tasks use:\n\n```shell\nmk --tasks\n```\n\n## Guide\n\nThis guides assumes you are using the `mk` program to run tasks, install it with `npm i -g mkdoc`.\n\n### Creating Tasks\n\nTasks are *named* functions that are passed to the `task` function:\n\n```javascript\nvar mk = require('mktask');\n\n// @task readme build the readme file.\nfunction readme(cb) {\n  // implement task logic\n  cb();\n}\n\nmk.task(readme);\n```\n\nAnonymous functions are not allowed and will generate an error if used.\n\n### Task Documentation\n\nIt is considered good practice to annotate your tasks with comments that provide a name and description of the task so that it will be included in the list printed when running `mk --tasks`.\n\n```javascript\n// @task readme build the readme file.\n```\n\n### Task Names\n\nBy default the task identifier (referenced on the command line) is taken from the function name but you may explicitly specify an identifier if you prefer:\n\n```javascript\nmk.task('docs', function readme(cb){cb()});\n```\n\nIf you have dependencies the identifier comes afterwards:\n\n```javascript\nmk.task([api, example], 'docs', function readme(cb){cb()});\n```\n\nWhen multiple tasks are passed then the identifier is taken from the last function which in this case becomes `readme`:\n\n```javascript\nmk.task(function api(cb){cb()}, function readme(cb){cb()});\n```\n\n### Main Task\n\nThe `mk` program when executed with no arguments will either run all available tasks in series or a `main` task if declared. To declare a main task give it the name `main`:\n\n```javascript\nvar mk = require('mktask');\n\n// @task main build all documentation.\nfunction main(cb) {\n  // implement task logic\n  cb();\n}\n\nmk.task(main);\n```\n\n### Deferred Tasks\n\nTypically task functions will invoke the callback function when done but they may also return an array of task functions which is useful when a task wishes to defer to a series of other tasks:\n\n```javascript\nvar mk = require('mktask');\n\n// @task api build the api docs.\nfunction api(cb) {\n  // implement api task logic\n  cb();\n}\n\n// @task readme build the readme file.\nfunction readme(cb) {\n  // implement readme task logic\n  cb();\n}\n\n// @task main build the api and readme docs.\nfunction main() {\n  return [api, readme];\n}\n\nmk.task(api);\nmk.task(readme);\nmk.task(main);\n```\n\nNote that when deferring to other task functions they must have been registered by calling `task()`.\n\n### Stream Tasks\n\nSometimes when creating complex stream pipelines it is useful to return streams so that parts of the pipeline become reusable between tasks, for example:\n\n```javascript\nvar mk = require('mktask')\n  , ast = require('mkast');\n\nfunction in() {\n  return mk\n    .src('This is a markdown paragraph.')\n    .pipe(ast.stringify());\n}\n\nfunction out() {\n  return mk.dest('target/stream-example.md');\n}\n\nmk.task(in, out);\n```\n\nWhen a task returns a stream it is piped to the next task function in the pipeline and the callback function is added as a listener for the `finish` event on the last stream in the pipeline.\n\n### Task Dependencies\n\nTask functions may declare an array of functions to call before the task function(s).\n\nDependencies are executed in parallel but they must all complete before the tasks are executed:\n\n```javascript\nvar mk = require('mktask');\n\n// @task api build the api docs.\nfunction api(\n  // implement api task logic\n  cb();\n}\n\n// @task example build the example file.\nfunction example(\n  // implement example task logic\n  cb();\n}\n\n// @task readme build the readme file.\nfunction readme(cb) {\n  // implement readme task logic\n  cb();\n}\n\nmk.task([api, example], readme);\n```\n\n### Task Arguments\n\nTask functions are automatically exposed the parsed arguments object via `this.args` such that `mk readme --env devel` would result in the readme task being able to access the `env` option using `this.args.options.env`.\n\nFlags are available in `this.args.flags` such that `mk readme -v` yields `true` for `this.args.flags.v`.\n\nNote that some command line arguments are handled by the `mk` program you should take care that the names do not conflict.\n\nFor detailed information on the `args` object see the [argparse library][argparse].\n\n## Sample\n\nInline code examples from the working example in [/doc/example](https://github.com/mkdoc/mktask/blob/master/doc/example).\n\nThe build file [mkdoc.js](https://github.com/mkdoc/mktask/blob/master/doc/example/mkdoc.js):\n\n```javascript\nvar mk = require('../../index');\n\n// @task example build the example file.\nfunction example(cb) {\n  mk.doc('source.md')             // read markdown source document\n    .pipe(mk.pi())                // parse processing instructions\n    .pipe(mk.ref())               // include link references\n    .pipe(mk.out())               // convert abstract syntax tree to markdown\n    .pipe(process.stdout)         // print the result\n    .on('finish', cb);            // proceed to next task\n}\n\nmk.task(example);\n```\n\nThe input source file [source.md](https://github.com/mkdoc/mktask/blob/master/doc/example/source.md):\n\n```markdown\n# Source\n\nExample for the mk(1) program supplied by [mkdoc][].\n\nA paragraph of markdown text followed by an include processing instruction.\n\n\u003c? @include include.md ?\u003e\n\nFollowed by some more markdown content and the result of executing a shell command:\n\n\u003c? @exec uname ?\u003e\n\nFinally include the link definition file.\n\n\u003c? @include links.md ?\u003e\n```\n\nInclude file [include.md](https://github.com/mkdoc/mktask/blob/master/doc/example/include.md):\n\n```markdown\n## Include\n\nA file that was included from another markdown document.\n```\n\nInclude file [links.md](https://github.com/mkdoc/mktask/blob/master/doc/example/links.md):\n\n```markdown\n[mkdoc]: https://github.com/mkdoc/mkdoc\n```\n\nResult:\n\n```markdown\n# Source\n\nExample for the mk(1) program supplied by [mkdoc][].\n\nA paragraph of markdown text followed by an include processing instruction.\n\n## Include\n\nA file that was included from another markdown document.\n\nFollowed by some more markdown content and the result of executing a shell command:\n\nLinux\n\nFinally include the link definition file.\n\n[mkdoc]: https://github.com/mkdoc/mkdoc\n\n```\n\n## Help\n\n```\nUsage: mk [-h] [--tasks] [--help] [--version] [--file=\u003cfile...\u003e] [task...]\n\n  Task runner.\n\nOptions\n  -f, --file=[FILE...]    Load specific task files\n  --tasks                 Print task list\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmktask@1.3.10\n```\n\n## API\n\n### mk\n\n```javascript\nmk()\n```\n\nCreates a task collection.\n\nReturns a Task.\n\n### #task\n\n```javascript\nstatic task()\n```\n\nAdds a task to the default task collection.\n\nReturns a Task.\n\n### Task\n\n```javascript\nTask()\n```\n\nEncapsulates a collection of named task functions.\n\n### .task\n\n```javascript\nTask.prototype.task()\n```\n\nAdds task function(s) to the list of known tasks.\n\n### .get\n\n```javascript\nTask.prototype.get()\n```\n\nGet a task map by function reference.\n\nReturns a task map if found.\n\n### .run\n\n```javascript\nTask.prototype.run()\n```\n\nGets a task runner for this collection of tasks.\n\nReturns a task Runner.\n\n### #src\n\n```javascript\nstatic src()\n```\n\nParses a markdown string into a stream.\n\nReturns the output stream.\n\n### #dest\n\n```javascript\nstatic dest([file])\n```\n\nGet a destination output stream.\n\nIf the file option is not given a destination stream that prints to\nstdout is returned.\n\nReturns an output stream.\n\n* `file` String path to the output file.\n\n### runner\n\n```javascript\nrunner(opts)\n```\n\nGet a task runner.\n\nReturns a Runner.\n\n* `opts` Object processing options.\n\n### Runner\n\n```javascript\nnew Runner(opts)\n```\n\nExecute task functions.\n\n* `opts` Object processing options.\n\n#### Options\n\n* `task` Object collection of tasks.\n\n### .get\n\n```javascript\nRunner.prototype.get(id)\n```\n\nGet a task by name identifier.\n\nReturns a task or undefined.\n\n* `id` Function|String task identifier.\n\n### .series\n\n```javascript\nRunner.prototype.series(list, cb)\n```\n\nExecute task functions in series.\n\n* `list` Array of task functions.\n* `cb` Function callback function.\n\n### .parallel\n\n```javascript\nRunner.prototype.parallel(list[, concurrent], cb)\n```\n\nExecute task functions in parallel.\n\n* `list` Array of task functions.\n* `concurrent` Number number of concurrent calls.\n* `cb` Function callback function.\n\n### .resolve\n\n```javascript\nRunner.prototype.resolve(cb)\n```\n\nResolves dependencies for a task.\n\nSearches for dependencies that are tasks and injects any dependencies for\nlocated tasks.\n\nReturns an array of task dependencies.\n\n* `cb` Function callback function.\n\n### .exec\n\n```javascript\nRunner.prototype.exec(id, cb)\n```\n\nExecute a task by name identifier.\n\nDependencies are run in parallel before task execution.\n\nReturns a task or undefined.\n\n* `id` Function|String task identifier.\n* `cb` Function callback function.\n\n### .each\n\n```javascript\nRunner.prototype.each([names], cb)\n```\n\nExecute a list of tasks.\n\nWhen `names` is not given and no main task exists all tasks are executed;\nif a main task exists it is executed.\n\n* `names` Array list of task identifiers or task functions.\n* `cb` Function callback function.\n\n## License\n\nMIT\n\n---\n\nCreated by [mkdoc](https://github.com/mkdoc/mkdoc) on May 22, 2016\n\n[mkdoc]: https://github.com/mkdoc/mkdoc\n[mkparse]: https://github.com/mkdoc/mkparse\n[argparse]: https://github.com/cli-kit/cli-argparse\n[commonmark]: http://commonmark.org\n[npm]: https://www.npmjs.com\n[github]: https://github.com\n[jshint]: http://jshint.com\n[jscs]: http://jscs.info\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmktask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkdoc%2Fmktask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmktask/lists"}