Nonlinear Performance Magnification
Get unlimited public & private packages + package-based permissions with npm Pro.Get started »


2.0.2 • Public • Published


A markdown formatter intended for writing specifications

Badges and stuff


License tested with jest


Dependency Status Known Vulnerabilities

What it is

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

It can also add a ToC in you document, see documentation below.

It is supposed to be used as a formatter for your markdown. Feel free to plug it to your favorite editor. I'll do Atom and IntelliJ because they are my editors of choice.

Note: obviously, this doc is formatted by dog-fooding the package. Look at npm script format:readme in package.json.

Use it


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


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


const { formatFromFile, formatFromString } = require('@quilicicf/markdown-formatter');
const main = async () => {
  const formattedFromString = await formatFromString('**Toto**', 2);
  process.stdout.write(`Formatted from string:\n${formattedFromString.contents}\n`);
  process.stdout.write(`With messages:\n${formattedFromString.messages}\n`);
  process.stdout.write(`New cursor offset:\n${formattedFromString.newCursorOffset}\n`);
  process.stdout.write(`New cursor position:\n${formattedFromString.newCursorPosition}\n`);
  const formattedFromFile = await formatFromFile(filePath);
  process.stdout.write(`Formatted from file:\n${formattedFromFile.contents}\n`);

Parameters for formatFromString

Parameter Type Description
content String Markdown string to format
cursorOffset Integer Optional the cursor offset from document start

Parameters for formatFromFile

Parameter Type Description
filePath String Path to markdown file to format
cursorOffset Integer Optional the cursor offset from document start

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.
<!-- 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


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


npm i @quilicicf/markdown-formatter

DownloadsWeekly Downloads






Unpacked Size

48.2 kB

Total Files


Last publish


  • avatar