👏 Galvanize your Markdown files with dynamic content
Cheer is the missing modern way to do inline templating in your Markdown files
through an elegant enhanced JavaScript syntax. No more outdated .md, we have
you covered!
- Simple: it's just JavaScript, with some enhancements for your own convenience
- Async-friendly: support asynchronous calls out of the box
- Extensible: thanks to its plugin system
- Neat: no external templates files
- Fast: all commands are executed in parallel
It does support the following features out-of-the-box:
- Badge generation (Shields.io)
- JSDoc documentation (documentation.js)
- Multi-platform shell execution (execa)
Look at this simple example, it:
- Extracts the commands to execute between
<!---and---> - Downloads the latest
cheerpackage information through the npm registry - Parses that raw text as JSON
- Injects the parsed JSON into the template string
- Places the final output between
--->and<!--->
<!--- open('http://registry.npmjs.org/cheer/latest') | json | `Latest push: ${name}@${version}` --->
Latest push: [email protected]
<!--->
Note: the parts in <!--- and ---> stays
pristine, that's the whole point of inline templating, allowing future calls to
replace the outdated output. This even allows you to add cheer --lint to your
CI, making sure your tests breaks if your documentation is outdated!
Who doesn't want to keep its documentation up-to-date?
Got your attention? Let's get started!
npm install --global cheer$ cheer --help
:clap: Galvanize your Markdown files with dynamic content
Usage
$ cheer [options] file...
Options
--dry-run Do not modify the files, but print the modifications to stdout and exit
--lint Do not modify the files, but lint them and exit with an error code if the files are outdated
--print-ast Print the AST nodes to stdout and exit
--print-tokens Print the Lexer tokens to stdout and exit
Example
$ cheer readme.md
This convenience method allows to call the fromFile method with an array of filepaths. The calls are performed in parallel.
- files:
Array<string>— The paths of the files to iterate on - options:
Object— The options to pass down tofromFile
Returns Promise<Array<string>> — Resolving when all the fromFile calls are done with success.
This convenience method allows to call the fromBuffer method with a filepath. The current working directory ( options.cwd ) is set to the filepath directory.
Returns Promise<string> — Resolving when the fromBuffer call is done with success, along with overwriting the filepath with the result.
Take an input buffer and return a new transformed buffer with all the expressions executed and the results injected into the new buffer.
- buffer:
string|buffer.Buffer— The input to galvanize - $1:
Object— The options- $1.cwd:
string— The current working directory - $1.dryRun:
boolean— Write the output to stdout and exit - $1.filepath:
string— Used by some plugins - $1.linebreak:
string— Which linebreak character should be used, inferred from the buffer by default - $1.lint:
boolean— Check the file for outdated content, and exit with the appropriate error code. Meant to be used in a CI or innpm run prepublish - $1.printAst:
boolean— Print the parser AST to stdout and exit - $1.printTokens:
boolean— Print the lexer tokens to stdout and exit
- $1.cwd:
Returns Promise<string> — Resolving a new transformed buffer.
- 1.0.0
- Bump stable
Creative Commons — CC0 1.0 Universal
To the extent possible under law, Aymeric Beaumet has waived all copyright and related or neighboring rights to this work.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent