markdown-formatter

A markdown formatter intended for writing specifications

Badges and stuff
- Info
- Status
What it is
Use it
- CLI
  - Options
- API
  - Parameters for formatFromString
  - Parameters for formatFromFile
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 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

CLI

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

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

API

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`);
}

main();

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

Roadmap

Create atom formatter
Create IntelliJ formatter
Add dot graphs capabilities

maoqis/markdown-formatter