mdrefine 0.2.0-rc.2 → 0.2.0

package/docs/integrations.md

@@ -0,0 +1,144 @@
+# Integrations
+
+## Continuous integration
+
+Two commands check a workspace without writing anything. Each fails with exit
+code `1` when it finds something, and with `2` when it cannot do its job:
+
+```sh
+npx mdtools lint --max-warnings 0
+npx mdtools format --check
+```
+
+The [examples](examples.md#automate-checks) include a complete GitHub Actions
+workflow that runs both on every pull request; copy it to
+`.github/workflows/markdown.yml`. Forgejo Actions, on Codeberg and other Forgejo
+instances, runs the same workflow from `.forgejo/workflows/`: set `runs-on` to a
+label that the instance's runners offer, and check that the actions it uses are
+available there.
+
+## Git hooks
+
+The CLI reads files from the working tree, not the staged content of the index.
+Pass it the files that a commit changes, and never run it with an empty list,
+which would check the whole workspace.
+
+With [lint-staged](https://github.com/lint-staged/lint-staged), which passes the
+staged files that match a pattern, keeps unstaged changes out of the way while
+it runs, and adds what the commands changed to the commit, configure it in
+`package.json`:
+
+```json
+{
+  "lint-staged": {
+    "*.{md,markdown}": [
+      "mdtools format --write --no-warn-ignored",
+      "mdtools lint --max-warnings 0 --no-warn-ignored"
+    ]
+  }
+}
+```
+
+and run `npx lint-staged` from a pre-commit hook, for example through husky.
+Without it, a `.git/hooks/pre-commit` script can lint the Markdown files that
+the commit adds or changes:
+
+```sh
+#!/bin/sh
+git diff --cached --name-only -z --diff-filter=ACMR -- '*.md' '*.markdown' |
+  xargs -0 -r npx mdtools lint --max-warnings 0 --no-warn-ignored --
+```
+
+In both, `--no-warn-ignored` leaves out the
+[warning](cli.md#which-files-are-processed) for a changed file that the tool
+skips, such as one that the configuration's `ignore` patterns match.
+`--diff-filter=ACMR` leaves out deleted files, which would be an error as paths.
+`xargs -r` skips the command when no file changed. `--` keeps a file name that
+starts with `-` from being read as an option. This hook checks each file as it
+is on disk, including changes that are not staged.
+
+## Editors
+
+There is no editor extension or language server. An editor that can format a
+buffer through an external command can run
+`npx mdtools format - --stdin-filepath path/of/the/file.md`, which reads the
+buffer from stdin and prints the formatted text; the path gives the buffer its
+file's configuration, dialect, and link targets. Exit code `1` means that
+findings remain, and the output is still the formatted text; with `2`, keep the
+buffer as it was.
+`npx mdtools lint - --stdin-filepath path/of/the/file.md --json` returns the
+findings with their positions. An editor that formats a selection can use the
+library's [`ranges`](api.md#part-of-a-document). An editor that reads JSON
+Schemas completes and checks the configuration file with the package's
+[schema](configuration.md#json-schema).
+
+## Next to Prettier or markdownlint
+
+Prettier formats Markdown too, and two formatters undo each other's changes.
+Leave Markdown to mdrefine by adding this line to `.prettierignore`:
+
+```text
+**/*.md
+```
+
+markdownlint and mdrefine can run side by side, but rules that overlap can
+disagree, such as markdownlint's emphasis style (MD049) and `style/emphasis`.
+Turn off in one tool what the other covers; the table below lists the overlaps.
+
+## Coming from Prettier or markdownlint
+
+mdrefine is meant to replace these tools for Markdown, but it does not yet cover
+everything they do. This table lists what has a rule today. Where it says "None
+yet", keep the other tool for that check.
+
+| Prettier or markdownlint                                                         | mdrefine                                                                                              |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `proseWrap: "always"` and `printWidth`; MD013 (line length)                      | [`style/wrap`](rules.md#stylewrap), which wraps instead of only reporting                             |
+| `proseWrap: "preserve"`                                                          | Turn `style/wrap` off                                                                                 |
+| `proseWrap: "never"`                                                             | None yet                                                                                              |
+| `_` for emphasis; MD049 (emphasis style)                                         | [`style/emphasis`](rules.md#styleemphasis)                                                            |
+| `**` for strong text; MD050 (strong style)                                       | [`style/strong`](rules.md#stylestrong)                                                                |
+| `#` headings without closing `#`; MD003 (heading style)                          | [`style/heading`](rules.md#styleheading), whose default converts underlined ones, unlike Prettier     |
+| Aligned or compact tables; MD055, MD060 (table style)                            | [`style/table`](rules.md#styletable), for tables outside lists and quotes                             |
+| Blank lines between blocks; MD022, MD032 (blank lines around headings and lists) | [`style/block-spacing`](rules.md#styleblock-spacing), for headings and lists                          |
+| Backtick code fences; MD046, MD048 (code block and fence style)                  | [`style/code-fence`](rules.md#stylecode-fence), which leaves indented code blocks as written          |
+| `---` for thematic breaks; MD035                                                 | [`style/thematic-break`](rules.md#stylethematic-break)                                                |
+| Trailing spaces; MD009                                                           | [`style/trailing-space`](rules.md#styletrailing-space), which keeps hard line breaks                  |
+| Repeated blank lines; MD012                                                      | [`style/blank-lines`](rules.md#styleblank-lines), with a `maximum`                                    |
+| Final newline; MD047                                                             | [`style/final-newline`](rules.md#stylefinal-newline)                                                  |
+| MD041 (first line is a heading)                                                  | [`structure/initial-heading`](rules.md#structureinitial-heading)                                      |
+| MD051 (link fragments)                                                           | [`links/valid`](rules.md#linksvalid), which also checks that local files exist                        |
+| MD052 (reference labels are defined)                                             | [`links/undefined-reference`](rules.md#linksundefined-reference), which also checks footnotes         |
+| MD053 (definitions are used)                                                     | [`links/unused-definition`](rules.md#linksunused-definition), which also checks footnotes             |
+| MD042 (no empty links)                                                           | [`links/empty`](rules.md#linksempty)                                                                  |
+| MD001 (heading levels go up by one)                                              | [`structure/heading-increment`](rules.md#structureheading-increment), with block quotes checked apart |
+| MD025 (one top-level heading)                                                    | [`structure/single-title`](rules.md#structuresingle-title)                                            |
+| MD024 (repeated headings) with `siblings_only`                                   | [`structure/duplicate-heading`](rules.md#structureduplicate-heading)                                  |
+| MD045 (image alternative text)                                                   | [`content/image-alt`](rules.md#contentimage-alt)                                                      |
+| MD056 (table column count)                                                       | [`content/table-columns`](rules.md#contenttable-columns)                                              |
+| MD040 (code block language)                                                      | [`content/code-language`](rules.md#contentcode-language)                                              |
+| `-` for bullets; MD004 (list style)                                              | [`style/list-marker`](rules.md#stylelist-marker), with MD004's `consistent` and `sublist`             |
+| `1.` and numbering; MD029 (ordered list prefix)                                  | [`style/ordered-list`](rules.md#styleordered-list); `same` stands for MD029's `one` and `zero`        |
+| One space after list markers, list indentation; MD005, MD007, MD030              | [`style/list-indent`](rules.md#stylelist-indent), with MD030's spacing and MD007's `indent`           |
+| Inline HTML, bare URLs; MD033, MD034                                             | None yet                                                                                              |
+| Hard tabs; MD010                                                                 | None yet                                                                                              |
+| Formatting the code inside code blocks                                           | None yet                                                                                              |
+| `<!-- prettier-ignore -->`, `<!-- markdownlint-disable -->`                      | [`<!-- mdtools-disable -->`](configuration.md#suppression-comments)                                   |
+| Custom rules                                                                     | [Plugins](plugins.md)                                                                                 |
+
+Prettier keeps line breaks by default (`proseWrap: "preserve"`), while
+`recommended` wraps at 80 columns. `style/wrap` keeps the lines of
+[site-generator syntax](dialects.md#what-each-dialect-reads) such as `:::note`
+and `{% tab %}`; for other syntax that depends on its line breaks, turn the rule
+off or use a suppression comment.
+
+## Agents and scripts
+
+Read the [JSON report](cli.md#json-report) and the exit code, not the text
+output, whose wording can change in any release. A diagnostic names its rule,
+its position, and, for a style rule, the edit it proposes. A safe loop is:
+`format --diff` to see the changes, `format --write` to apply them, then `lint`
+again for what needs a person. The [examples](examples.md#automate-checks)
+include a script that summarizes a report. To report a defect of the tool,
+follow the [contribution
+guide](https://github.com/viell-dev/slop-markdown-tools/blob/main/CONTRIBUTING.md#report-a-defect).

package/docs/obsidian.md

@@ -1,12 +1,12 @@
 # Obsidian vaults
 
-The Obsidian profile understands wikilinks, embeds, callouts, highlights,
-comments, heading references, and block references. Its rules share the same
-lint and format engine used for ordinary Markdown.
+The `obsidian` dialect reads wikilinks, embeds, callouts, highlights, comments,
+and heading and block references, and checks links the way Obsidian resolves
+them.
 
 ## Configure the vault
 
-Create `mdtools.config.jsonc` at the vault root:
+Create `mdtools.config.jsonc` at the vault's root, next to `.obsidian/`:
 
 ```jsonc
 {
@@ -15,102 +15,83 @@ Create `mdtools.config.jsonc` at the vault root:
 }
 ```
 
-Use the vault root as `--root` so the CLI can resolve links across all notes and
-from the vault's folder, as Obsidian does. Run these commands from a
-[built checkout](quick-start.md):
+Run the commands from the vault's root, or pass it with `--root`, so that links
+are resolved across the whole vault:
 
 ```sh
-node dist/cli/main.js lint --root "/path/to/vault" --json
-node dist/cli/main.js format --root "/path/to/vault" --diff
+npx mdtools lint --root "/path/to/vault"
+npx mdtools format --root "/path/to/vault" --diff
 ```
 
-Before that file exists, or when it names no dialect, the CLI still reads the
-notes in the Obsidian dialect: a folder that contains a `.obsidian` folder is
-recognized as a vault. Line breaks and wikilinks are then safe on a first run,
-but only the dialect is assumed. The rules of the `obsidian` preset, including
-the report that reflow is disabled, need the configuration above.
-Version 0.2.0-rc.1 and earlier read such a vault as CommonMark, joined the lines
-of its paragraphs, and could split a wikilink; with those versions, create the
-configuration first.
-
-## Vaults that are not the workspace root
-
-A note belongs to the nearest vault at or above its folder, wherever the
-workspace root is. Its assumed dialect and its line-break setting come from that
-vault:
-
-- **A vault in a folder of a larger workspace**, such as `docs/vault/` in a
-  repository: its notes are read in the Obsidian dialect and the documents
-  around it as GitHub Markdown. Each vault in a workspace follows its own
-  `.obsidian/app.json`.
-- **A folder of a vault used as the root**, with `--root` or through a
-  configuration file in that folder: the vault is found above the root.
-- **A repository inside a vault** is not part of the vault. The tool leaves a
-  repository inside a workspace alone, and when it runs in that repository it
-  reads the documents as GitHub Markdown.
-
-A dialect named by the configuration or by `--dialect` still takes precedence
-over all of this.
-
-Links follow the vault as well. In a vault below the workspace root, a link in a
-note reaches only the vault's files, as it does in Obsidian: a path is counted
-from the vault's folder, a search by note name looks inside the vault, and
-`links/path` writes `"style": "root"` paths from the vault's folder. The
-findings and edits are the ones a run with the vault as the root produces. A
-path that leads out of the vault to a file that exists, such as
-`[the project](../../README.md)`, is reported as
+Without a configuration file, the notes are still read in the Obsidian dialect,
+because the vault is recognized by its `.obsidian` directory; see [the assumed
+dialect](dialects.md#the-assumed-dialect). The rules of the `obsidian` preset,
+among them the report that wrapping is off, still need the configuration.
+
+## Enable wrapping
+
+Obsidian shows a single line break inside a paragraph as a line break unless the
+vault's "Strict line breaks" setting is on. `style/wrap` therefore wraps notes
+only when the vault's `.obsidian/app.json` contains `"strictLineBreaks": true`,
+and [`obsidian/strict-line-breaks`](rules.md#obsidianstrict-line-breaks) reports
+when it does not. The tool reads the file and never changes it; when you change
+the setting, keep the file's other settings. If the file cannot be read or is
+not valid JSON, the tool warns and leaves paragraphs as written; a byte order
+mark at its start is ignored. If strict line breaks do not suit your vault,
+disable `style/wrap`; the other rules still run.
+
+The tool reads highlights (`==text==`) and wikilinks within one line. A
+paragraph with `==`, `[[`, or `]]` outside them, such as a highlight written
+across two lines, is left as written, because joining its lines could create a
+highlight or a link.
+
+In a callout, the title line stays as written, with its folding marker, and the
+body is wrapped inside the quote, also directly below the title. A body
+paragraph is left as written in the cases that
+[`style/wrap`](rules.md#stylewrap) lists, and so is a body whose quote markers
+are not consistent, or inline syntax that runs from the title into the body. A
+title that is too long is reported by `reportUnbreakable`.
+
+## Vaults inside a larger workspace
+
+A note belongs to the nearest vault at or above its directory, wherever the
+workspace root is, and its dialect and its line-break setting come from that
+vault. A vault in a directory of a repository, such as `docs/vault/`, is read in
+the Obsidian dialect while the documents around it are read as GitHub Markdown.
+Each vault in a workspace follows its own `.obsidian/app.json`. A repository
+inside a vault is not part of the vault.
+
+Links follow the vault too. In a vault below the workspace root, a link reaches
+only the vault's files, as in Obsidian: a path counts from the vault's root, a
+search by note name looks only inside the vault, and `links/path` writes
+`"style": "root"` paths from the vault's root. A path that leaves the vault for
+a file that exists, such as `[the project](../../README.md)`, is reported as
 `Local target is outside the vault`, because Obsidian cannot follow it.
-Documents outside the vault link into it as into any other folder. Versions up
-to `0.2.0-rc.1` resolved such a vault's links from the workspace root.
+Documents outside the vault link into it as into any other directory.
 
-In the opposite layout, a root that is a folder of a vault, the tool sees only a
-part of the vault and reads nothing outside the root. It therefore treats a link
-as uncertain whenever the rest of the vault could matter:
+## A workspace root inside a vault
+
+When the workspace root is a directory inside a vault, through `--root` or a
+configuration file there, the tool finds the vault above it but reads nothing
+outside the root. Where the rest of the vault could matter, a link is uncertain:
 
 - A link with no match below the root is reported as
-  `Local target could not be checked`, with the reason that the workspace root
-  is only a part of the vault. It is not called missing.
-- A link found by note name, or by a path that Obsidian would first look for at
-  the top of the vault, is accepted but never rewritten by `links/path` or
-  `links/notation`: another note outside the root could be the one Obsidian
-  chooses.
-- A link written as an explicit relative path (`./Sub/Note.md`), or as a path
-  from the vault's folder that leads through the root, is certain and is
-  rewritten as usual. `"style": "root"` writes it from the vault's folder.
-
-For complete link checks and shortest-path rewriting, run with the vault as the
-root. Versions up to `0.2.0-rc.1` took the folder for the whole vault, which
-could shorten a link until it named a different note.
-
-## Enable source wrapping
-
-Obsidian reflow requires `"strictLineBreaks": true` in the vault's
-`.obsidian/app.json` so soft line breaks in source do not become visible line
-breaks in Reading view. Preserve the file's other settings when changing this
-value. The CLI checks it and never edits the settings file itself. If it is not
-permitted to read the file, or the file is not valid JSON, it warns and leaves
-paragraphs as written; see
-[paths that cannot be read](configuration.md#paths-that-cannot-be-read).
-
-If that setting is not appropriate for your vault, disable `style/wrap`. Other
-enabled rules can still run.
-
-## Wrap callout bodies
-
-With strict line breaks verified, `style/wrap` reflows supported body prose even
-when it directly follows the callout header without a blank quote line. The
-header stays on its original physical line, including its title and folding
-marker. Existing quote and list-container prefixes are retained.
-
-Hard breaks, block IDs, inline HTML, and unsupported multiline syntax still
-protect body paragraphs. Lazy or inconsistent quote continuations and inline
-syntax spanning the title/body boundary remain untouched. Long headers follow
-`reportUnbreakable`; skipped breakable body prose follows `reportUnreflowed`.
-
-## Choose link policies deliberately
-
-The recommended preset validates local links. To normalize verified destinations
-to vault-relative paths wrapped in angle brackets:
+  `Local target could not be checked`, because the workspace root is only part
+  of the vault. It is not called missing.
+- A link found by note name, or by a path that Obsidian would look for at the
+  vault's root first, is accepted but never rewritten by `links/path` or
+  `links/notation`: a note outside the root could be the one Obsidian chooses.
+- A link written as an explicit relative path (`./Sub/Note.md`), or as a
+  vault-relative path that leads into the root, is certain and is rewritten as
+  usual; `"style": "root"` writes it from the vault's root.
+
+For complete link checks and rewriting, use the vault's root as the workspace
+root.
+
+## Choose link policies
+
+The `recommended` preset checks links. To also write verified Markdown links as
+vault-relative paths in angle brackets, such as `[Note](<Folder/Note.md>)`:
 
 ```jsonc
 {
@@ -121,26 +102,21 @@ to vault-relative paths wrapped in angle brackets:
 }
 ```
 
-For example, a resolved Markdown link can become `[Note](<Folder/Note.md>)`.
-Note names and heading subpaths match case-insensitively, as in Obsidian, while
-block identifiers match exactly; notes whose paths differ only by case are
-reported as ambiguous. Missing or ambiguous destinations are never guessed.
-Unaliased wikilinks retain their target spelling because changing it may change
-their visible label. Note embeds remain embeds.
-
-See [link policies](configuration.md#link-policies) for relative paths,
-extension handling, and eligible Markdown/wikilink conversion. Path rewriting
-and notation conversion should be run in separate passes.
-
-## Review visible results
-
-Preview changes with `--diff`, then use `--write` to apply them. Inspect complex
-notes in Obsidian, especially when using additional plugins. The resolver does
-not reproduce every Obsidian link-resolution behavior, and unsupported syntax
-may need an ignore pattern or a
-[suppression comment](configuration.md#suppressions).
-
-The [vault example](examples.md#format-an-obsidian-vault) shows a small vault
-before and after formatting. Read the
-[current limitations](design.md#safety-boundaries) before a broad vault-wide
-formatting pass.
+Note names and headings match without regard to case, as in Obsidian, and block
+identifiers match exactly; notes whose paths differ only by case are ambiguous.
+A heading also matches as its source writes it, and `[[Note#Setup#Mobile]]`
+reaches a heading below another; a wikilink never names a folder. A missing or
+ambiguous target is never guessed. Wikilinks without a label keep their target
+as written, because it is their visible text, and embeds stay embeds, with any
+image size in their label. [`links/path`](rules.md#linkspath) and
+[`links/notation`](rules.md#linksnotation) describe the options.
+
+## Review the result
+
+Preview with `--diff` before `--write`, and look at complex notes in Obsidian
+afterwards, especially with community plugins whose syntax the tool does not
+know. The link resolver does not reproduce every behavior of Obsidian's, and
+syntax it does not know may need an `ignore` pattern or a [suppression
+comment](configuration.md#suppression-comments). The [vault
+example](examples.md#format-an-obsidian-vault) shows a small vault before and
+after formatting, and [limits](design.md#limits) lists what is not modeled.