mdrefine 0.2.1 → 0.2.3

package/docs/rules.md

@@ -4,7 +4,8 @@ A rule is either a **style** rule or a **problem** rule. A style rule checks how
 something is written and proposes an edit, which `format` applies and `lint`
 reports. A problem rule reports a defect that has no single correct repair, and
 never edits. `format` applies an edit only when the document still means the
-same afterwards; see [how it works](design.md#safety-model).
+same afterwards, and never in text that the parser reads where renderers read a
+list; see [how it works](design.md#safety-model).
 
 Enable and configure rules under `rules` in the
 [configuration](configuration.md#rules-and-severity). `npx mdtools rules` lists
@@ -165,7 +166,9 @@ Writes the type of a GitHub alert in capitals. The renderers accept any case for
 the five types `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`, and their
 documentation spells them in capitals. Other types are not alerts there and are
 left as written, and so is a marker written with an escape or a character
-reference, such as `\[!note]`.
+reference, such as `\[!note]`. So is a marker that GitHub shows as text: one in
+a block quote inside another quote or a list, one followed by text on its line,
+and one with nothing below it in the quote.
 
 Before:
 
@@ -242,7 +245,9 @@ label shows its target as text, and a note embed is not the same thing as a
 Markdown image. A new wikilink decodes percent escapes, because Obsidian takes
 its text as the note's name: `[x](My%20Note.md)` becomes `[[My Note.md|x]]`. A
 destination that does not decode, or whose name would hold `|`, `[`, `]`, `#`,
-or `^`, stays as written.
+or `^`, stays as written. In a table cell, a `|` that the rule writes, between a
+new wikilink's target and label or in a new Markdown label, is escaped as `\|`,
+because one that is not escaped ends the cell.
 
 With `"style": "markdown"`, before:
 
@@ -290,11 +295,14 @@ only when the new destination leads to the same file and fragment.
 A relative path also gets `./` when it would otherwise name a different file at
 the vault's root. A destination that already has the configured spelling keeps
 its percent-encoding; a new path encodes `%` and `#`, so that it names the same
-file. Absolute filesystem paths are never written. These are left as written: a
-wikilink without a label, whose target is also its visible text; reference
-definitions, which are checked but not rewritten; autolinks; and links whose
-target is uncertain because a directory could not be read or the workspace root
-is only part of a vault (see [Obsidian
+file, and in a table cell writes a `|` in a name as `\|`, because one that is
+not escaped ends the cell. In a wikilink only the destination changes: the `|`
+or `\|` after it, the label, and an embed's size stay as written. Absolute
+filesystem paths are never written. These are left as written: a wikilink
+without a label, whose target is also its visible text; reference definitions,
+which are checked but not rewritten; autolinks; and links whose target is
+uncertain because a directory could not be read or the workspace root is only
+part of a vault (see [Obsidian
 vaults](obsidian.md#a-workspace-root-inside-a-vault)).
 
 With `{ "style": "relative", "leadingDot": true }` in `README.md`, before:
@@ -674,7 +682,9 @@ or what a comment applies to:
   blocks of a list item makes the list loose, which changes how it renders.
 - Front matter and the block below it.
 - A list that ends inside an HTML comment or another HTML block without its end
-  marker, which would take the blank line in.
+  marker, which would take the blank line in. The same goes for a list whose
+  last item ends in a fenced code block without its closing fence: renderers put
+  the blank line into the code, although the parser does not.
 - A heading or list directly below an HTML comment or below a
   `mdtools-disable-next-line` directive, which apply to the line below them.
 - The line that opens a callout or alert, such as `> [!NOTE]`, and the block
@@ -682,10 +692,15 @@ or what a comment applies to:
 - In the Obsidian dialect, a block identifier on a line of its own (`^id`)
   directly below a heading or list, which Obsidian may attach to the block
   above.
-- Directly below text or a link reference definition: a list or quote whose
-  first line continues with another list marker, as in `- 2. Step` or `- -`, and
-  a heading underlined with `===` or `---`. The parser can read such a line
-  differently there than below a blank line.
+- Directly below text or a link reference definition: a heading underlined with
+  `===` or `---`, which the parser can read differently there than below a blank
+  line.
+- Text that the parser reads where renderers read a list, such as `- 2. Step`
+  directly below text: the list or quote that starts with it, the blocks
+  indented below it, and a list after them, which renderers read as part of that
+  list, and text on the line directly below the list item or quote that it ends,
+  which renderers read as more of it (see [how it
+  works](design.md#safety-model)).
 - Directly below a table that ends in a list item or block quote: text whose
   second line is a table delimiter row. The parser reads a table there as text,
   where GitHub reads a table, and a blank line would make it a table for the
@@ -821,9 +836,11 @@ After:
 
 A trailing run of `#` in the text of an underlined heading is escaped, so that
 it is not taken for a closing sequence. Underlined headings of more than one
-line, and those inside lists or block quotes, are left as written. On Forgejo
-and Gitea, a closing sequence after an attribute block such as `{#id}` stays,
-because Gitea before 1.26 reads the block only when the sequence follows it.
+line, those inside lists or block quotes, and one directly below TOML front
+matter, whose lines renderers without TOML front matter read as part of the
+heading, are left as written. On Forgejo and Gitea, a closing sequence after an
+attribute block such as `{#id}` stays, because Gitea before 1.26 reads the block
+only when the sequence follows it.
 
 With `setext`, a `#` heading is underlined only where its text can stand on a
 line of its own as the same heading: at the start of a line of the document, not
@@ -859,6 +876,9 @@ joined line would read differently:
   marker, which holds an Obsidian callout's title.
 - Where the joined span needs a different number of backticks than it has, and
   an earlier run of that many in the same paragraph would pair with them.
+- Where a line inside the span ends with a backslash: where its backticks do not
+  pair, as on GitHub after an unpaired longer run, that backslash is a hard line
+  break. `style/wrap` keeps such a paragraph as written too.
 
 Before:
 
@@ -941,6 +961,17 @@ These are left as written:
   another block once inside the item.
 - A list with a tab in an item's indentation, such as one that Obsidian indented
   with tabs.
+- A list directly below TOML front matter that cannot interrupt a paragraph: a
+  numbered list that does not start at 1, or one whose first item starts with a
+  blank line, and the lists that directly follow it. Renderers without TOML
+  front matter read the front matter's lines as a paragraph, which such a list
+  continues as text. `style/list-marker` and `style/ordered-list` leave these
+  lists as written too.
+- A list among the blocks indented below text that the parser reads where
+  renderers read a list, such as `2. Two` after an indented code block, or the
+  list right after them, and the lists next to it (see [how it
+  works](design.md#safety-model)). `style/list-marker` and `style/ordered-list`
+  keep their markers too.
 
 ## `style/list-marker`
 
@@ -963,7 +994,9 @@ A bullet list that directly follows another one is a separate list only because
 its marker differs, so it gets the next marker in the order `-`, `*`, `+`, and
 the list after that the first one again. A list whose new marker would make a
 line read as a thematic break, as `+ - -` would with `-`, keeps its markers, and
-so do the lists next to it.
+so do the lists next to it. So does a list directly below TOML front matter
+whose first item starts with a blank line, as for
+[`style/list-indent`](#stylelist-indent).
 
 Before:
 
@@ -1010,7 +1043,9 @@ number gets wider or narrower, as from `9.` to `10.`, the item's other lines
 move with its text. A list keeps its numbers where that would move a line into
 or out of an item, as for [`style/list-indent`](#stylelist-indent), and where
 the numbers are written with leading zeros, as in `01.`, or would need more than
-nine digits.
+nine digits. A list directly below TOML front matter that does not start at 1,
+or whose first item starts with a blank line, keeps its delimiter and numbers,
+as for `style/list-indent`.
 
 Before:
 
@@ -1105,8 +1140,9 @@ Text.
 A break is left as written where the new marker would change what the document
 means:
 
-- With `---`, directly below a paragraph or a link reference definition, which
-  `---` would underline as a heading.
+- With `---`, directly below a paragraph, a link reference definition, or
+  display math, which `---` would underline as a heading; GitHub builds display
+  math from a paragraph.
 - On the line of a list item whose marker is the new marker's character, as in
   `- ***` with `---`: `- ---` is one thematic break, not a list item.
 - At the start of a document, with `---`, which would open front matter if a
@@ -1114,6 +1150,10 @@ means:
   start of front matter.
 - With `---`, at the start of a line below a first line of `---` that no line
   closes, which `---` would close as front matter.
+- Directly below TOML front matter, a break that is or would become `---`,
+  because renderers without TOML front matter read the front matter's lines as a
+  paragraph that `---` underlines as a heading; see the [safety
+  model](design.md#safety-model).
 
 ## `style/trailing-space`
 
@@ -1161,10 +1201,12 @@ span, an image, math, a link's destination, a template tag on one line such as
 `{% data x %}` or `{{ title }}`, and a word longer than the line stay whole and
 can overflow; a code span or an image description written across lines is joined
 onto one, without the spaces and tabs that start its next line, as renderers
-read it. In Obsidian, the text of a link stays whole and is joined onto one line
-too, because Live Preview shows a link whose text spans lines as its Markdown
-source. List markers, block quote markers, and indentation count toward the
-width, a tab up to the next multiple of four columns.
+read it. On a lazy continuation line, which keeps them, such a code span stays
+as written, and so does its paragraph. In Obsidian, the text of a link stays
+whole and is joined onto one line too, because Live Preview shows a link whose
+text spans lines as its Markdown source. List markers, block quote markers, and
+indentation count toward the width, a tab up to the next multiple of four
+columns.
 
 A word that would start a block at the start of a line, such as a list marker,
 `#`, `>`, a run of `-` or `=`, or a table delimiter row such as `|---|`, stays

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdrefine",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Configurable Markdown linting and formatting for CommonMark, GitHub, Forgejo, Gitea, and Obsidian",
   "keywords": [
     "markdown",
@@ -120,10 +120,13 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@types/commonmark": "0.27.10",
     "@types/node": "22.20.5",
     "@types/unist": "3.0.3",
+    "commonmark": "0.31.2",
     "eslint": "10.13.0",
     "fast-check": "4.10.2",
+    "markdown-it": "15.0.3",
     "npm-run-all2": "9.0.3",
     "prettier": "3.9.10",
     "typescript": "6.0.3",