 __      __   __   __   ______   ____                
/\ \  __/\ \ /\ \ /\ \ /\__  _\ /\  _`\   /'\_/`\    
\ \ \/\ \ \ \\ `\`\/'/'\/_/\ \/ \ \ \L\_\/\      \   
 \ \ \ \ \ \ \`\/ > <     \ \ \  \ \  _\/\ \ \__\ \  
  \ \ \_/ \_\ \  \/'/\`\   \_\ \__\ \ \/  \ \ \_/\ \ 
   \ `\___x___/  /\_\\ \_\ /\_____\\ \_\   \ \_\\ \_\
    '\/__//__/   \/_/ \/_/ \/_____/ \/_/    \/_/ \/_/

WXI Flavored Markdown

This is a package that adds a couple new features to markdown without tinkering with other markdown flavors such as GitHub Flavored Markdown (GFM) or the default markdown parser.

This npm package started out as a rewrite if marked package, a markdown parser library by chjj@github, but now WXI Flavored Markdown only extends it.

Even added a library called libmdxi. It should allow you to create your own markdown parsers. For examples look at cplogfm.coffee.

The WXI Flavor:

It adds:

Meta Tags:

Use if you want to add information about the file. Meta name (such as author or version) will be converted to lowercase so don't worry about matching the standarts' case. You can add one line metas with @@name: value or multiline metas by surrounding with @@@ ... @@@.

What it looks like in action:

One Line

@@Author: Logan Howlett
@@VErSiOn: 0.6    <- This is the same 
@@version: 0.7    <- As this
@@VeRSION: 0.8    <- Or this, or "version" and "VERSION"
Duis autem vel eum iriure dolor in hendrerit 
in vulputate velit esse molestie consequat, 
vel illum dolore eu feugiat nulla facilisis.

Multi Line

@@@
description:Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
Phasellus vel sapien quis leo volutpat viverra. 
Pellentesque tempor tortor sagittis diam volutpat facilisis. 
Aenean eleifend tristique.
@@@
@@@
description2:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
Phasellus vel sapien quis leo volutpat viverra. 
Pellentesque tempor tortor sagittis diam volutpat facilisis. 
Aenean eleifend tristique.
@@@
@@@description3
Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
Phasellus vel sapien quis leo volutpat viverra. 
Pellentesque tempor tortor sagittis diam volutpat facilisis. 
Aenean eleifend tristique.
@@@
 
Nam liber tempor cum soluta nobis eleifend option congue 
nihil imperdiet doming id quod mazim placerat facer possim 
assum. Lorem ipsum dolor sit amet, consectetuer adipiscing 
elit, sed diam nonummy nibh euismod tincidunt ut laoreet 
dolore magna aliquam erat volutpat. Ut wisi enim ad minim 
veniam, quis nostrud exerci tation ullamcorper suscipit 
lobortis nisl ut aliquip ex ea commodo consequat.

Great, but how to install it?

To install automatically:

WXIFM can be installed by this command:

$``npm install wxi-flavored-markdown

Or if you want to install the package and automatically save dependency to your package.json

$``npm install wxi-flavored-markdown --save

If you are a developer (can I hear a thank youuu?)

Clone repository:

$``git clone git@github.com:aponxi/npm-wxi-flavored-markdown.git

and

$``npm install --dev

to install build tools and what not.

We have it installed, now how do we use it?

Following is how to use this script in coffeescript <3

Example

# require module 
wxi_flavor = require ('wxifm')
 
# let the text be some file 
fs = require 'fs'
text = fs.readFileSync('test.md','utf8')
 
# Parse the text by 
# new wxi_flavor (String text[, Object options]); 
t = new wxi_flavor text, {validate: on}
# meta information is stored in wxi_flavor.meta 
# lets view the meta information (prettyfied) that has been parsed in console. 
console.log JSON.stringify t.meta, null, "    "
# render the text as html 
rendered = t.render()
# view rendered output in console 
console.log rendered

Output would be:

{
    "author": [
        "logan"
    ],
    "homepage": [
        "www.weaponxi.com"
    ],
    "tags": {
        "markdown": null,
        "github": null,
        "repetitivetag": null,
        "tagwithsubtags": [
            "subtag"
        ],
        "another": [
            "subtag",
            "subtag2",
            "repeating",
            "this",
            "repeating"
        ]
    },
    "version": "1.0.2",
    "status": [
        "stable"
    ],
    "url": [
        "http://www.something.com"
    ],
    "description3": [
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit. \nPhasellus vel sapien quis leo volutpat viverra. \nPellentesque tempor tortor sagittis diam volutpat facilisis. \nAenean eleifend tristique."
    ],
    "description1": [
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit. \nPhasellus vel sapien quis leo volutpat viverra. \nPellentesque tempor tortor sagittis diam volutpat facilisis. \nAenean eleifend tristique."
    ],
    "description2": [
        "\nLorem ipsum dolor sit amet, consectetur adipiscing elit. \nPhasellus vel sapien quis leo volutpat viverra. \nPellentesque tempor tortor sagittis diam volutpat facilisis. \nAenean eleifend tristique."
    ]
}

