moved parsing step out of the function

Author: GantaRoja

scripts/js/commands/checkMarkdown.ts

@@ -13,6 +13,10 @@
 import { globby } from "globby";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
 
 import { collectInvalidImageErrors } from "../lib/markdownImages.js";
 import { readMarkdown } from "../lib/markdownReader.js";
@@ -90,11 +94,18 @@ async function main() {
 
   for (const file of files) {
     const markdown = await readMarkdown(file);
-    const imageErrors = await collectInvalidImageErrors(markdown);
+    const processor = unified()
+      .use(remarkParse)
+      .use(remarkGfm)
+      .use(remarkFrontmatter, ["yaml"]);
+
+    const tree = processor.parse(markdown);
+
+    const imageErrors = await collectInvalidImageErrors(tree);
     const mismatchedTitleHeadingErrors =
       IGNORE_TITLE_MISMATCHES.includes(file) || file.startsWith("docs/api")
         ? new Set<string>()
-        : await collectHeadingTitleMismatch(markdown);
+        : await collectHeadingTitleMismatch(tree);
 
     //Collect all errors for this file
     const errorsInFile: string[] = [
@@ -114,14 +125,14 @@ async function main() {
   if (allErrors.length) {
     allErrors.forEach((error) => console.log(error));
     console.error(
-      "Some issues were found in your Markdown files. Please fix them before proceeding.\n" +
+      "💔 Some issues were found in your Markdown files. Please fix them before proceeding.\n" +
         "Image help: https://github.com/Qiskit/documentation#images\n" +
         "Title/Heading help: https://github.com/Qiskit/documentation#titles-and-headings\n",
     );
     process.exit(1);
   }
 
-  console.log("All files passed validation.\n");
+  console.log("✅ All files passed validation.\n");
 }
 
 async function determineContentFiles(args: Arguments): Promise<string[]> {

scripts/js/lib/markdownImages.test.ts

@@ -11,6 +11,19 @@
 // that they have been altered from the originals.
 
 import { expect, test } from "@playwright/test";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
+import { Root } from "mdast";
+
+function parseMarkdown(markdown: string): Root {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkFrontmatter, ["yaml"])
+    .parse(markdown);
+}
 
 import { collectInvalidImageErrors } from "./markdownImages.js";
 
@@ -45,8 +58,12 @@ test("Test the finding of invalid images", async () => {
 ![And a valid SVG](/learning/images/valid.svg)
 
 <img src="/learning/images/HTMLexample1.jpg" alt="" width="200"/>
+
     `;
-  const images = await collectInvalidImageErrors(markdown);
+
+  const tree = parseMarkdown(markdown);
+  const images = await collectInvalidImageErrors(tree);
+
   const correct_images = new Set([
     "Convert 'img1.png' to AVIF. You can use the command `magick <path/to/image>.png <path/to/image>.avif`. If ImageMagick isn't preinstalled, you can get it from https://imagemagick.org/script/download.php. Then delete the old file and update the markdown to point to the new file.",
     "Convert 'img2.png' to AVIF. You can use the command `magick <path/to/image>.png <path/to/image>.avif`. If ImageMagick isn't preinstalled, you can get it from https://imagemagick.org/script/download.php. Then delete the old file and update the markdown to point to the new file.",

scripts/js/lib/markdownImages.ts

@@ -11,55 +11,37 @@
 // that they have been altered from the originals.
 
 import { load } from "cheerio";
-import { unified } from "unified";
-import { Root } from "remark-mdx";
+import { Root } from "mdast";
 import { visit } from "unist-util-visit";
-import remarkParse from "remark-parse";
-import remarkGfm from "remark-gfm";
-import remarkStringify from "remark-stringify";
 import { last, split } from "lodash-es";
 
-export async function collectInvalidImageErrors(
-  markdown: string,
-): Promise<Set<string>> {
+export function collectInvalidImageErrors(tree: Root): Set<string> {
   const imagesErrors = new Set<string>();
 
-  await unified()
-    .use(remarkParse)
-    .use(remarkGfm)
-    .use(() => (tree: Root) => {
-      visit(tree, "image", (node) => {
-        // Sphinx uses the image path as alt text if it wasn't defined using the
-        // :alt: option.
-        const imageName = last(split(node.url, "/"));
-        if (!node.alt || node.alt.endsWith(imageName!)) {
-          imagesErrors.add(`The image '${node.url}' does not have alt text.`);
-        }
+  visit(tree, "image", (node) => {
+    const imageName = last(split(node.url, "/"));
+    if (!node.alt || node.alt.endsWith(imageName!)) {
+      imagesErrors.add(`The image '${node.url}' does not have alt text.`);
+    }
 
-        // Ask to convert PNG and JPEG to AVIF
-        if (node.url.match(/\.(png|jpe?g)$/)) {
-          const urlWithAvifExtension = node.url.replace(
-            /\.(png|jpe?g)$/,
-            ".avif",
-          );
-          imagesErrors.add(
-            `Convert '${imageName}' to AVIF. You can use the command \`magick <path/to/image>.png <path/to/image>.avif\`. ` +
-              `If ImageMagick isn't preinstalled, you can get it from https://imagemagick.org/script/download.php. ` +
-              `Then delete the old file and update the markdown to point to the new file.`,
-          );
-        }
-      });
-      visit(tree, "html", (node) => {
-        const $ = load(node.value);
-        if ($("img").length) {
-          imagesErrors.add(
-            `The image '${$("img").attr("src")}' uses an HTML <img> tag instead of markdown syntax.`,
-          );
-        }
-      });
-    })
-    .use(remarkStringify)
-    .process(markdown);
+    if (node.url.match(/\.(png|jpe?g)$/)) {
+      const urlWithAvifExtension = node.url.replace(/\.(png|jpe?g)$/, ".avif");
+      imagesErrors.add(
+        `Convert '${imageName}' to AVIF. You can use the command \`magick <path/to/image>.png <path/to/image>.avif\`. ` +
+          `If ImageMagick isn't preinstalled, you can get it from https://imagemagick.org/script/download.php. ` +
+          `Then delete the old file and update the markdown to point to the new file.`,
+      );
+    }
+  });
+
+  visit(tree, "html", (node) => {
+    const $ = load(node.value);
+    if ($("img").length) {
+      imagesErrors.add(
+        `The image '${$("img").attr("src")}' uses an HTML <img> tag instead of markdown syntax.`,
+      );
+    }
+  });
 
   return imagesErrors;
 }

