markdown-formatter

A markdown formatter intended for writing specifications

• Badges and stuff

  • Info
  • Status

• What it is

• Use it

  • CLI

    • CLI options

  • API

    • formatFromString
    • formatFromFile

  • Options

    • markdownFormatterOptions
    • stringifyOptions

• How it works

• ToC generation

  • ToC parameters

• Roadmap

Badges and stuff

Info

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

• [x] Create atom formatter
• [x] Create IntelliJ formatter
• [ ] Add dot graphs capabilities?