Gitdown adds additional functionality (generating table of contents, including documents, using variables, etc.) to GitHub Flavored Markdown.

// Generate table of contents
{"gitdown": "contents"}
{"gitdown": "contents", "maxLevel": 4}
{"gitdown": "contents", "rootId": "features"}

// Use a custom defined variable
{"gitdown": "variable", "name": "nameOfTheVariable"}

// Include file
{"gitdown": "include", "file": "./LICENSE.md"}

// Get file size
{"gitdown": "filesize", "file": "./src/gitdown.js"}
{"gitdown": "filesize", "file": "./src/gitdown.js", "gzip": true}

// Generate badges
{"gitdown": "badge", "name": "npm-version"}
{"gitdown": "badge", "name": "bower-version"}
{"gitdown": "badge", "name": "travis"}
{"gitdown": "badge", "name": "david"}
{"gitdown": "badge", "name": "david-dev"}
{"gitdown": "badge", "name": "waffle"}

// Print date
{"gitdown": "date", "format": "YYYY"}

• Cheat Sheet
• Contents
• Command Line Usage
• API Usage
  • Gulp
  • Logging
• Syntax
  • Ignoring Sections of the Document
  • Register a Custom Helper
• Features
  • Generate Table of Contents
  • Heading Nesting
  • Find Dead URLs and Fragment Identifiers
  • Reference an Anchor in the Repository
  • Variables
  • Include File
  • Get File Size
  • Generate Badges
  • Print Date
  • Gitinfo

npm install gitdown -g
gitdown ./.README/README.md --output-file ./README.md

Gitdown is designed to be run using either of the build systems, such as Gulp or Grunt.

var Gitdown = require('gitdown'),
    gitdown;

// Read the markdown file written using the Gitdown extended markdown.
// File name is not important.
// Having all of the Gitdown markdown files under ./.README/ path is the recommended convention.
gitdown = Gitdown.readFile('./.README/README.md');

// If you have the subject in a string, call the constructor itself:
// gitdown = Gitdown.read('literal string');

// Get config.
gitdown.getConfig()

// Set config.
gitdown.setConfig({
    gitinfo: {
        gitPath: __dirname
    }
})

// Output the markdown file.
// All of the file system operations are relative to the root of the repository.
gitdown.writeFile('README.md');

Gitdown writeFile method returns a promise, that will make Gulp wait until the task is completed. No third-party plugins needed.

var gulp = require('gulp'),
    Gitdown = require('gitdown');

gulp.task('gitdown', function () {
    return Gitdown
        .readFile('./.README/README.md')
        .writeFile('README.md');
});

gulp.task('watch', function () {
    gulp.watch(['./.README/*'], ['gitdown']);
});

Gitdown is using console object to log messages. You can set your own logger:

gitdown.setLogger({
    info: function () {},
    warn: function () {}
});

The logger is used to inform about Dead URLs and Fragment Identifiers.

Gitdown extends markdown syntax using JSON:

{"gitdown": "helper name", "parameter name": "parameter value"}

The JSON object must have a gitdown property that identifies the helper you intend to execute. The rest is a regular JSON string, where each property is a named configuration property of the helper that you are referring to.

JSON that does not start with a "gitdown" property will remain untouched.

Use HTML comment tags to ignore sections of the document:

Gitdown JSON will be interpolated.
<!-- gitdown: off -->
Gitdown JSON will not be interpolated.
<!-- gitdown: on -->
Gitdown JSON will be interpolated.

gitdown.registerHelper('my-helper-name', {
    /**
     * @var {Number} Weight determines the processing order of the helper function. Default: 10.
     */
    weight: 10,
    /**
     * @param {Object} config JSON configuration.
     * @return {mixed|Promise}
     */
    compile: function (config) {
        return 'foo: '   config.foo;
    }
});

{"gitdown": "my-helper-name", "foo": "bar"}

Produces:

foo: bar

{"gitdown": "contents"}

Generates table of contents.

The table of contents is generated using markdown-contents.

{"gitdown": "contents", "maxLevel": 4, "rootId": "features"}

