Newman's Personal Motorcade
Miss any of our Open RFC calls?Watch the recordings here! »

@quilicicf/markdown-formatter

3.0.0 • Public • Published

markdown-formatter

A markdown formatter intended for writing specifications

Badges and stuff

Info

License tested with jest

Status

Dependencies freshness Known Vulnerabilities Build status

What it is

This formatter takes a markdown file and applies formatting rules to it.

It can also add a ToC in your document.

It is supposed to be used as a formatter for your markdown. Feel free to plug it to your favorite editor.

There are already plugins for Atom and VSCode.

Note: obviously, this doc is formatted with markdown-formatter. Look at npm script format:readme in package.json.

Use it

CLI

$ npm install -g @quilicicf/markdown-formatter
$ markdown-format --content '**Toto**'
> __Toto__
$

CLI options

Option Alias Type Description
content c String Markdown string to format. Mutually exclusive with file
file f String File path to Markdown file to format. Mutually exclusive with content
output-file o String When specified, creates/overwrites a file with the formatted markdown
replace r Boolean Replaces the file content in-place. Mutually exclusive with content & output-file. Only valid when file is set
use-configuration u String File path to the configuration file for markdown-formatter. The configuration file can define markdownFormatterOptions, stringifyOptions or both (example). More information on options.

API

Both methods return a VFile.

formatFromString

Usage
const { formatFromString } = require('@quilicicf/markdown-formatter');
 
const main = async () => {
  const { contents, messages } = await formatFromString(
    '**Toto**', // Markdown string
    { watermark: 'top' }, // Markdown-formatter options
    { gfm: false }, // Stringify options
  );
  process.stdout.write(`Formatted from string:\n${contents}\n`);
  process.stdout.write(`With messages:\n${messages}\n`);
}
 
main();
formatFromString options
Parameter Type Description
content String Markdown string to format
markdownFormatterOptions Object The markdownFormatterOptions. Set to {} or omit to use defaults.
stringifyOptions Object The stringifyOptions. Set to {} or omit to use defaults.

formatFromFile

Usage
const { formatFromFile } = require('@quilicicf/markdown-formatter');
 
const main = async () => {
  const { contents } = await formatFromFile(
    filePath, // Markdown string
    { watermark: 'top' }, // Markdown-formatter options
    { gfm: false }, // Stringify options
  );
  process.stdout.write(`Formatted from file:\n${contents}\n`);
}
 
main();
formatFromFile options
Parameter Type Description
filePath String Path to markdown file to format
markdownFormatterOptions Object The markdownFormatterOptions. Set to {} or omit to use defaults.
stringifyOptions Object The stringifyOptions. Set to {} or omit to use defaults.

Options

This tool accepts two different configuration objects, markdownFormatterOptions and stringifyOptions.

The first one configures the plugin itself, the second one configures the formatting feature only and is purely mapped to the options of the underlying module used: remark-stringify.

You can pass values for these two using the CLI and API.

markdownFormatterOptions

The markdownFormatterOptions structure is defined by this plugin in the TypeScript module declaration (in the interface MarkdownFormatterOptions).

The default values for the fields are in the constants file (in property DEFAULT_MARKDOWN_FORMATTER_OPTIONS).

Each field present in the configuration you pass to markdown-formatter will overwrite the default value for this field.

Examples:

  • pass {} to use all the default values
  • pass { watermark: 'top' } to overwrite the property watermark and use defaults for other properties

stringifyOptions

The stringifyOptions structure is defined by the dependency remark-stringify.

The default values for the fields are in the constants file (in property DEFAULT_STRINGIFY_OPTIONS). Any field not present in this repository's defaults will use remark-stringify's default value instead.

Each field present in the configuration you pass to markdown-formatter will overwrite the default value for this field.

Examples:

  • pass {} to use all the default values
  • pass { gfm: false } to overwrite the property gfm and use defaults for other properties

How it works

It uses remark to parse the markdown and generate an AST.

Then remark-stringify to re-generate the string from the AST and apply the formatting rules to it.

Additionally, mdast-util-toc is used to generate a ToC.

ToC generation

The ToC is inserted in the HTML comments described below and can be configured with the options also examplified.

<!-- TOC START min:2 max:4 -->
 
> Anything between those two HTML comments will be replaced by the auto-generated ToC.
> The TOC parameters are optional, see default values in the table below
 
<!-- TOC END -->

ToC parameters

Name Accepted values Default value Description
min Any number between 1 & 6 2 The minimum level of headings that should appear in the ToC
max Any number between 1 & 6 4 The maximum level of headings that should appear in the ToC

Roadmap

  • Create atom formatter
  • Create IntelliJ formatter
  • Add dot graphs capabilities?

Install

npm i @quilicicf/markdown-formatter

DownloadsWeekly Downloads

6

Version

3.0.0

License

Apache-2.0

Unpacked Size

51.2 kB

Total Files

44

Last publish

Collaborators

  • avatar