kgryte/markdown-to-restructuredtext

Convert Markdown to reStructuredText.

JavaScriptMIT

Markdown to reStructuredText

Convert Markdown to reStructuredText.

Installation

$ npm install markdown-to-restructuredtext

Installation prerequisites:

pandoc

Usage

var md2rst = require( 'markdown-to-restructuredtext' );

md2rst( [dest,] src[, opts], clbk )

Asynchronously converts a Markdown file to reStructuredText.

md2rst( './README.rst', './README.md', done );

function done( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'converted' );
}

The destination and source file paths may be either absolute or relative. If relative, a file path is resolved relative to the current working directory.

var inFile = '/path/to/my/file.md';
var outFile = './../output.rst';

process.chdir( '/some/directory' );

md2rst( outFile, inFile, done );

function done( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'output file: /some/output.rst' );
}

If not provided a destination file path, the function returns a reStructuredText string.

md2rst( './README.md', done );

function done( error, rst ) {
	if ( error ) {
		throw error;
	}
	console.log( rst );
}

The function accepts the following options:

flavor: Markdown flavor; e.g., 'github'. For supported flavors, see pandoc. Default: ''.

By default, the function assumes standard Markdown. To convert from a different Markdown flavor, set the flavor option.

var opts = {
	'flavor': 'github' // GFM
};

md2rst( './README.rst', './README.md', opts, done );

function done( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'converted from Github Flavored Markdown' );
}

md2rst.sync( [dest,] src[, opts] )

Synchronously converts a Markdown file to reStructuredText.

// Write to an output file:
md2rst.sync( './README.rst', './README.md' );

// Return a reStructuredText string:
var rst = md2rst.sync( './README.md' );
// returns <string>

The function accepts the same options as md2rst().

md2rst.fromString( [dest,] str[, opts], clbk )

Asynchronously converts a Markdown string to reStructuredText.

var readFile = require( 'utils-fs-read-file' ).sync;
var data = readFile( './README.md', {'encoding':'utf8'} );

md2rst.fromString( './README.rst', data, done );

function done( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'converted' );
}

If not provided a destination file path, the function returns a reStructuredText string.

md2rst.fromString( data, done );

function done( error, rst ) {
	if ( error ) {
		throw error;
	}
	console.log( rst );
}

The function accepts the same options as md2rst().

md2rst.fromStringSync( [dest,] str[, opts] )

Synchronously converts a Markdown string to reStructuredText.

var readFile = require( 'utils-fs-read-file' ).sync;
var data = readFile( './README.md', {'encoding':'utf8'} );

// Write to an output file:
md2rst.fromStringSync( './README.rst', data );

// Return a reStructuredText string:
var rst = md2rst.fromStringSync( data );
// returns <string>

The function accepts the same options as md2rst().

md2rst.fromBuffer( [dest,] buffer[, opts], clbk )

Asynchronously converts a Markdown buffer to reStructuredText.

var readFile = require( 'utils-fs-read-file' ).sync;
var data = readFile( './README.md' );

md2rst.fromBuffer( './README.rst', data, done );

function done( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'converted' );
}

If not provided a destination file path, the function returns a reStructuredText string.

md2rst.fromBuffer( data, done );

function done( error, rst ) {
	if ( error ) {
		throw error;
	}
	console.log( rst );
}

The function accepts the same options as md2rst().

md2rst.fromBufferSync( [dest,] buffer[, opts] )

Synchronously converts a Markdown buffer to reStructuredText.

var readFile = require( 'utils-fs-read-file' ).sync;
var data = readFile( './README.md' );

// Write to an output file:
md2rst.fromBufferSync( './README.rst', data );

// Return a reStructuredText string:
var rst = md2rst.fromBufferSync( data );
// returns <string>

The function accepts the same options as md2rst().

Examples

var path = require( 'path' );
var md2rst = require( 'markdown-to-restructuredtext' );

var inFile = path.resolve( __dirname, '../../README.md' );
var outFile = path.join( __dirname, './README.rst' );

var opts = {
	'flavor': 'github'
};

md2rst( inFile, opts, onResults );

function onResults( error, rst ) {
	if ( error ) {
		throw error;
	}
	console.log( rst );
}

md2rst( outFile, inFile, opts, onFile );

function onFile( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'Input file: %s', inFile );
	console.log( 'Output file: %s', outFile );
}

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/file_async/index.js

CLI

Installation

To use the module as a general utility, install the module globally

$ npm install -g markdown-to-restructuredtext

Usage

Usage: md2rst [options] inFile

Options:

  -h,  --help               Print this message.
  -V,  --version            Print the package version.
       --flavor flavor      Markdown flavor. Default: (none).
  -o,  --output file        Output file path.

Notes

If not provided an output file path, the generated reStructuredText is written to stdout.

Examples

$ DEBUG=* md2rst --flavor=github -o ./README.rst ./README.md

For local installations, modify the command to point to the local installation directory; e.g.,

$ DEBUG=* ./node_modules/.bin/md2rst --flavor=github -o ./README.rst ./README.md

Or, if you have cloned this repository and run npm install, modify the command to point to the executable; e.g.,

$ DEBUG=* node ./bin/cli --flavor=github -o ./README.rst ./README.md

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

Copyright

Copyright © 2016. Athan Reines.