@fullstackio/cqmd

6.1.2 • Public • Published

cqmd: A markdown preprocessor for cq code blocks npm package

cqmd is a CLI tool markdown preprocessor that parses cq query blocks and replaces them with "regular" markdown code blocks.

Advanced Users Note

If you want fine-grained control over how the markdown is parsed, you may want to use remark-cq instead

Install

$ npm install --global @fullstackio/cqmd

Usage

$ cqmd --path <path/to/code/basepath> <input-markdown-file>

# or

$ cat file | cqmd --path <path>

Examples

# process a single file to stdout
cqmd --path code manuscript/chapters/forms.md

# process a single file to an output file
cqmd --path code --output forms-out.md manuscript/chapters/forms.md

# process a single file, adjusting paths, to the preview directory
cqmd --path manuscript --imgPath ../manuscript/ --output preview/ manuscript/chapters/forms.md

# watch a glob of files
cqmd --path manuscript --adjustPath ../manuscript/ --output preview/ --watchGlob 'manuscript/chapters/*.md'

Markdown Format

To use cqmd you write a normal markdown file but instead of using indented code blocks you use the following syntax:

{lang=myLang,crop-query=myQuery,format=myFormat}
<<[](path/to/file.js)

For example, say we have a file examples/basics.js with the following code:

// examples/basics.js
const bye = function() {
  return "bye";
};
bye(); // -> 'bye'

let Farm = () => "cow";

In our markdown file we could include the code block by using the following markdown:

// document.md

And here is how we say goodbye:

{lang=javascript,crop-query=.bye,format=gfm}
<<[](examples/basics.js)

Isn't that neat?

Notice that none of the values are quoted. You do not quote your crop-query. If you use quotes then you are searching for a string.

Now we can process document.md like so:

$ cqmd --path . document.md

Which emits:

// document.md

And here is how we say goodbye:

```javascript
const bye = function() {
  return 'bye';
}
```

Isn't that neat?

You can see the full list of possible queries in the cq manual.

Using Remark Extensions

To use a remark extension, pass the remarkExtensions option like this:

./src/cli.js --remarkExtensions="remark-frontmatter,remark-yaml-config"  examples/frontmatter.md

Library Usage

var cqmd = require("@fullstackio/cqmd").default;
cqmd(input, { path: __dirname }).then(function(results) {
  console.log(results);
});

But, this library is just a thin wrapper to provide a CLI tool. If you're using this as a library you may want to use remark-cq instead

If you'd like to create a custom formatting function, use the format key in the options.

Contributing

Please feel free to submit pull requests.

Authors

Originally written by Nate Murray.

License

MIT

Readme

Keywords

none

Package Sidebar

Install

npm i @fullstackio/cqmd

Weekly Downloads

25

Version

6.1.2

License

MIT

Unpacked Size

80.7 kB

Total Files

21

Last publish

Collaborators

  • eigenjoy
  • fullstackio
  • pozymasika