angrykoala/yamp

Yet Another Markdown Parser

Yamp

by @angrykoala

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.

• GitHub: https://github.com/angrykoala/yamp
• Npm: https://www.npmjs.com/package/yamp

Features

• HTML conversion
• PDF conversion
• Code highlight support
• Github-style and academic output
• API to use yamp programmatically
• Custom styles
• CSS-embedded HTML (just open it offline in any browser)
• HTML tags support (for PDF output too)
• Include other files in your markdown
• HTML presentations
• Front Matter metadata
• Custom xejs-based tags ({{}})
• Koalafied

Upcoming features

• Custom templates
• Client-side web support (browserify)

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

• -h, --help to display a basic usage information
• -V, --version to display yamp version installed
• -o, --output <file> output filename (without extension) e.g. yamp my_file.md -o final_name
• --pdf to generate a pdf (default)
• --htmlto generate html
• --remarkto generate a html presentation using remark
• -t, --title [value] to add a custom title to Html pages
• --style <file> to set change the css style (supports the provided styles and custom styles)
  • Option not suported along with --no-style
• --no-style to disable CSS styling
  • Option not supported along with --style <file>
• --list-styles will list all the styles provided by yamp
  • These styles will be supported by --style option
• --minify to minify Html output
• --no-tags to disable custom Yamp tags
• --no-highlight to disable code highlight
• --no-front-matter to disable front-matter metadata
• -k, --koala to koalify your outputs

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

• include [file.md]: Includes the given text file (markdown or not), the tags on the included file will also be parsed, allowing nested file structure.
• date: Will write the current date (at the moment of rendering).
• page break: Will force a page break in pdf output.
• yamp version: Will display the yamp version used to render the document.

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).

• github.css Default style, will look similar to Github style
• acm-sig.css Academic style based on ACM SIG templates

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:

• yamp.renderers.html to process a markdown file into an full Html page
• yamp.renderers.pdf to process a markdown into a pdf

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:

• outputFilename: name of the output filename (without extension), will default to the input filename
• highlight: (true) indicates if code blocks should be highlighted
• style: (true) indicates if default style should be used or no style at all. If a filename is passed, it will use it as custom css style
• minify: (false) whether the Html output should be minified or not
• title: Custom title for the Html page
• tags: (true) whether to parse yamp tags or not ({{ ... }})
• koala: (false) true to koalify your outputs

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

• To install execute npm install in the downloaded/cloned folder
• To test, execute npm test
  • The tests will also run jshint
• To execute the CLI, execute npm start -- <file> [options]
• To install your local version globally, execute npm install -g . on the project folder
• To generate documentation (with installed version of yamp) execute npm run docs

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

• Marked as markdown parser
• Github-markdown.css as default style
• Highlight.js for code highlighting
• html-pdf for pdf generation
• remark for html slides output
• pubcss for academic output style

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

yamp's Issues

Improve tests coverage

Improve average coverage of the unit tests to at least 70%

Use custom title in html

Use a custom title, file title or the first header as title for the html page

Support html attributes in title parser

Currently, title parser accepts any html header 1 of the form <h1>Title</h1>, however, it doesn't support using attributes such as <h1 class="title">Title</h1>

One solution would be changing the current regex into a regex that accepts arguments and adapting the slice call that get the content to use other regex

/<h1(.*?>).+?<\/h1>/

Add watermark with a koala in generated documents

Either as a selectable option or as an easter egg. It's a totally necessary functionality.

Add toc option

Add a table of contests option (--toc) maybe use https://www.npmjs.com/package/markdown-it-table-of-contents

Include code highlight only if necessary

Using the highlightRenderer and a flag boolean, it should be possible to disable highlight automatically if no code block was created (check this) so highlight css and js will only be included if needed

Add new options to CLI

Add options to customize yamp behavior:

