Mos-plugin-example NPM

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