Yamp

by @angrykoala

npm version Build Status codecov Dependency Status

Yet Another Markdown Parser

The aim of this package is to provide an easy-to-use toolbox for markdown-related task including Html & Pdf conversion.

Features

Upcoming features

Check the project roadmap and our cute kanban board

Installation

To use yamp cli, install it globally using npm:

npm install -g yamp

If you want to use the API instead, install it locally:

npm install --save yamp

then, include yamp in your javascript:

var yamp = require('yamp');

Usage

To create a .pdf file from your markdown file, simply type:

yamp <file.md>

For example:

yamp README.md

Will generate readme.pdf.

Options

To generate pdf and html with default styling and options:

yamp myFile.md --pdf --html

The --no-highlight and --no-style options will greatly reduce your Html and Pdf outputs

Yamp tags

Yamp supports extra tags in your markdown files. Currently using xejs templates. All tags are written between double braces {{ ... }} and are not case-sensitive

Starting a tag with {{# will create a comment tag that will not be rendered into the final file

Yamp styles

Yamp provides several styles for your document (supported for html and pdf outputs).

You can select any of these styles with the option --style [style.css], the same option will enable you to use your own files instead --style [myfolder/mystyle.css]

You can always check the styles with the option --list-styles

API

Include yamp in your javascript with:

var yamp = require('yamp');

You'll have access to different renderers to process your files:

To use a renderer:

var myRenderer = new renderers.pdf(options);
renderer.renderFile(myFile, function(err){
    if (err) return console.log("Error while rendering: "+err);
    else console.log("Rendering was successful");
});

Options

The options accepted by the default renderers are:

Creating new renderers

If you need a custom renderer, instead of using one of the defaults you can extend directly from Renderer class or any of the default renderers:

class MyCustomRenderer extends yamp.Renderer {
    constructor(options) {
        super(options, "default.ejs", yamp.parsers.md2Html);
        this.output="html"; //desired output extension
    }

    beforeLoad(filename){
        //Modify filename or this.fileLoader before loading it
    }


    beforeRender(templateOptions) {
        // Modify the data passed to the template before rendering, including title, content and options
    }

    afterRender(content) {
        // Modify template result (Html)
    }

    fileOutput(content,done) {
        // Write file (preferably to this.options.outputFilename) in the desired format using a parser
    }
}

Custom parser: It is possible to use a custom parser from markdown to Html instead of the built-in yamp.parsers.md2html, the parser must be a function of the type function(originalString,options,callback) that will translate from originalString (markdown) to html, calling the callback(err,res) afterwards.

If, instead of extending from yamp.Renderer you are extending from one of the default renderers, you should only re-implement the methods you need, and usually you should call super().methodName to maintain its basic functionality.

Development Instructions

To contribute to yamp you should clone the official repository https://github.com/angrykoala/yamp or your own fork with git.

You can also download it from GitHub clicking here

It is strongly recommended to install the npm repository version instead of your local copy

Contributors

If you want to contribute to yamp please:

  1. Read CONTRIBUTING.md
  2. Fork from dev branch
  3. Make sure tests passes before pull request
  4. Check the opened and closed issues before creating one

Thanks for your help!

Acknowledgments

YAMP is developed under GNU GPL-3 license by @angrykoala