mdrefine 0.2.3 → 0.2.5

package/docs/design.md

@@ -31,9 +31,10 @@ The comparison is only as good as the parser's reading:
 - It compares syntax trees, and does not run GitHub's, Forgejo's, Gitea's, or
   Obsidian's renderer. To find documents that renderers read otherwise than the
   parser, the tests format generated documents and CommonMark's examples and
-  compare the HTML of commonmark.js and markdown-it before and after, and a
-  weekly workflow does the same with GitHub's renderer. Each difference found is
-  tracked as an issue.
+  compare the HTML of commonmark.js and markdown-it before and after, a weekly
+  workflow does the same with GitHub's renderer, and a check started by hand
+  compares Obsidian's Live Preview and Reading view, with Obsidian running in
+  Docker. Each difference found is tracked as an issue.
 - It reads the document in its dialect, so it cannot notice that the dialect is
   wrong. In CommonMark a table is an ordinary paragraph, and joining its lines
   changes nothing that CommonMark sees. This is why the tool [assumes a
@@ -146,7 +147,9 @@ Files:
 Syntax:
 
 - Obsidian inline comments that span several paragraphs are not fully read;
-  suppress formatting around them or use comment blocks. Heading nesting paths
+  suppress formatting around them or use comment blocks. A comment on lines of
+  its own directly above text is read as a block before a paragraph, where
+  Obsidian reads one paragraph; both show the same text. Heading nesting paths
   in links, property aliases, PDF subpaths, and the syntax of community plugins
   are not supported.
 - Forgejo's and Gitea's own syntax, such as definition lists, backslash math,

package/docs/dialects.md

@@ -127,8 +127,11 @@ On GitHub, Forgejo, and Gitea, more fragments are valid:
 Both render GitHub Markdown and more. The tool parses their documents as GitHub
 Markdown and protects the rest:
 
-- A paragraph with a definition description (a line starting with `: `) or a
-  display-math line starting with `\[` is not wrapped.
+- A definition description, a line starting with `: ` below its term, holds
+  blocks on Forgejo and Gitea, as a list item does, and so do the lines indented
+  below it: `: 2. Step` is a list there, and a fence starts code. No rule
+  changes the paragraph with such a line or the blocks indented below it. A
+  paragraph with a display-math line starting with `\[` is not wrapped.
 - `\(…\)` math and `[[…]]` shortlinks on one line are kept whole; a pair split
   across lines keeps its paragraph from being wrapped. Emphasis markers inside
   `\(…\)` are not changed, and code spans are not joined where that would put

package/docs/obsidian.md

@@ -52,6 +52,38 @@ paragraph is left as written in the cases that
 are not consistent, or inline syntax that runs from the title into the body. A
 title that is too long is reported by `reportUnbreakable`.
 
+## Where Obsidian reads Markdown its own way
+
+Obsidian's Reading view and Live Preview read some Markdown otherwise than
+CommonMark, and otherwise than each other. Where formatting would change what a
+note shows there, the tool keeps the text as written:
+
+- A paragraph, heading, or table cell with a backtick that no run of backticks
+  closes, such as ``a ` b``, also in a highlight, an inline comment, or the text
+  of a link or image. Live Preview shows the text after it as code, at least to
+  the end of its line, and Reading view pairs a run of two or more backticks
+  with a later, shorter run. No rule changes such a block. A backtick in math or
+  a wikilink does not count.
+- The blocks below a run of three or more backticks that nothing closes. Live
+  Preview shows them as code too, across blank lines and out of a list item, up
+  to a run of the same length outside an indented code block, a fenced code
+  block, or a list item. No rule changes them, nor a table that holds such a
+  run.
+- A paragraph with a later line that starts a list item in Obsidian, where
+  CommonMark reads more of the paragraph: Live Preview starts a list at a number
+  other than 1 with text after it, as in `3. Step`, except in a block quote, and
+  Reading view at an empty item, `*`, `+`, `- `, or `1.`, as in `Text` and `- `
+  below it, which the parser reads as a heading. No rule changes such a
+  paragraph, nor the blocks below it that start further right than the marker,
+  which Live Preview reads inside the item, or the block after those.
+- A line of blank space that holds a tab, which Reading view reads as more of
+  the paragraph above it, and one directly below an HTML block such as
+  `<div>…</div>`, which continues the block. The blocks below such a line are
+  more of the HTML block too, up to an empty line, and Reading view shows them
+  as written. No rule empties the line or changes those blocks. A comment, and
+  the other HTML blocks that end at their own end marker, such as `<pre>`, do
+  not continue.
+
 ## Vaults inside a larger workspace
 
 A note belongs to the nearest vault at or above its directory, wherever the

package/docs/quick-start.md

@@ -6,7 +6,7 @@ mdrefine needs Node.js 22.12 or newer. Install the package in the project that
 holds your documents:
 
 ```sh
-npm install --save-dev --save-exact mdrefine@0.2.3
+npm install --save-dev --save-exact mdrefine@0.2.5
 npx --no-install mdtools --help
 ```
 

package/docs/rules.md

@@ -290,7 +290,8 @@ only when the new destination leads to the same file and fragment.
 - `extension`: whether the path to a Markdown file ends in `.md`. `omit` applies
   in the Obsidian dialect only.
 - `leadingDot`: with `relative`, start a path with `./` when it does not start
-  with `.`.
+  with `./` or `../`, also a path to a name that starts with a dot, such as
+  `./.gitignore`.
 
 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
@@ -447,7 +448,9 @@ Options: none.
 
 Writes the type of an Obsidian callout in lowercase, custom types included. The
 title and the body are left as written, and so is a marker written with an
-escape or a character reference, such as `\[!TIP]`.
+escape or a character reference, such as `\[!TIP]`, and one that Obsidian shows
+as text because more than one space or a tab separates it from the quote's `>`,
+as in `>  [!TIP]`.
 
 Before:
 
@@ -611,7 +614,9 @@ lines at the start and at the end of a document. The option `maximum` is an
 integer of at least 1; the default is 1. The line break that ends the last line
 stays; [`style/final-newline`](#stylefinal-newline) adds it where it is missing.
 Inside a block quote, a line of only `>` markers is a blank line, and repeated
-ones are removed the same way.
+ones are removed the same way. In the Obsidian dialect, a line of blank space
+that holds a tab, or that lies directly below an HTML block, is not blank:
+Obsidian's Reading view reads it as more of the paragraph or block above it.
 
 Before, with three blank lines between the blocks and two at the end:
 
@@ -783,6 +788,12 @@ so are the exceptions of [Forgejo and Gitea](dialects.md#forgejo-and-gitea):
   `x~~_b_~~`, which GitHub reads as inside a word.
 - Text whose markers CommonMark pairs otherwise than the parser, as in
   `xab***a* a*y`: GitHub follows CommonMark, so the parser misread the text.
+- In Obsidian, a paragraph, heading, or table cell whose text holds a `*` or `_`
+  that is not a marker, as in `snake_case` or `5 * 3`. Obsidian's Reading view
+  pairs such a character with a later one, so `snake_case and _em_` shows
+  `case and _em` as emphasis, and `snake_case and *em*` is right only with the
+  `*` kept. Escaped characters and those in code, math, or wikilinks do not
+  count.
 
 ## `style/final-newline`
 
@@ -1179,14 +1190,16 @@ Line one\
 line two
 ```
 
-Blank space is left as written where it is content: in code blocks, except on
-their fence lines, and in HTML, math, front matter, Obsidian comments, code
-spans, and link titles and labels that span lines. With `"backslash"`, a break
-stays as spaces where a backslash would change what the line says: after another
-backslash, after a literal autolink such as `www.example.com`, which would take
-the backslash into its address, on the title line of an alert or callout, in a
-paragraph that starts like a link reference definition (`[label]:`), and on
-Forgejo and Gitea inside `\(...\)` math.
+Blank space is left as written where it is content: on a line of blank space
+that holds a tab or lies directly below an HTML block in the Obsidian dialect,
+which Obsidian's Reading view reads as more of the block above it; in code
+blocks, except on their fence lines, and in HTML, math, front matter, Obsidian
+comments, code spans, and link titles and labels that span lines. With
+`"backslash"`, a break stays as spaces where a backslash would change what the
+line says: after another backslash, after a literal autolink such as
+`www.example.com`, which would take the backslash into its address, on the title
+line of an alert or callout, in a paragraph that starts like a link reference
+definition (`[label]:`), and on Forgejo and Gitea inside `\(...\)` math.
 
 ## `style/wrap`
 
@@ -1204,9 +1217,10 @@ onto one, without the spaces and tabs that start its next line, as renderers
 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.
+text spans lines as its Markdown source. For the same reason, an inline footnote
+(`^[…]`) on one line stays whole there, and a paragraph with one that spans
+lines keeps its lines. 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.3",
+  "version": "0.2.5",
   "description": "Configurable Markdown linting and formatting for CommonMark, GitHub, Forgejo, Gitea, and Obsidian",
   "keywords": [
     "markdown",
@@ -91,6 +91,8 @@
     "docs:preview": "vitepress preview docs",
     "benchmark": "node benchmarks/run.mjs",
     "prebenchmark": "npm run build",
+    "check:obsidian": "run-s build check:obsidian:run",
+    "check:obsidian:run": "node scripts/obsidian-check.mjs",
     "release:prepare": "run-s check release:pack",
     "release:pack": "node scripts/package-smoke.mjs --retain",
     "schema": "run-s build schema:write",