Markdown driven task runner.
npm install maid    
> Markdown driven task runner.
- Install
- What is a maidfile?
- Run tasks before/after a task
- Task hooks
- Advanced
- Code block languages
- bash/sh
- Read command line arguments
- js/javascript
- Asynchronous task
- py/python
- Use a custom maidfile
- Development
- lint
- test
- toc
- Contributing
- Author
You can install Maid globally:
``bash`For npm users
npm i -g maidFor Yarn users
yarn global add maid
Or if you want to ensure that your teammates are using the same version as you, it's recommended to install Maid locally:
`bash`For npm users
npm i -D maidFor Yarn users
yarn add maid --dev
PRO TIP: you can use npx or yarn command to run any locally installed executable that is inside node_modules/.bin/, e.g. use yarn maid to run the locally installed maid command.
A maidfile is where you define tasks, in Markdown!
📝 maidfile.md:
``markdownlint
It uses ESLint to ensure code quality.
`bash`
eslint --fix
Build our main app
Run task build:demo after this
`bashnpm scriptsnote that you can directly call binaries inside node_modules/.bin
just like how
works`
babel src -d lib
You can use JavaScript to write to task script too!
`js
const webpack = require('webpack')
// Async task should return a Promise
module.exports = () =>
new Promise((resolve, reject) => {
const compiler = webpack(require('./webpack.config'))
compiler.run((err, stats) => {
if (err) return reject(err)
console.log(stats.toString('minimal'))
resolve()
})
})
`
Each task is defined using h2 header and its child contents, the value of h2 header will be used as task name, its following paragraphs (optional) will be used as task description, and following code block (optional) will be used as task script.
Currently the code block languages are sh bash js javascript and more!.
Now run maid help to display the help for this maidfile:
`bash
❯ maid help
lint It uses ESLint to ensure code quality.
build Build our main app
build:demo You can use JavaScript to write to task script too!
❯ maid help "build*"
build Build our main app
build:demo You can use JavaScript to write to task script too!
`
To run a task, you can directly run maid
`bash
❯ maid build
[13:46:38] Starting 'build'...
🎉 Successfully compiled 3 files with Babel.
[13:46:38] Finished 'build' after 363 ms...
[13:46:38] Starting 'build:demo'...
webpack compiled in 734ms.
[13:46:38] Finished 'build:demo' after 734 ms...
$3
You can run tasks before or after a task:
markdown
build
Run task
deploy after this`bash
webpack --config config/webpack.config.js
`deploy
bash
gh-pages -d dist
`
Expressions that start with
are treated specially. In this case if you run maid build it will also run the deploy task after build has finished.The syntax is simple:
Runs? tasks? where each task name is surrounded by a pair of backticks: .By default a task will run before the current task. So ` Run task build would run build before the task it was described in. The presence of after anywhere in the setence (after Run task) will cause it to be ran after. Commands run synchronously by default. The presence of in parallel in the scentence will cause it to be run in parallel.
Examples:
- Run task build.
- Run task build after this.
- Run tasks clean, build, and lint.
- Run tasks build:app start:server before this.
- Run tasks build:server build:client before this in parallel.
Like npm scripts, when you run a command called build, when it's finished we will also run postbuild task.
Hook syntax:
- pre: Run before a specific task.post
- : Run after a specific task.afterAll
- : Run after all tasks.beforeAll
- : Run before all tasks.
#### bash/sh
##### Read command line arguments
The CLI arguments are passed to executed script, so you can access it like this:
``markdownlog
`bash`
echo $1
Then run maid log nice and it will print nice in the console.
#### js/javascript
The JS script will also be evaluated.
``markdownlog
`js`
console.log(process.argv)
##### Asynchronous task
For asynchonous tasks, you can export a function which returns Promise:
``markdownbuild
`js`
module.exports = async () => {
const files = await readFiles('./')
await buildFiles(files)
}
#### py/python
``markdownlog
`py`
print("cool")
By default, Maid would use maidfile.md or README.md (case-insensitive) in current working directory, when you're using README.md you need to manually specify the section of the markdown you wanna use as Maid tasks like below:
``markdownMy Project
Let me explain..
`bash`some test scripts...
Unlike a maidfile.md which uses all h2 headers as tasks, in README.md only h3 headers under the specified h2 header will be used as tasks. You can add a comment right below the desired h2 header.
Alternatively, if you're not using maidfile.md, you can also use --section h2_header and --path foo.md flags to customize it.
Maid's own development scripts are powered by itself, run maid help or node bin/cli help in this project to get more.
Run ESLint to ensure code quality and code style (via Prettier).
`bash`
yarn eslint . "${@:1}"
If you want to automatically fix lint errors, try adding --fix plugin to the command you run, e.g. maid lint --fix
Use AVA to run unit tests.
`bash`
yarn ava "${@:1}"
Similar to the lint task, you can append any flags for ava command directly when you run the maid command.
Generate a table of contents section in the README.md file.
`bash`
yarn doctoc README.md
1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes:
4. Push to the branch:
5. Submit a pull request :D
maid © egoist, Released under the MIT License.
Authored and maintained by egoist with help from contributors (list).
> github.com/egoist · GitHub @egoist · Twitter @\_egoistlily