fix(cli): better error message when frontmatter is broken (#5766)

\

fern/pages/changelogs/cli/2025-01-27.mdx

@@ -0,0 +1,5 @@
+## 0.51.5
+**`(fix):`** Added a new rule to validate frontmatter parsing across markdown files, ensuring frontmatter 
+is properly formatted and can be parsed without errors.
+
+

packages/cli/cli/versions.yml

@@ -1,3 +1,11 @@
+- changelogEntry:
+    - summary: |
+        Added a new rule to validate frontmatter parsing across markdown files, ensuring frontmatter 
+        is properly formatted and can be parsed without errors.
+      type: fix
+  irVersion: 55
+  version: 0.51.5
+
 - changelogEntry:
     - summary: |
         Various improvements to the Mintlify and Readme importers, including better default styling 

packages/cli/yaml/docs-validator/package.json

@@ -45,6 +45,7 @@
     "chardet": "^2.0.0",
     "estree-walker": "^3.0.3",
     "file-type": "^19.0.0",
+    "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
     "mdast-util-to-hast": "^13.2.0",
     "next-mdx-remote": "^5.0.0",
@@ -59,17 +60,17 @@
     "zod": "^3.22.3"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.4",
     "@fern-api/configs": "workspace:*",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.1",
+    "@types/hast": "^3.0.4",
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.8",
     "@types/node": "18.15.3",
     "@types/unist": "^3.0.3",
     "depcheck": "^1.4.7",
     "eslint": "^8.56.0",
     "prettier": "^3.4.2",
-    "@trivago/prettier-plugin-sort-imports": "^5.2.1",
     "typescript": "5.7.2",
-    "@types/jest": "^29.5.14",
-    "@types/js-yaml": "^4.0.8",
     "vitest": "^2.1.8"
   }
 }

packages/cli/yaml/docs-validator/src/getAllRules.ts

@@ -6,6 +6,7 @@ import { OnlyVersionedNavigation } from "./rules/only-versioned-navigation";
 import { PlaygroundEnvironmentsExistRule } from "./rules/playground-environments-exist";
 import { ValidDocsEndpoints } from "./rules/valid-docs-endpoints";
 import { ValidFileTypes } from "./rules/valid-file-types";
+import { ValidFrontmatter } from "./rules/valid-frontmatter";
 import { ValidateVersionFileRule } from "./rules/validate-version-file";
 
 export function getAllRules(): Rule[] {
@@ -18,6 +19,7 @@ export function getAllRules(): Rule[] {
         ValidFileTypes,
         PlaygroundEnvironmentsExistRule,
         ValidDocsEndpoints,
-        AllRolesMustBeDeclaredRule
+        AllRolesMustBeDeclaredRule,
+        ValidFrontmatter
     ];
 }

packages/cli/yaml/docs-validator/src/rules/valid-frontmatter/index.ts

@@ -0,0 +1 @@
+export { ValidFrontmatter } from "./valid-frontmatter";

packages/cli/yaml/docs-validator/src/rules/valid-frontmatter/valid-frontmatter.ts

@@ -0,0 +1,30 @@
+import { readFile } from "fs/promises";
+import grayMatter from "gray-matter";
+
+import { Rule } from "../../Rule";
+
+export const ValidFrontmatter: Rule = {
+    name: "valid-frontmatter",
+    create: () => {
+        return {
+            filepath: async ({ absoluteFilepath }) => {
+                if (!absoluteFilepath.endsWith(".md") && !absoluteFilepath.endsWith(".mdx")) {
+                    return [];
+                }
+
+                try {
+                    const fileContents = await readFile(absoluteFilepath, "utf-8");
+                    grayMatter(fileContents);
+                    return [];
+                } catch (error) {
+                    return [
+                        {
+                            severity: "fatal",
+                            message: `Failed to parse frontmatter${error instanceof Error ? `: ${error.message}` : ""}`
+                        }
+                    ];
+                }
+            }
+        };
+    }
+};