feat: Migrate linting to remark-lint (#37)

Author: niallthomson

.gitignore

@@ -13,4 +13,6 @@ dist
 !.yarn/plugins
 !.yarn/releases
 !.yarn/sdks
-!.yarn/versions
+!.yarn/versions
+
+eval

README.md

@@ -111,10 +111,10 @@ Skip external link validation for offline or faster checks:
 toolkit-md check ./docs --skip-external-links
 ```
 
-Ignore specific markdownlint rules:
+Ignore specific remark-lint rules:
 
 ```bash
-toolkit-md check ./docs --ignore-rule MD013 --ignore-rule MD033
+toolkit-md check ./docs --ignore-rule maximum-line-length --ignore-rule no-html
 ```
 
 Only report errors (skip warnings):
@@ -169,7 +169,7 @@ Toolkit for Markdown supports configuration through:
 | `check.links.timeout`          | `--link-timeout`     | `TKMD_CHECK_LINK_TIMEOUT`              | Timeout in milliseconds for HTTP link and image checks                                       | `5000`                                               |
 | `check.links.skipExternal`     | `--skip-external-links` | `TKMD_CHECK_SKIP_EXTERNAL_LINKS`    | Skip validation of external HTTP/HTTPS links and images                                      | `false`                                              |
 | `check.links.ignorePatterns`   | `--ignore-link-pattern` | `TKMD_CHECK_LINK_IGNORE_PATTERN_*`  | Regex patterns for URLs to ignore during link checking, can be specified multiple times       | `[]`                                                 |
-| `check.lint.ignoreRules`       | `--ignore-rule`      | `TKMD_CHECK_LINT_IGNORE_RULE_*`        | Markdownlint rule names or aliases to ignore, can be specified multiple times                 | `[]`                                                 |
+| `check.lint.ignoreRules`       | `--ignore-rule`      | `TKMD_CHECK_LINT_IGNORE_RULE_*`        | remark-lint rule names to ignore (without the remark-lint- prefix), can be specified multiple times | `[]`                                                 |
 | `staticPrefix`                 | `--static-prefix`    | `TKMD_STATIC_PREFIX`                   | URL prefix indicating a link points to a file in the static directory                        | `undefined`                                          |
 | `staticDir`                    | `--static-dir`       | `TKMD_STATIC_DIR`                      | Directory relative to the cwd where static assets are stored, used with staticPrefix         | `undefined`                                          |
 
@@ -215,7 +215,7 @@ Create a `.toolkit-mdrc` file in JSON format:
       "ignorePatterns": ["^https://example\\.com/.*"]
     },
     "lint": {
-      "ignoreRules": ["MD013"]
+      "ignoreRules": ["maximum-line-length"]
     }
   },
   "staticPrefix": "/static/",
@@ -526,7 +526,7 @@ toolkit-md map ./docs --images
 
 ### `check`
 
-Validates Markdown content without AI by running linting checks (via markdownlint), verifying that local link targets exist, and confirming that referenced images are present. Remote links and images are validated with HTTP HEAD requests. This command requires no AWS credentials and is suitable for CI pipelines. Exits with code 1 if any errors are found.
+Validates Markdown content without AI by running linting checks (via remark-lint), verifying that local link targets exist, and confirming that referenced images are present. Remote links and images are validated with HTTP HEAD requests. This command requires no AWS credentials and is suitable for CI pipelines. Exits with code 1 if any errors are found.
 
 **Example:**
 
@@ -540,10 +540,10 @@ toolkit-md check ./docs
 toolkit-md check ./docs --skip-external-links
 ```
 
-**Ignore specific markdownlint rules:**
+**Ignore specific remark-lint rules:**
 
 ```bash
-toolkit-md check ./docs --ignore-rule MD013 --ignore-rule MD033
+toolkit-md check ./docs --ignore-rule maximum-line-length --ignore-rule no-html
 ```
 
 **Options:**

package.json

@@ -40,12 +40,15 @@
     "globby": "^14.0.2",
     "gray-matter": "^4.0.3",
     "handlebars": "^4.7.8",
-    "markdownlint": "^0.37.4",
     "ora": "^8.0.1",
     "remark": "^15.0.1",
     "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
     "remark-parse": "^11.0.0",
+    "remark-preset-lint-consistent": "^6.0.1",
+    "remark-preset-lint-recommended": "^7.0.1",
     "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
     "yaml": "^2.8.0",
     "zod": "^3.25.75"
   },

src/ai/mcp/runChecksTool.ts

@@ -110,14 +110,14 @@ export function registerRunChecksTool(
         }
 
         if (result.issues.length === 0) {
-          results.push(`${result.filePath}: no issues`);
-        } else {
-          results.push(result.filePath);
-          for (const issue of result.issues) {
-            results.push(
-              `  ${issue.line}:${issue.column}  ${issue.severity}  ${issue.rule}  ${issue.message}  (${issue.category})`,
-            );
-          }
+          continue;
+        }
+
+        results.push(result.filePath);
+        for (const issue of result.issues) {
+          results.push(
+            `  ${issue.line}:${issue.column}  ${issue.severity}  ${issue.rule}  ${issue.message}  (${issue.category})`,
+          );
         }
       }
 

