All Projects → gajus → Gitdown

gajus / Gitdown

Licence: other
GitHub markdown preprocessor.

Programming Languages

javascript
184084 projects - #8 most used programming language

Labels

Projects that are alternatives of or similar to Gitdown

Misaka
A Python binding for Hoedown.
Stars: ✭ 404 (-4.72%)
Mutual labels:  markdown
Assemble
Community
Stars: ✭ 3,995 (+842.22%)
Mutual labels:  markdown
Breakdance
It's time for your markup to get down! HTML to markdown converter. Breakdance is a highly pluggable, flexible and easy to use.
Stars: ✭ 418 (-1.42%)
Mutual labels:  markdown
Remark
remark is a popular tool that transforms markdown with plugins. These plugins can inspect and change your markup. You can use remark on the server, the client, CLIs, deno, etc.
Stars: ✭ 4,746 (+1019.34%)
Mutual labels:  markdown
Cleaver
30-second slideshows for hackers
Stars: ✭ 3,927 (+826.18%)
Mutual labels:  markdown
Clean Mark
Convert an article into a clean text
Stars: ✭ 414 (-2.36%)
Mutual labels:  markdown
Crowbook
Converts books written in Markdown to HTML, LaTeX/PDF and EPUB
Stars: ✭ 399 (-5.9%)
Mutual labels:  markdown
Pytablewriter
pytablewriter is a Python library to write a table in various formats: CSV / Elasticsearch / HTML / JavaScript / JSON / LaTeX / LDJSON / LTSV / Markdown / MediaWiki / NumPy / Excel / Pandas / Python / reStructuredText / SQLite / TOML / TSV.
Stars: ✭ 422 (-0.47%)
Mutual labels:  markdown
Pipe
🎷 一款小而美的博客平台,专为程序员设计。
Stars: ✭ 3,898 (+819.34%)
Mutual labels:  markdown
Moeditor
(discontinued) Your all-purpose markdown editor.
Stars: ✭ 4,003 (+844.1%)
Mutual labels:  markdown
Sublime zk
A SublimeText3 package featuring ID based wiki style links, and #tags, intended for zettelkasten method users. Loaded with tons of features like inline image display, sophisticated tag search, note transclusion features, support for note templates, bibliography support, support for multiple panes, etc. to make working in your Zettelkasten a joy 😄.
Stars: ✭ 408 (-3.77%)
Mutual labels:  markdown
Justwrite
一款支持同步滑动预览的跨平台Markdown编辑器
Stars: ✭ 411 (-3.07%)
Mutual labels:  markdown
Ascii Tables
Quickly format table in ASCII. Great for code comments, or Github Markdown!
Stars: ✭ 416 (-1.89%)
Mutual labels:  markdown
Github Profile Readme Generator
🚀 Generate GitHub profile README easily with the latest add-ons like visitors count, GitHub stats, etc using minimal UI.
Stars: ✭ 7,812 (+1742.45%)
Mutual labels:  markdown
Markdown Img Upload
markdown图片实用工具
Stars: ✭ 418 (-1.42%)
Mutual labels:  markdown
Markdowneditor
Lightweight markdown editor written for windows,only one GREEN exe file
Stars: ✭ 403 (-4.95%)
Mutual labels:  markdown
Mdx Docs
📝 Document and develop React components with MDX and Next.js
Stars: ✭ 412 (-2.83%)
Mutual labels:  markdown
Django Markdown Editor
Awesome Django Markdown Editor, supported for Bootstrap & Semantic-UI
Stars: ✭ 423 (-0.24%)
Mutual labels:  markdown
Gatsby Starter Bee
🐝Full Package | Simple | Fresh UI | Blog Template :: Let's start to blogging with gatsby-starter-bee!
Stars: ✭ 416 (-1.89%)
Mutual labels:  markdown
Mdp
A command-line based markdown presentation tool.
Stars: ✭ 4,226 (+896.7%)
Mutual labels:  markdown

GitSpo Mentions 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

a

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.47 KB
2.54 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/gitdown.svg?style=flat-square)](https://www.npmjs.org/package/gitdown)
[![Travis build status](http://img.shields.io/travis/gajus/gitdown/master.svg?style=flat-square)](https://travis-ci.org/gajus/gitdown)
[![Dependency Status](https://img.shields.io/david/gajus/gitdown.svg?style=flat-square)](https://david-dm.org/gajus/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:

1563038327
2019

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

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

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.defaultBranchName Default branch to use when the current branch name cannot be resolved. N/A
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 check if user generated README.md before committing his changes.

"husky": {
  "hooks": {
    "pre-commit": "npm run lint && npm run test && npm run build",
    "pre-push": "gitdown ./.README/README.md --output-file ./README.md --check",
  }
}

--check attributes makes Gitdown check if the target file differes from the source template. If the file differs then the program exits with an error code and message:

Gitdown destination file does not represent the current state of the template.

Do not automate generating and committing documentation: automating commits will result in a noisy commit log.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].