* [Generate Table of Contents](#features-generate-table-of-contents)
    * [Example](#features-generate-table-of-contents-example)
    * [JSON Configuration](#features-generate-table-of-contents-json-configuration)
* [Heading Nesting](#features-heading-nesting)
    * [Parser Configuration](#features-heading-nesting-parser-configuration)
* [Find Dead URLs and Fragment Identifiers](#features-find-dead-urls-and-fragment-identifiers)
    * [Parser Configuration](#features-find-dead-urls-and-fragment-identifiers-parser-configuration)
* [Reference an Anchor in the Repository](#features-reference-an-anchor-in-the-repository)
    * [JSON Configuration](#features-reference-an-anchor-in-the-repository-json-configuration)
    * [Parser Configuration](#features-reference-an-anchor-in-the-repository-parser-configuration)
* [Variables](#features-variables)
    * [Example](#features-variables-example)
    * [JSON Configuration](#features-variables-json-configuration)
    * [Parser Configuration](#features-variables-parser-configuration)
* [Include File](#features-include-file)
    * [Example](#features-include-file-example)
    * [JSON Configuration](#features-include-file-json-configuration)
* [Get File Size](#features-get-file-size)
    * [Example](#features-get-file-size-example)
    * [JSON Configuration](#features-get-file-size-json-configuration)
* [Generate Badges](#features-generate-badges)
    * [Supported Services](#features-generate-badges-supported-services)
    * [Example](#features-generate-badges-example)
    * [JSON Configuration](#features-generate-badges-json-configuration)
* [Print Date](#features-print-date)
    * [Example](#features-print-date-example)
    * [JSON Configuration](#features-print-date-json-configuration)
* [Gitinfo](#features-gitinfo)
    * [Example](#features-gitinfo-example)
    * [Supported Properties](#features-gitinfo-supported-properties)
    * [JSON Configuration](#features-gitinfo-json-configuration)
    * [Parser Configuration](#features-gitinfo-parser-configuration)

Github markdown processor generates heading ID based on the text of the heading.

The conflicting IDs are solved with a numerical suffix, e.g.

# Foo
## Something
# Bar
## Something

<h1 id="foo">Foo</h1>
<h2 id="something">Something</h1>
<h1 id="bar">Bar</h1>
<h2 id="something-1">Something</h1>

The problem with this approach is that it makes the order of the content important.

Gitdown will nest the headings using parent heading names to ensure uniqueness, e.g.

# Foo
## Something
# Bar
## Something

<h1 id="foo">Foo</h1>
<h2 id="foo-something">Something</h1>
<h1 id="bar">Bar</h1>
<h2 id="bar-something">Something</h1>

Uses Deadlink to iterate through all of the URLs in the resulting document. Throws an error if either of the URLs is resolved with an HTTP status other than 200 or fragment identifier (anchor) is not found.

This feature is under development. Please suggest ideas https://github.com/gajus/gitdown/issues

{"gitdown": "anchor"}

Generates a Github URL to the line in the source code with the anchor documentation tag of the same name.

Place a documentation tag @gitdownanchor <name> anywhere in the code base, e.g.

/**
 * @gitdownanchor my-anchor-name
 */

Then reference the tag in the Gitdown document:

Refer to [foo]({"gitdown": "anchor", "name": "my-anchor-name"}).

The anchor name must match /^[a-z] [a-z0-9\-_:\.]*$/i.

Gitdown will throw an error if the anchor is not found.

{"gitdown": "variable"}

Prints the value of a property defined under a parser variable.scope configuration property. Throws an error if property is not set.

var gitdown;

gitdown = Gitdown(
    '{"gitdown": "variable", "name": "name.first"}'  
    '{"gitdown": "variable", "name": "name.last"}'
);

gitdown.setConfig({
    variable: {
        scope: {
            name: {
                first: "Gajus",
                last: "Kuizinas"
            }
        }
    }
});

{"gitdown": "include"}

Includes the contents of the file to the document.

The included file can have Gitdown JSON hooks.

See source code of ./.README/README.md.

{"gitdown": "filesize"}

Returns file size formatted in human friendly format.

{"gitdown": "filesize", "file": "src/gitdown.js"}
{"gitdown": "filesize", "file": "src/gitdown.js", "gzip": true}

Generates:

8.7 kB
2.38 kB

{"gitdown": "badge"}

Gitdown generates markdown for badges using the environment variables, e.g. if it is an NPM badge, Gitdown will lookup the package name from package.json.

Badges are generated using http://shields.io/.

What service are you missing? Raise an issue.

{"gitdown": "badge", "name": "npm-version"}
{"gitdown": "badge", "name": "travis"}
{"gitdown": "badge", "name": "david"}

Generates:

[![NPM version](http://img.shields.io/npm/v/gitdown.svg?style=flat)](https://www.npmjs.org/package/gitdown)
[![Travis build status](http://img.shields.io/travis/gajus/gitdown/master.svg?style=flat)](https://travis-ci.org/gajus/gitdown)
[![Dependency Status](https://david-dm.org/gajus/gitdown.svg?style=flat)](https://david-dm.org/gajus/gitdown)

{"gitdown": "date"}

Prints a string formatted according to the given moment format string using the current time.

{"gitdown": "date"}
{"gitdown": "date", "format": "YYYY"}

Generates:

1442942137
2015

{"gitdown": "gitinfo"}

Gitinfo gets info about the local GitHub repository.

{"gitdown": "gitinfo", "name": "username"}
{"gitdown": "gitinfo", "name": "name"}
{"gitdown": "gitinfo", "name": "url"}
{"gitdown": "gitinfo", "name": "branch"}

gajus
gitdown
https://github.com/gajus/gitdown
master