@knight-owl-llc/prettier-plugin-pandoc weekly downloads statistics

@knight-owl-llc/prettier-plugin-pandoc

Format Pandoc Markdown with prettier without changing what Pandoc reads.

The plugin reads a document with @knight-owl-llc/pandoc-parser, a port of Pandoc's Markdown reader. It prints structure from that read and text as the source wrote it, then reads its own output: a block that reads differently prints as written.

Install

npm install --save-dev prettier @knight-owl-llc/prettier-plugin-pandoc

In .prettierrc, for the files Pandoc builds:

{
  "overrides": [
    {
      "files": "manuscript/**/*.md",
      "options": { "plugins": ["@knight-owl-llc/prettier-plugin-pandoc"] }
    }
  ]
}

Markdown GitHub renders, a README or a changelog, belongs on prettier's own parser. The plugin keeps what Pandoc reads, and a CommonMark reader such as GitHub's reads some Markdown differently: to Pandoc, a - item line right after paragraph text continues the paragraph, and the plugin may join the two lines.

What it formats

• One blank line between top-level blocks.
• Paragraphs reflowed, with prettier's emphasis markers.
• Headings in ATX form.
• List markers and reference definitions as prettier writes them.
• Pipe tables aligned.
• Fenced code with a fence fit for its content.
• Block quotes, lists, definition lists, divs and note definitions printed from their structure.

Other blocks print as written, and so does markup Pandoc reads as broken. A fence a paragraph runs into is that paragraph's text, and an unclosed div runs to the document's end; repairing either would change what the document means.

Options

Option	What it does
pandocTabStop	Pandoc's --tab-stop, 4 by default: the columns a tab advances and the indent that makes code. Match the build's.
proseWrap	preserve (the default) keeps line breaks as written; always fills to printWidth; never puts each paragraph on one line.
embeddedLanguageFormatting	auto (the default) reformats a fenced sample tagged with a language prettier formats, such as yaml; off prints it as written.
tabWidth	Pads a list marker toward it, by up to three spaces, so every line of the item starts at one column: - item at 4.

For documents built with pandoc --tab-stop=8, the override's options take "pandocTabStop": 8.

<!-- prettier-ignore --> keeps the next block as written; <!-- prettier-ignore-start --> and <!-- prettier-ignore-end --> keep everything between them.

markdownlint

A few markdownlint rules trip on the plugin's output. A div's content sits against its fences, so a list or code fence there trips MD031 and MD032. Prettier's emphasis, * inside a word and _ elsewhere, trips MD049's default. For the files the plugin formats:

blanks-around-fences: false
blanks-around-lists: false
emphasis-style:
  style: underscore

MD049 still reads a * inside raw TeX, which Pandoc passes to TeX, as emphasis.

With tabWidth above 2, the padded markers trip MD030 and MD007 as well:

list-marker-space: false
ul-indent:
  indent: 4 # the tabWidth

A .markdownlint.yaml in the manuscript's directory holds these for those files alone: markdownlint-cli2 applies one to its own directory.

License

GPL-2.0-or-later: LICENSE, NOTICE.md.