mos-plugin-example

A mos plugin that combines example code files with their output

Installation

This module is installed via npm:

npm install mos-plugin-example --save

Usage

There is an example/index.js file in this module. Its content is:

'use strict'
console.log('Hello world!')

function sum (a, b) {
  return a + b
}

console.log(sum(1, 2))

//! Comments that start with an exclamation will be inserted into the markdown outside the code block.

function printEachLetter (text) {
  for (let i = 0; i < text.length; i++) {
    console.log(text[i])
  }
}

printEachLetter('Hello world!')

We can load this file via the example plugin. The mos plugin will execute the code in the file and combine the output of the console.logs with the code.

In the current README.md we have this code snippet:

<!--@example('./example/index.js')-->
<!--/@-->

It produces this code block, with the outputs written under the console.logs inside comments:

'use strict'
console.log('Hello world!')
//> Hello world!

function sum (a, b) {
  return a + b
}

console.log(sum(1, 2))
//> 3

Comments that start with an exclamation will be inserted into the markdown outside the code block.

function printEachLetter (text) {
  for (let i = 0; i < text.length; i++) {
    console.log(text[i])
    //> H
    //> e
    //> l
    //> l
    //> o
    //>  
    //> w
    //> o
    //> r
    //> l
    //> d
    //> !
  }
}

printEachLetter('Hello world!')

ES6

example/ can be written in ES6, but they have to be loaded with example.es6.

Mos uses rollup and babel to transpile the example written ES6. However, babel is not installed with mos, so you'll have to install babel manually. Put a .babelrc file in your example folder and configure babel the way it is described here.

Here is an example that is using ES6 in the current package:

const sum = (a, b) => a + b

const numbers = [1, 2]
console.log(sum(...numbers))
//> 3

API

• example(relativePathToFile)
• example.es6(relativePathToFile) - process an example written in ES6

License

MIT © Zoltan Kochan

Dependencies

• babel-runtime: babel selfContained runtime
• codemo: Embeds console output to the code
• independent: Change relative requires to import actual modules

Dev Dependencies

• babel-cli: Babel command line.
• babel-plugin-add-module-exports: Fix babel/babel#2212
• babel-plugin-transform-runtime: Externalise references to helpers and builtins, automatically polyfilling your code without polluting globals
• babel-preset-es2015: Babel preset for all es2015 plugins.
• babel-register: babel require hook
• babel-preset-es2015-rollup: This is babel-preset-es2015, minus modules-commonjs, plus external-helpers. Use it wi
• chai: BDD/TDD assertion library for node.js and the browser. Test framework agnostic.
• cz-conventional-changelog: Commitizen adapter following the conventional-changelog format.
• eslint: An AST-based pattern checker for JavaScript.
• eslint-config-standard: JavaScript Standard Style - ESLint Shareable Config
• eslint-plugin-promise: Enforce best practices for JavaScript promises
• eslint-plugin-standard: ESlint Plugin for the Standard Linter
• ghooks: Simple git hooks
• istanbul: Yet another JS code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. Supports all JS coverage use cases including unit tests, server side functional tests
• mocha: simple, flexible, fun test framework
• mos: A pluggable module that injects content into your markdown files via hidden JavaScript snippets
• semantic-release: automated semver compliant package publishing
• validate-commit-msg: Script to validate a commit message follows the conventional changelog standard