| Github License | Github Issues | Github Release | Github Tags | Travis CI | Waffle | Code Climate |
|---|---|---|---|---|---|---|
 |
 |
 |
 |
 |
 |
 |
| Branch | Codecov | Coveralls | Inch CI | David DM | David DM (dev) |
|---|---|---|---|---|---|
| master |  |
 |
 |
 |
 |
| develop |  |
 |
 |
 |
 |
This modules creates a Markdown presentation from a package.json on CLI or API.
Download node.js at nodejs.org and install it, if you haven't already. Ensure the proper registry setting before npm install:
$ npm config set registry https://registry.npmjs.org/$ npm install pkg2md --global$ npm install pkg2md --saveor as devDependency:
$ npm install pkg2md --save-dev| Type | Link |
|---|---|
| git | https://github.com/deadratfink/pkg2md |
- ajv: Another JSON Schema Validator
- bluebird: Full featured Promises/A+ implementation with exceptionally good performance
- cli: A tool for rapidly building command line apps
- cwd: Easily get the CWD (current working directory) of a project based on package.json, optionally starting from a given path. (Node.js/javascript util)
- flat: Take a nested Javascript object and flatten it, or unflatten an object with delimited keys
- github-url-to-object: Extract user, repo, and other interesting properties from GitHub URLs
- is-stream: Check if something is a Node.js stream
- json-stringify-safe: Like JSON.stringify, but doesn't blow up on circular refs.
- mkdirp-then: mkdirp as promised
- package.json-schema: JSON Schema for node/npm package.json
- url-join: Join urls and normalize as in path.join.
- codeclimate-test-reporter: Code Climate test reporter client for javascript projects
- codecov: Uploading report to Codecov: https://codecov.io
- coveralls: takes json-cov output into stdin and POSTs to coveralls.io
- doctoc: Generates TOC for markdown files of local git repo.
- fs-extra: fs-extra contains methods that aren't included in the vanilla Node.js fs package. Such as mkdir -p, cp -r, and rm -rf.
- istanbul: Yet another JS code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. Supports all JS coverage use cases including unit tests, server side functional tests
- jsdoc-parse: Jsdoc-annotated source code in, JSON format documentation out.
- jsdoc-to-markdown: jsdoc-annotated source in, markdown API docs out.
- mocha: simple, flexible, fun test framework
- mocha-lcov-reporter: LCOV reporter for Mocha
- object-path: Access deep properties using a path
- package-json-to-readme: Generate a README.md from package.json contents
- winston: A multi-transport async logging library for Node.js
Test execution:
$ npm install
$ npm test
| Role | Name | |
|---|---|---|
| Author | Jens Krefeldt | [email protected] |
api, cli, convert, markdown, md, package, package.json, pkg, pkg-to-md, pkg2md, pkgtomd, promise, readme, readme.md, transform
| Property (flattened) | Value | Applicable in scripts Section |
|---|---|---|
test.istanbul.report |
lcovonly | $npm_package_config_test_istanbul_report |
test.mocha.reporter |
spec | $npm_package_config_test_mocha_reporter |
| Run Command | Script Executed |
|---|---|
$ npm run docs |
cat docs/LOGO.md > README.md && cat docs/BADGES.md >> README.md && cat docs/TOC.md >> README.md && ./pkg2md -b -c -o -k -s -r -m -i && cat docs/USAGE.md >> README.md && doctoc README.md --github --title '# TOC' --maxlevel 2 |
$ npm run test |
istanbul cover _mocha --report $npm_package_config_test_istanbul_report -- -R $npm_package_config_test_mocha_reporter ./test/test-*.js |
$ npm run test:html |
istanbul cover _mocha --report html -- -R $npm_package_config_test_mocha_reporter ./test/test-*.js |
$ npm run wiki |
jsdoc2md -P lib/*.js index.js > docs/API.md && doctoc docs/API.md --github --title '### TOC' --maxlevel 2 && cat docs/API.md > '../pkg2md.wiki/API-v1.md'&& cat docs/CONTRIBUTING.md > ../pkg2md.wiki/Contributing.md && cat docs/CHANGELOG.md > ../pkg2md.wiki/Changelog.md && doctoc ../pkg2md.wiki/Changelog.md --github --title '### TOC' --maxlevel 3 |
- ./index.js
$ pkg2md⇒ ./pkg2md
SEE LICENSE IN LICENSE.md
Why this module? Module package-json-to-readme is a nice tool to generate a README from scratch. Unfortunately, for me it lacks some options and does not cover all of package.json I needed. Therefore, I decided to write my own module which is more flexible (in terms of options) and covers also other sections in the package.json, concentrating on the standard package info only (no badges, no example files).
The module can be used on CLI or as API (the latter is fully Promise based).
Since the module can be used in two different ways, do an installation as follows:
- CLI: install globally via
-goption - API: install locally
Both usage types are described in more detail in the following sections.
The module can easily be used by API but a in most cases a usual scenario could be the usage on CLI. You can simply refer to the API Reference section for API access use case (these contains some examples how to use) it.
The following snippet gives an example how to
use it in scripts section of a package.json of your particular project,
here as docs target generating the README.md:
{
...
"scripts" : {
"docs": "pkg2md <OPTIONS...>"
},
...
}Simply run:
$ npm run docs
and pkg2md generates the README.md (or any other MD file if specified
as file argument) or just appends to an existing one (which is autodetected),
to overwrite simply use the -f (--force) option on command).
Of course, the pkg2md command can be pre- or appended by other commands
manipulating the README.md. Let's say after generation, we we want to
insert a a TOC in front of the generated content using the nice module
doctoc, this can be easily achieved
as follows:
{
...
"scripts" : {
"docs": "cat docs/TOC.md > README.md && pkg2md <OPTIONS...> && doctoc README.md --github --title '# TOC' --maxlevel 2"
},
...
}NOTE: the file ./docs/TOC.md contains the comments used by doctoc
to locate the position where to insert the TOC:
<!-- START doctoc -->
<!-- END doctoc -->
The two newlines are there by intention to create some distance to the follow-up section.
TODO!!!
None known yet.
The CLI provides the pkg2md command (actually, this might require the use of options).
After the global installation you can access the command options
with the usual help command as follows:
$ pkg2md --help
The --help option prints an overview about all available CLI properties:
$ pkg2md --help
TODO!!!
These are more formally defined in the following table:
TODO!!!
IMPORTANT NOTE: when using this feature then any subsequent execution which uses the same target/file name, will overwrite the original source or target created beforehand!
By default this feature is not enabled to prevent you from accidentally overwriting your input source.
$ pkg2md -f
Of course, leaving out the -f switch simply appends the generated content to the input file.
It is usual that you use an own logger in your application. This module
supports you by letting you inject your logger as constructor argument to the
following objects:
PkgReaderMdPkgToMdMdWriter
If you do not provide one, then the default logger is console.
var logger = ...;
var reader = new PkgReader(logger);
var markdown = new Md(logger);
var controlFlow = new PkgToMd(logger);
var writer = new MdWriter(logger);At least, the passed logger object has to support the following functions:
function info(msg)
function debug(msg)
function trace(msg)
function error(err|msg)Anyway, there are some fallbacks if a level is not supported:
- DEBUG ⇒ INFO
- TRACE ⇒ DEBUG
For more details on how to use the API, please refer to the API Reference wiki which describes the full API and provides more examples.
Pull requests and stars are always welcome. Anybody is invited to take part into this project. For bugs and feature requests, please create an issue. See the wiki Contributing section for more details about conventions.
The complete changelog is listed in the wiki Changelog section.