src/check/lintChecker.ts

@@ -15,54 +15,69 @@
  */
 
 /**
- * @fileoverview Markdown linting checker using markdownlint.
+ * @fileoverview Markdown linting checker using remark-lint.
  *
- * Validates markdown content against markdownlint rules, with support
- * for ignoring specific rules by name or alias.
+ * Validates markdown content against remark-lint rules from the
+ * recommended and consistent presets, with support for ignoring
+ * specific rules by name.
  */
 
-import { lint } from "markdownlint/promise";
+import { remark } from "remark";
+import remarkDirective from "remark-directive";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkLintCodeBlockStyle from "remark-lint-code-block-style";
+import remarkLintHeadingStyle from "remark-lint-heading-style";
+import remarkLintNoUndefinedReferences from "remark-lint-no-undefined-references";
+import remarkPresetLintConsistent from "remark-preset-lint-consistent";
+import remarkPresetLintRecommended from "remark-preset-lint-recommended";
+import type { VFile } from "vfile";
+import remarkCodeDirective from "../content/utils/remarkCodeDirective.js";
 import type { CheckIssue } from "./types.js";
 
 /**
- * Runs markdownlint on the given content and returns any issues found.
+ * Runs remark-lint on the given content and returns any issues found.
  *
  * @param filePath - Path to the file being checked (used for reporting)
  * @param content - Raw markdown content to lint
- * @param ignoreRules - Rule names or aliases to disable
- * @returns Array of check issues found by markdownlint
+ * @param ignoreRules - Rule names to suppress (without the `remark-lint-` prefix)
+ * @returns Array of check issues found by remark-lint
  */
 export async function checkLint(
   filePath: string,
   content: string,
   ignoreRules: string[],
 ): Promise<CheckIssue[]> {
-  const config: Record<string, boolean> = {
-    default: true,
-    MD033: false,
-    MD013: false,
-  };
-  for (const rule of ignoreRules) {
-    config[rule] = false;
-  }
+  const processor = remark()
+    .use(remarkFrontmatter)
+    .use(remarkDirective)
+    .use(remarkCodeDirective)
+    .use(remarkPresetLintConsistent)
+    .use(remarkPresetLintRecommended)
+    .use(remarkLintNoUndefinedReferences, false)
+    .use(remarkLintCodeBlockStyle, false)
+    .use(remarkLintHeadingStyle, "atx");
 
-  const results = await lint({
-    strings: { [filePath]: content },
-    config,
+  const file: VFile = await processor.process({
+    path: filePath,
+    value: content,
   });
 
-  const fileResults = results[filePath];
-  if (!fileResults) {
-    return [];
-  }
+  const ignoreSet = new Set(
+    ignoreRules.map((r) => r.replace(/^remark-lint-/, "")),
+  );
 
-  return fileResults.map((result) => ({
-    file: filePath,
-    line: result.lineNumber,
-    column: 1,
-    severity: "warning" as const,
-    category: "lint" as const,
-    rule: result.ruleNames.join("/"),
-    message: result.ruleDescription,
-  }));
+  return file.messages
+    .filter((msg) => {
+      const ruleId = msg.ruleId ?? "";
+      return !ignoreSet.has(ruleId);
+    })
+    .map((msg) => ({
+      file: filePath,
+      line: msg.line ?? 1,
+      column: msg.column ?? 1,
+      severity: "warning" as const,
+      category: "lint" as const,
+      rule: msg.ruleId ?? "unknown",
+      message: msg.reason,
+    }));
 }

src/commands/check.ts

@@ -97,7 +97,7 @@ function printResults(result: CheckResult, baseDir: string): void {
       : file.filePath;
 
     if (file.issues.length === 0) {
-      console.log(chalk.green(`${relativePath}: no issues`));
+      continue;
     } else {
       console.log(chalk.underline(relativePath));
       for (const issue of file.issues) {

src/config/schema.ts

@@ -309,7 +309,9 @@ export const CONFIG_CHECK_LINK_IGNORE_PATTERNS = withConfig(
 export const CONFIG_CHECK_LINT_IGNORE_RULES = withConfig(
   z
     .array(z.string())
-    .describe("Markdownlint rule names or aliases to ignore")
+    .describe(
+      "remark-lint rule names to ignore (without the remark-lint- prefix)",
+    )
     .default([]),
   "ignoreRule",
   undefined,

src/content/utils/index.ts

@@ -23,4 +23,5 @@
 export * from "./diffUtils.js";
 export * from "./languageUtils.js";
 export * from "./markdownUtils.js";
+export { default as remarkCodeDirective } from "./remarkCodeDirective.js";
 export * from "./staticPathUtils.js";

src/content/utils/remarkCodeDirective.ts

@@ -0,0 +1,73 @@
+/**
+ * Copyright 2025 Amazon.com, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @fileoverview Remark plugin that converts :::code container directives
+ * into standard fenced code blocks.
+ *
+ * When used with remark-directive, a block like:
+ *
+ *   :::code{lang=python}
+ *   print("hello")
+ *   :::
+ *
+ * is parsed as a containerDirective node with name "code". This plugin
+ * replaces those nodes with standard mdast `code` nodes so downstream
+ * processors (serializers, linters) see regular fenced code blocks.
+ */
+
+import type { Code, Root, RootContent } from "mdast";
+import type { ContainerDirective } from "mdast-util-directive";
+import { visit } from "unist-util-visit";
+
+/**
+ * Remark plugin that transforms :::code directives into fenced code blocks.
+ */
+export default function remarkCodeDirective() {
+  return (tree: Root) => {
+    visit(tree, "containerDirective", (node, index, parent) => {
+      const directive = node as ContainerDirective;
+      if (directive.name !== "code" || index == null || !parent) {
+        return;
+      }
+
+      const lang =
+        directive.attributes?.lang ?? directive.attributes?.language ?? null;
+
+      const textParts: string[] = [];
+      for (const child of directive.children) {
+        if (child.type === "paragraph") {
+          const paragraphText = child.children
+            .map((c) => ("value" in c ? (c.value ?? "") : ""))
+            .join("");
+          textParts.push(paragraphText);
+        } else if ("value" in child && child.value != null) {
+          textParts.push(child.value);
+        }
+      }
+
+      const codeNode: Code = {
+        type: "code",
+        lang,
+        meta: null,
+        value: textParts.join("\n"),
+        position: node.position,
+      };
+
+      parent.children[index] = codeNode as RootContent;
+    });
+  };
+}

tests/check/checker.test.ts

@@ -106,7 +106,7 @@ describe("checkAll", () => {
     const nodes = [
       createTestNode({
         filePath: join(tempDir, "docs", "bad.md"),
-        content: "#Bad Heading\n",
+        content: "1) Hello, _Jupiter_ and *Neptune*!\n",
       }),
     ];
 
@@ -175,7 +175,7 @@ describe("checkAll", () => {
   });
 
   test("should respect ignoreRules option", async () => {
-    const content = "#Bad Heading\n";
+    const content = "1) Hello, _Jupiter_ and *Neptune*!\n";
     const nodes = [
       createTestNode({
         filePath: join(tempDir, "docs", "test.md"),
@@ -187,7 +187,7 @@ describe("checkAll", () => {
 
     const resultWith = await checkAll(nodes, {
       ...defaultOptions,
-      lint: { ignoreRules: ["MD018", "MD041"] },
+      lint: { ignoreRules: ["ordered-list-marker-style", "emphasis-marker"] },
     });
 
     expect(resultWithout.totalWarnings).toBeGreaterThan(
@@ -199,7 +199,7 @@ describe("checkAll", () => {
     const nodes = [
       createTestNode({
         filePath: join(tempDir, "docs", "test.md"),
-        content: "#Bad Heading\n\n[Missing](./nope.md)\n",
+        content: "1) Hello, _Jupiter_ and *Neptune*!\n\n[Missing](./nope.md)\n",
         links: [{ url: "./nope.md", text: "Missing", line: 3, remote: false }],
       }),
     ];
@@ -234,7 +234,7 @@ describe("checkAll", () => {
     const nodes = [
       createTestNode({
         filePath: join(tempDir, "docs", "test.md"),
-        content: "#Bad Heading\n\n[Missing](./nope.md)\n",
+        content: "1) Hello, _Jupiter_ and *Neptune*!\n\n[Missing](./nope.md)\n",
         links: [{ url: "./nope.md", text: "Missing", line: 3, remote: false }],
       }),
     ];
@@ -255,7 +255,7 @@ describe("checkAll", () => {
     const nodes = [
       createTestNode({
         filePath: join(tempDir, "docs", "test.md"),
-        content: "#Bad Heading\n\n[Missing](./nope.md)\n",
+        content: "1) Hello, _Jupiter_ and *Neptune*!\n\n[Missing](./nope.md)\n",
         links: [{ url: "./nope.md", text: "Missing", line: 3, remote: false }],
       }),
     ];
@@ -281,7 +281,7 @@ describe("checkAll", () => {
     const nodes = [
       createTestNode({
         filePath: join(tempDir, "docs", "test.md"),
-        content: "#Bad Heading\n\n[Missing](./nope.md)\n",
+        content: "1) Hello, _Jupiter_ and *Neptune*!\n\n[Missing](./nope.md)\n",
         links: [{ url: "./nope.md", text: "Missing", line: 3, remote: false }],
       }),
     ];