Have ideas to improve npm?Join in the discussion! »

    mos

    1.3.1 • Public • Published

    mos

    A pluggable module that injects content into your markdown files via hidden JavaScript snippets

    npm version Build Status Coverage Status Gitter

    Why mos?

    Preview

    The readme you are currently reading uses mos! Here's how the shields are generated:

    <!--@shields('npm', 'travis', 'coveralls', 'gitter')-->
    [![npm version](https://img.shields.io/npm/v/mos.svg)](https://www.npmjs.com/package/mos) [![Build Status](https://img.shields.io/travis/mosjs/mos/master.svg)](https://travis-ci.org/mosjs/mos) [![Coverage Status](https://img.shields.io/coveralls/mosjs/mos/master.svg)](https://coveralls.io/r/mosjs/mos?branch=master) [![Gitter](https://img.shields.io/gitter/room/mosjs/mos.svg)](https://gitter.im/mosjs/mos)
    <!--/@-->

    Table of Contents

    Installation

    Install mos globally:

    npm i -g mos

    Make mos configure your package.json:

    mos --init

    Your package.json will be updated with some new dependencies and script properties:

    {
      "name": "awesome-package",
      "scripts": {
        "test": "mos test",
        "md": "mos",
        "?md": "echo \"Update the markdown files\""
      },
      "devDependencies": {
        "mos": "^1.2.0"
      }
    }

    Manual installation

    You can also install mos directly:

    npm i -D mos

    You'll have to configure the script property in your package.json to use mos (see above).

    Usage

    Mos uses a simple templating syntax to execute JavaScript inside markdown files. The result of the JavaScript execution is then inserted into the markdown file.

    The great thing is, that the template and the markdown file are actually the same file! The code snippets are written inside markdown comments, which are invisible when reading the generated markdown file.

    Lets use mos to write a readme with some dynamic data. Have you ever renamed your package and forgotten to update the readme? Good news! With mos it won't ever happen again:

    README.md

    <!--@h1([pkg.name])-->
    <!--/@-->

    If you view your readme now, it will be empty. However, you have the code that can insert the title in your readme. All you have to do now is to run mos in a terminal.

    Once you've run mos, the readme will look like this:

    <!--@h1([pkg.name])-->
    # my-awesome-module
    <!--/@-->

    Now your readme has both the code that generates the content and the content itself. However, only the content is visible after the readme is generated to HTML by GitHub or npm. Awesome!

    Happy cat

    CLI Usage

    mos

    Regenerate the markdown files if they are out of date.

    mos test

    Test the markdown files. Fails if can't generate one of the markdown files or one of the markdown files is out of date. It is recommended to add this command to the scripts.test property of package.json.

    Optional TAP output

    Mos can generate TAP output via --tap option for use with any TAP reporter.

    mos test --tap | tap-nyan

    NOTE: the CLI will use your local install of mos when available, even when run globally.

    Mos plugins

    In the usage example the package variable was used to access the package info. The variables available in the markdown scope are declared by mos plugins. The package variable is created by the package-json plugin.

    There are a few mos plugins that are installed with mos by default:

    Do you want to write a new one? Read the plugins readme.

    Configuring the default plugins

    It is possible to pass options to the default mos plugins via the mos property in the package.json.

    {
      "mos": {
        "installation": {
          "useShortAlias": true
        }
      }
    }

    To disable a default plugin, pass false instead of a config object:

    {
      "mos": {
        "license": false
      }
    }

    Who uses mos?

    License

    MIT © Zoltan Kochan


    Dependencies dependency status

    Dev Dependencies devDependency status


    What does mos mean?
    It means Markdown on Steroids!

    Install

    npm i mos

    DownloadsWeekly Downloads

    212

    Version

    1.3.1

    License

    MIT

    Last publish

    Collaborators

    • avatar