Rules

markright has formatters, which rewrite lines, and linters, which only report. Every one has a name; an issue prints it, and the configuration turns it on or off.

Where CommonMark decides how Markdown is read, every rule follows it. Where it leaves a choice, such as which of -, * and + marks a list item, a formatter applies the most common convention, so documents look alike across repositories.

Commands#

check and fmt take the documents under the current directory, or only the documents and directories given after them, such as markright check README.md docs; run from the root, markright check and markright check . take every document. Paths are relative to the current directory and must lie in the repository. Every document is still read, so links and anchors into the others resolve, but only the ones given are reported and rewritten. A file that is not one of the repository's documents, such as one Git ignores, stops the command.

The root of the repository is the nearest directory, from the current one up, that holds a configuration file or .git; --root names it instead, and then check and fmt without paths take the whole of it. --config names another configuration file. A configuration or repository that cannot be read, a path that cannot be taken, or a run interrupted with Ctrl+C, ends any command with exit code 2.

Formatters#

They run in that order, on prose only: code blocks and protected spans stay as written. hard-tabs runs first, so the others see spaces; heading-style, block-spacing, blank-lines and final-newline remove or add lines, so they run last. check reports what each formatter would change against the file as it is, so every line number points into the file. A formatter changes how a document is written, never what it renders to, except where its description says so: arrows turns arrows into their characters, bare-urls makes a URL a link, link-spacing drops spaces at the edges of a link's text, and trailing-whitespace drops a line break written as two spaces.

• arrows turns any run of dashes ending in > or starting with < into one arrow, so --> becomes → as well.
• tables pads cells by display width and keeps each column's alignment: :-- pads on the right, --: on the left, :-: on both sides. A block counts as a table only when its second row is a separator, so a paragraph that starts with | stays as it is.
• list-marker uses -, or * or + when formatters.settings.list-marker.marker chooses it, as Configuration: Settings shows. It leaves a list alone when another list stands right before or after it: there, the different marker is what keeps the two lists apart, and changing it would merge them.
• tables leaves a table alone when a row has more cells than the header, since padding the header would add a column; table-columns reports it instead.
• blank-lines keeps blank lines inside code and HTML blocks, where they are content; elsewhere Markdown renders several blank lines as one.
• final-newline removes blank lines at the end of the file and makes it end with one newline.
• hard-tabs counts columns from the start of the line, as an editor shows them, and leaves tabs in code, inline code included.
• heading-spacing, heading-style and block-spacing change only headings and blocks at the top of a document, outside lists and blockquotes, where moving a line could move it into or out of its container. heading-spacing keeps a # that ends the text, as in C#.
• list-marker-space changes only items of one line, and leaves five spaces or more, which start a code block inside the item. ordered-list-numbers keeps the first number, where the list starts, and leaves an item of more than one line whose new number would be longer or shorter, since its text would move from under its other lines. formatters.settings.ordered-list-numbers.numbering chooses increasing, the default, or same.
• emphasis-marker writes * and **, or _ and __ when its setting chooses them; emphasis that touches a letter or a digit keeps *, since _ does not mark emphasis inside a word.
• fence-marker makes a fence longer when the code holds a line that the new fence would otherwise close on, and leaves a block that is never closed, or a backtick fence whose info string would hold a backtick.
• horizontal-rule leaves a rule right under a line of text, or on the first line, as written when its style is ---: there --- would underline the text into a heading, or open front matter.
• code-span-spacing removes a space only when the code has one on each side, which a renderer drops anyway; a space on one side is part of the code, as in 9., and stays. Code that starts or ends with a backtick keeps its spaces, as in ` for a backtick, and so does a span written over more than one line.
• table-pipes runs before tables, which aligns only rows that start with |, and leaves a table in a blockquote alone. A | escaped as \| at the end of a row is text, so the row still gets one.
• bare-urls finds a URL as GFM does, without the punctuation that ends its sentence, and leaves URLs in links, code and HTML alone.

Linters#

Linters see a document as it is after the formatters, and skip code blocks.

• links and anchors resolve the target relative to the document, and a fragment against the target's headings: Anchors. A link that climbs above the root is an issue even when the file exists, since it breaks wherever the repository is viewed on its own. A reference link, [text][label] or [label][], is checked through its definition, [label]: target, and a label with no definition in the document is an issue, since it renders as plain text. A link with an empty target, [text](), or with no content at all, [](target), is an issue too. External links, mailto: and links inside inline code are not followed.

• A link is found wherever a paragraph has it, also when its text wraps onto the next line, and its issue is reported on the line its target starts on. Brackets inside the text and balanced parentheses inside the target belong to the link, a target in <...> may contain spaces, backslash escapes and entities in a target are resolved as CommonMark resolves them, and a target is percent-decoded and loses its ?query before the file is looked up, so my%20file.md finds my file.md.

• A reference definition is what CommonMark takes for one: it starts a block, so a line that looks like a definition inside a paragraph is text, and when a label is defined twice the first definition wins and the second is ignored, as a renderer ignores it.

• alerts expects the form below; anything else in the tag, or text right after it, is an issue.

  > [!WARNING]
  >
  > The text.

• blockquotes reports a lazy line: one without > that Markdown still joins to the paragraph of the quote above. A line that starts a block of its own, such as a heading or a list, ends the quote and is not reported.

• fence-language reports a fenced block with no info string; text names plain text, which renders without highlighting.

• heading-increment lets a heading go back up any number of levels, but down only one, so ## after #### is fine and #### after ## is not.

• image-alt reports an image whose alternative text is empty, also inside a link, as in a badge.

• table-columns reports a row with more cells than the header: the extra cells are not rendered. A row with fewer cells renders with empty ones, and tables pads it.

• unused-definitions reports a definition, [label]: target, that no reference link uses: [text][label], [label][] or [label].

• line-length counts characters, and leaves out table rows, badges, lines that start with HTML and lines holding a URL of 60 characters or more, none of which can be wrapped.

• first-heading lets front matter and HTML, such as badges, come before the title. single-title reports every top-level heading after the first.

• heading-punctuation lets a heading end with ?, as a question that names a section of answers.

• list-indent compares each item with the first of its list, and is satisfied when either the marker or the text starts at the same column, so numbers aligned on the right, 9. over 10., are fine.

• duplicate-definitions reports every definition of a label after the first, which a renderer ignores, so a link through that label leads where the first one points.

• duplicate-headings compares headings of one section: those with the same nearest heading above them at a lower level. Two ## Setup under different chapters are fine.

• heading-without-space reports a line that starts with # and no space, which CommonMark reads as text.

• emphasis-as-heading reports a paragraph of one line that is all emphasis and does not end with punctuation.

• reversed-links reports (text)[target], unless [target] is a defined reference or the text follows a link.

• blank-line-in-blockquote lets an alert start a blockquote of its own, since two alerts in a row are two quotes.

• code-block-style reports indented code blocks, which cannot name their language.

• link-text compares a link's text, without case and the punctuation around it, with linters.settings.link-text.phrases.

• index and readme-links look at the documents their settings name; when that document is missing, they do not run. index does not ask for documents the linters exclude by path. Which documents exist is decided by document discovery.