scripts/js/lib/markdownTitles.test.ts

@@ -1,6 +1,6 @@
 // This code is a Qiskit project.
 //
-// (C) Copyright IBM 2023.
+// (C) Copyright IBM 2025.
 //
 // This code is licensed under the Apache License, Version 2.0. You may
 // obtain a copy of this license in the LICENSE file in the root directory
@@ -11,19 +11,31 @@
 // that they have been altered from the originals.
 
 import { expect, test } from "@playwright/test";
-
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
 import { collectHeadingTitleMismatch } from "./markdownTitles";
+import { Root } from "mdast";
+
+function parseMarkdown(markdown: string): Root {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkFrontmatter, ["yaml"])
+    .parse(markdown);
+}
 
 test("Test for matching titles and headings", async () => {
   const markdown1 = `---
 title: My Awesome Guide
 ---
 
 # My Awesome Guide
-    `;
-  const mismatched = await collectHeadingTitleMismatch(markdown1);
-  const result: Set<string> = new Set();
-  expect(mismatched).toEqual(result);
+  `;
+  const tree = parseMarkdown(markdown1);
+  const mismatched = await collectHeadingTitleMismatch(tree);
+  expect(mismatched).toEqual(new Set());
 });
 
 test("Test to find mismatched titles and headings", async () => {
@@ -36,29 +48,31 @@ author: John
 
 This guide will walk you through everything.`;
 
-  const mismatched2 = await collectHeadingTitleMismatch(markdown2);
+  const tree = parseMarkdown(markdown2);
+  const mismatched2 = await collectHeadingTitleMismatch(tree);
 
-  const result2: Set<string> = new Set([
+  const result2 = new Set([
     `Mismatch: frontmatter title "Qiskit Doc" does not match heading "Introduction"`,
   ]);
 
   expect(mismatched2).toEqual(result2);
 });
 
 test("Test to mismatched and complex titles and headings", async () => {
-  const markdown2 = `---
+  const markdown3 = `---
 title: My Awesome Guide
 ---
 
 # This is a *Heading*
 
 This guide will walk you through everything.`;
 
-  const mismatched2 = await collectHeadingTitleMismatch(markdown2);
+  const tree = parseMarkdown(markdown3);
+  const mismatched3 = await collectHeadingTitleMismatch(tree);
 
-  const result2: Set<string> = new Set([
+  const result3 = new Set([
     `Mismatch: frontmatter title "My Awesome Guide" does not match heading "This is a  Heading"`,
   ]);
 
-  expect(mismatched2).toEqual(result2);
+  expect(mismatched3).toEqual(result3);
 });

scripts/js/lib/markdownTitles.ts

@@ -1,7 +1,15 @@
-import { unified } from "unified";
-import remarkParse from "remark-parse";
-import remarkGfm from "remark-gfm";
-import remarkFrontmatter from "remark-frontmatter";
+// This code is a Qiskit project.
+//
+// (C) Copyright IBM 2025.
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE file in the root directory
+// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
 import { visit, EXIT } from "unist-util-visit";
 import { Root } from "mdast";
 import yaml from "js-yaml";
@@ -24,20 +32,13 @@ function extractText(node: any): string {
 }
 
 export async function collectHeadingTitleMismatch(
-  markdown: string,
+  tree: Root,
 ): Promise<Set<string>> {
   const mismatches = new Set<string>();
 
   let frontmatterTitle: string | undefined;
   let headingText: string | undefined;
 
-  const processor = unified()
-    .use(remarkParse)
-    .use(remarkGfm)
-    .use(remarkFrontmatter, ["yaml"]);
-
-  const tree = processor.parse(markdown);
-
   // Extract frontmatter title
   visit(tree, "yaml", (node: any) => {
     const data = yaml.load(node.value);