cheer

👏 Galvanize your Markdown files with dynamic content

Introduction

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 
Downloads the latest cheer package 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: cheer@0.0.1
<!--->

Note: the parts in  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!

Rationale

Who doesn't want to keep its documentation up-to-date?

Got your attention? Let's get started!

Install

npm install --global cheer

Usage - CLI

$ 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

Usage - API

`fromFiles(files, options)`

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 to fromFile

Returns Promise<Array<string>> — Resolving when all the fromFile calls are done with success.

`fromFile(file, $1)`

This convenience method allows to call the fromBuffer method with a filepath. The current working directory ( options.cwd ) is set to the filepath directory.

file: string — The path of the file to galvanize
$1: Object — The options passed down to fromBuffer
- $1.cwd: string — The current working directory from which the file should be resolved, set to the file directory before calling fromBuffer
- $1.options: ...any

Returns Promise<string> — Resolving when the fromBuffer call is done with success, along with overwriting the filepath with the result.

`fromBuffer(buffer, $1)`

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 in npm run prepublish
- $1.printAst: boolean — Print the parser AST to stdout and exit
- $1.printTokens: boolean — Print the lexer tokens to stdout and exit

Returns Promise<string> — Resolving a new transformed buffer.

Changelog

1.0.0
- Bump stable

License

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.

aymericbeaumet / cheer