npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@gnd/gitdown

v2.5.3

Published

Github markdown preprocessor.

Downloads

6

Readme

NPM version Travis build status Dependency Status

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

Cheat Sheet

// 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"}

Contents

Command Line Usage

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

API Usage

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

const Gitdown = require('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.
const 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');

Gulp

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

const gulp = require('gulp');
const Gitdown = require('gitdown');

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

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

Logging

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

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

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

Syntax

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.

Ignoring Sections of the Document

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.

Register a Custom Helper

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: (config) => {
        return 'foo: ' + config.foo;
    }
});
{"gitdown": "my-helper-name", "foo": "bar"}

Produces:

foo: bar

Features

Generate Table of Contents

{"gitdown": "contents"}

Generates table of contents.

The table of contents is generated using markdown-contents.

Example

{"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-1)
* [Reference an Anchor in the Repository](#features-reference-an-anchor-in-the-repository)
    * [JSON Configuration](#features-reference-an-anchor-in-the-repository-json-configuration-1)
    * [Parser Configuration](#features-reference-an-anchor-in-the-repository-parser-configuration-2)
* [Variables](#features-variables)
    * [Example](#features-variables-example-1)
    * [JSON Configuration](#features-variables-json-configuration-2)
    * [Parser Configuration](#features-variables-parser-configuration-3)
* [Include File](#features-include-file)
    * [Example](#features-include-file-example-2)
    * [JSON Configuration](#features-include-file-json-configuration-3)
* [Get File Size](#features-get-file-size)
    * [Example](#features-get-file-size-example-3)
    * [JSON Configuration](#features-get-file-size-json-configuration-4)
* [Generate Badges](#features-generate-badges)
    * [Supported Services](#features-generate-badges-supported-services)
    * [Example](#features-generate-badges-example-4)
    * [JSON Configuration](#features-generate-badges-json-configuration-5)
* [Print Date](#features-print-date)
    * [Example](#features-print-date-example-5)
    * [JSON Configuration](#features-print-date-json-configuration-6)
* [Gitinfo](#features-gitinfo)
    * [Example](#features-gitinfo-example-6)
    * [Supported Properties](#features-gitinfo-supported-properties)
    * [JSON Configuration](#features-gitinfo-json-configuration-7)
    * [Parser Configuration](#features-gitinfo-parser-configuration-4)

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | maxLevel | The maximum heading level after which headings are excluded. | 3 | | rootId | ID of the root heading. Provide it when you need table of contents for a specific section of the document. Throws an error if element with the said ID does not exist in the document. | N/A |

Heading Nesting

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>

Parser Configuration

| Name | Description | Default | | --- | --- | --- | | headingNesting.enabled | Boolean flag indicating whether to nest headings. | true |

Find Dead URLs and Fragment Identifiers

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.

Parser Configuration

| Name | Description | Default | | --- | --- | --- | | deadlink.findDeadURLs | Find dead URLs. | false | | deadlink.findDeadFragmentIdentifiers | Find dead fragment identifiers. | false |

Reference an Anchor in the Repository

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.

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | name | Anchor name. | N/A |

Parser Configuration

| Name | Description | Default | | --- | --- | --- | | anchor.exclude | Array of paths to exclude. | ['./dist/*'] |

Variables

{"gitdown": "variable"}

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

Example

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

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

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | name | Name of the property defined under a parser variable.scope configuration property. | N/A |

Parser Configuration

| Name | Description | Default | | --- | --- | --- | | variable.scope | Variable scope object. | {} |

Include File

{"gitdown": "include"}

Includes the contents of the file to the document.

The included file can have Gitdown JSON hooks.

Example

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

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | file | Path to the file. The path is relative to the root of the repository. | N/A |

Get File Size

{"gitdown": "filesize"}

Returns file size formatted in human friendly format.

Example

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

Generates:

8.62 KB
2.58 KB

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | file | Path to the file. The path is relative to the root of the repository. | N/A | | gzip | A boolean value indicating whether to gzip the file first. | false |

Generate Badges

{"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/.

Supported Services

| Name | Description | | --- | --- | | npm-version | NPM package version. | | bower-version | Bower package version. | | travis | State of the Travis build. | | david | David state of the dependencies. | | david-dev | David state of the development dependencies. | | waffle | Issues ready on Waffle board. | | gitter | Join Gitter chat. | | coveralls | Coveralls. | | codeclimate-gpa | Code Climate GPA. | | codeclimate-coverage | Code Climate test coverage. | | appveyor | AppVeyor status. |

What service are you missing? Raise an issue.

Example

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

Generates:

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

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | name | Name of the service. | N/A |

Print Date

{"gitdown": "date"}

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

Example

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

Generates:

1545089096
2018

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | format | Moment format. | X (UNIX timestamp) |

Gitinfo

{"gitdown": "gitinfo"}

Gitinfo gets info about the local GitHub repository.

Example

{"gitdown": "gitinfo", "name": "username"}
{"gitdown": "gitinfo", "name": "name"}
{"gitdown": "gitinfo", "name": "url"}
{"gitdown": "gitinfo", "name": "branch"}
gnidan
gitdown
https://github.com/gnidan/gitdown
scope

Supported Properties

|Name|Description| |---|---| |username|Username of the repository author.| |name|Repository name.| |url|Repository URL.| |branch|Current branch name.|

JSON Configuration

| Name | Description | Default | | --- | --- | --- | | name | Name of the property. | N/A |

Parser Configuration

| Name | Description | Default | | --- | --- | --- | | gitinfo.gitPath | Path to the .git/ directory or a descendant. | __dirname of the script constructing an instance of Gitdown. |

Recipes

Automating Gitdown

Use Husky to automate generation of README.md and committing it to the version control.

"husky": {
  "hooks": {
    "post-commit": "npm run create-readme && git add README.md && git commit -m 'docs: generate docs' --no-verify",
    "pre-commit": "npm run lint && npm run test && npm run build"
  }
}

Where create-readme is your script to generate README.md, e.g.

"scripts": {
  "create-readme": "gitdown ./.README/README.md --output-file ./README.md",
}