And it outputs the rendered text.

Sweet, and there are options you can set!

`validate` (`boolean`):

- `on`: Turns on validation
- `off`: Turns off validation

`ignore_invalid` (`boolean`):

- `on` :  Don't return invalid metas but return others
- `off` : All must be valid to return results

`cover_tracks` (`boolean`):

- `on` : Remove metas found before rendering markdown
- `off`: Setting off

`verbose` (`boolean`):

- `on` : Turn on verbose messages (default) 
- `off` : Turn off verbose mode

`debug` (`boolean`):

- `on` : Turn on verbose messages and extra debug information.
- `off` : Turn off debug mode (default)

More usage!

Some meta tags are special, and treated accordingly. This is the list of special tags and how they are treated:

All metas:

Case is not important. @@NAME: value or @@nAmE: value are the same as @@name: value

`Version` meta - Specifies version of the file:

There can be only one version, if there are multiple versions provided such as:

@@version: 1.2

@@version: 1.3

Only the first one (the one closer to the beginning of the file) will be parsed. The next one will be discarded.
You can write versions with v prefix and they will be excluded.

@@version: v1.0 -> {version: "1.0"}

`Tag` meta - Defines tags for the file. Uses tagxi™ which allows subtags.

Tags can be defined as @@tag:.... or @@tags:...
Tag delimeter can be either , or ;. And they can have spaces after comma. How about before? Example:

@@tags:markdown, github

@@tags:markdown,github

@@tags:markdown; github

@@tags:markdown;github
Tags can have subtags as @@tags:GitHub,OS:Linux and can also have multiple subtags like @@tags:Github,OS:Linux:Ubuntu:12.04LTS. As Subtags are chained, their order matter and there can be more than one of the same subtag as in @@tags:GitHub,Function:Core:SubFunction:Core. Example:

@@tags:TagWithSubtags:subtag,another:subtag:subtag2:repeating:this:repeating

@@tags:TagWithSubtags:subtag;another:subtag:subtag2:repeating:this:repeating
Tags can end with either the delimeter or a line break. @@tags:Github or @@tags:Github, or @@tags:Github;

Repetitive Tags ( not subtags ) are intelligently merged. Example:

@@tags:markdown, github, repetitivetag, tagwithsubtags:subtag, another:subtag:subtag2:repeating:this:repeating,repetitivetag, repetitivetag:withsubby, repetitivetag:withsubtag

@@tags:markdown;github; repetitivetag; tagwithsubtags:subtag, another:subtag:subtag2:repeating:this:repeating; repetitivetag; repetitivetag:withsubby; repetitivetag:withsubtag

Would return:

{
    "tags": {
            "markdown": null,
            "github": null,
            "repetitivetag": [
                "withsubby",
                "withsubtag"
            ],
            "tagwithsubtags": [
                "subtag"
            ],
            "another": [
                "subtag",
                "subtag2",
                "repeating",
                "this",
                "repeating"
            ]
        }
}

As seen above, if a tag doesn't have a subtag it will be null.
~~Currently tags do not allow - or _ in names. This will be fixed in aponxi/npm-wxi-flavored-markdown#2~~

Notes to organize on this readme

Added extensibility, you can now extend the markdown parser. example: src/lib/cplogfm.coffee
There are four stages to this program.
1. Initialize : Iterates over "meta" regular expressions. It captures the things that we need to parse.
2. Process : If it is a special meta that has multiple stuff under it, like @@Tags: tag1,tag2:subtag etc. It processes it. In this example it processes this "meta" called Tags because it needs to get the tag names from there and subtags. This example uses the tagxi™.
3. Validate: It modifies the meta values. For example use this if you wanted to Capitalize the first letter of @@Author: logan.
4. Finalize: This manipulates the captured token. Like if the captured token is an url, you might want to place html anchor tags around it. Or if it is a token that doesn't need to be seen on the rendered html, then you might replace it with "" - so that it would be removed.

Process, Validate and Finalize methods look for token names, and if there is a special processing/validating/finalizing-aka replacing- method, then it runs the token through that method. In example, if you had captured an @@author: logan token and wanted to capitalize it, then you would add a author method under validate method group.

Legal mombo jombo

If you would mention WeaponXI in your source code or under credits or something it would mean the world to me!