• title
• output files
• style
• template (requires #15 and #37)

Online presentations template

Support online presentations with remark or reveal

Create gh-pages with readme, documentation and examples

This page could serve as documentation and for test of the client-side functionalitites ( #6 )

Force page jump tag

use a tag (like {{page-jump}} or in markdown files to force a page-jump on pdf output

this tag should follow the same rules as the tags defined on #15

and options (maybe default) should apply a page jump on every <h1>

Unit test cases for each option

Test all cli options and different combination in the unit tests cases

Check minimum Node compatibility

Check the minimun version required to run yamp and add it to the package.json. Increase compatibility if possible

Usage documentation

Add user guide to readme

Include different content loaders

For example:

• Raw file loader
• File with templates rendering loader
• Direct content
• Stream content

Code beautifier

Add code beautifier to project workflow (for example js-beautify)

Support include in markdown

Support some include tags to compile several .md files into one file (check current standards on extra tags for markdown)

e.g.

# My Book
{include chapter1.md}
{include chapter2.md}
**The End**

Add tests and CI

Make some basic tests checking all the parsing and add continuous integration service to the repo

Client-side markdown parser

user browserify or similar to provide a client-side parser, allowing to dynamically parse blocks of code

e.g.

<p class="markdown">
   ## A nice header
</p>

Embedded css/js option

set an option to embed or not the styles and scripts

Support custom parser

provide one (or more) default parsers, but allow the usage of other markdown parsers optionally

Separate renderers in module renderer

have to separate function (or classes) for each type of rendering (children of a parent class maybe?) and export all of them, so you don't need to pass an output value with your configuration object.

So it loads something like:

var htmlRenderer=require('./app/renderer').html;

Add markdow-it plugins

Add and tests some markdown-it plugins to include extra elements when parsing markdown:

• https://github.com/markdown-it/markdown-it-sup
• https://github.com/markdown-it/markdown-it-mark
• https://github.com/markdown-it/markdown-it-footnote
• https://github.com/markdown-it/markdown-it-ins
• https://github.com/markdown-it/markdown-it-emoji

Add custom tags to markdown

Simple tags to use before rendering markdown.

e.g.
{{ include "file" }}

Code blocks truncated

Code blocks are formatted in HTML using the

 ... </ code></ pre> tags. If the block is greater than the width of the page, a horizontal scroll bar is displayed (as github pages, off course).

When creating the PDF, this bar is displayed as a static image, it does not allow scrolling text, and the right side is hidden.
This effect is increased because the font in the PDF is too big. With the current font, the code block has a width of 61 characters, apparently.
For example, the following block:
text in a code block with many characters:
1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890

will create this HTML code:
<pre><code> text in a code block with many characters:
1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890
</code></pre>

to display in the PDF as follows:

Inject css into html

inject styles within the html (optional) to make it easier to open and process into a pdf

Comments and documentation

Add comments to the code and some documentation (Readme,wiki or groc)

Elements are being cut by pages

The Text and elements are not 'page aware' in the pdfs, so tables, images and stuff may be directly cut between pages.

Make all this content page aware, and force a page break when an element doesn't fit

Highlight support and css styles should be optional

To avoid oversizing html and pdf files, all styles and scripts should only be loaded when needed, and it's use optionsl

Allow the use of emojis

Check the plugin https://github.com/markdown-it/markdown-it-emoji to allow the use of emojis (optionally)

Create npm package

create a npm package/module, easy to install and add to a node project

Add academic style support

Use something similar to latex (or pandoc if necessary)

Check pdf-html fonts

The font-size should be similar in the html and pdf output, check github style.

relate to #12

Header and footer support for pdfs

using <div id="pageHeader"></div> and <div id="pageFooter"></div> it would be possible to customize the pdf header and footer of each page

Clean github-markdown stylesheet

A lot of rules are duplicated or are not relevant to the use of the github stylesheet in yamp

Windows support

Add windows support and tests

Images not working on pdf output

Images (![](image.png)) are not properly added to the pdf output (while working on the html output)

Module API

API to use yamp as a module, importing it into a node app

Accept metadata in markdown file

A header in some standard format (json, yml, etc..) could provide some compiling default information (title, style etc..). (Front-matter)

Add support for metadata headers in markdown.
e.g.

title: mytitle
style: mystyle
tags: false
-------------
# my md file

Add default css to provide with html

A default stylesheet will be useful for future rendering and use of the html files

Get input/output files from extension

If no option given, use the file extension to check the input and output format

Add code highlight support

So code blocks will be colored according to language (check highlight.js)

Add proper footnote support

Add footnote support

My text[^1]

[^1]: Example footnote

The markdown-it plugin for footnotes (https://github.com/markdown-it/markdown-it-footnote) does not work properly on pdf output.

use a different parser for footnotes or modify markdown-it plugin

Live parser

Create a real-time md parser that only process the changed elements

Allow converting multiple files

Either converting them separately or joining into one, multiple input files should be allowed

Optional minifier to html output

Check if uglify affect pdf

Check pdf compressor

Check lossless pdf compressors to see if the final size could be reduced

Add a markdown-ejs template step

related to #15 , use ejs before parsing to include files, templates and elements to the markdown file

Pdf output support

support pdf output generated from html file

Test other markdown parsers and implement multiple renderers

Try marked as md2html parser and create a new renderer

Marked should be faster for rendering md2html, so it may be a good idea to implement a renderer based on marked, check if all functionality can be adapted (markdown-it plugins)

Avoid parsing unwanted tags

Add a step to change unwanted markdown tags <% tags into <%%

for example, when the tag is inside a code block