mintlify 2.1.0 → 3.0.4

package/src/local-preview/listener/categorize.ts

@@ -1,105 +0,0 @@
-// TODO - put in prebuild package
-import path from "path";
-
-import { getFileExtension, openApiCheck, getFileList } from "./utils.js";
-import { PotentialFileCategory } from "./utils/types.js";
-
-export const categorizeFiles = async (contentDirectoryPath: string) => {
-  const allFilesInCmdExecutionPath = await getFileList(contentDirectoryPath);
-  const contentFilenames = [];
-  const staticFilenames = [];
-  const promises = [];
-  const openApiFiles = [];
-  const snippets = [];
-  allFilesInCmdExecutionPath.forEach((filename) => {
-    promises.push(
-      (async () => {
-        const extension = getFileExtension(filename);
-        let isOpenApi = false;
-        if (extension && (extension === "mdx" || extension === "md")) {
-          if (filename.startsWith("/_snippets")) {
-            snippets.push(filename);
-          } else {
-            contentFilenames.push(filename);
-          }
-        } else if (
-          extension &&
-          (extension === "json" || extension === "yaml" || extension === "yml")
-        ) {
-          const openApiInfo = await openApiCheck(
-            path.join(contentDirectoryPath, filename)
-          );
-          isOpenApi = openApiInfo.isOpenApi;
-          if (isOpenApi) {
-            const fileName = path.parse(filename).base;
-            openApiFiles.push({
-              filename: fileName.substring(0, fileName.lastIndexOf(".")),
-              spec: openApiInfo.spec,
-            });
-          }
-        } else if (!filename.endsWith("mint.json") && !isOpenApi) {
-          // all other files
-          staticFilenames.push(filename);
-        }
-      })()
-    );
-  });
-  await Promise.all(promises);
-
-  return { contentFilenames, staticFilenames, openApiFiles, snippets };
-};
-
-const excludedMdFiles = ["readme", "license", "contributing", "contribute"];
-
-const supportedStaticFileExtensions = [
-  ".jpeg",
-  ".jpg",
-  ".jfif",
-  ".pjpeg",
-  ".pjp",
-  ".png",
-  ".svg",
-  ".svgz",
-  ".ico",
-  ".webp",
-  ".gif",
-  ".apng",
-  ".avif",
-  ".bmp",
-  ".mp4",
-];
-
-export const getCategory = (filePath: string): PotentialFileCategory => {
-  filePath = filePath.toLowerCase();
-
-  const parsed = path.parse(filePath);
-
-  if (parsed.base === "mint.json") {
-    return "mintConfig";
-  }
-
-  const fileName = parsed.name;
-  const extension = parsed.ext;
-  if (
-    filePath.startsWith("_snippets") &&
-    (extension === ".mdx" || extension === ".md")
-  ) {
-    return "snippet";
-  } else if (extension === ".mdx") {
-    return "page";
-  } else if (extension === ".md") {
-    // Exclude common markdown files people don't want on their docs website
-    if (excludedMdFiles.includes(fileName)) {
-      throw new Error("Excluded Md File");
-    }
-    return "page";
-  } else if (extension === ".yaml" || extension === ".yml") {
-    return "potentialYamlOpenApiSpec";
-  } else if (extension === ".json") {
-    return "potentialJsonOpenApiSpec";
-  } else if (supportedStaticFileExtensions.includes(extension)) {
-    return "staticFile";
-  }
-
-  throw new Error("Unsupported File Type, No change enacted");
-};

package/src/local-preview/listener/generate.ts

@@ -1,110 +0,0 @@
-// TODO - add types
-import { promises as _promises } from "fs";
-import { outputFile } from "fs-extra";
-import path from "path";
-import createPage from "./utils/createPage.js";
-import { OpenApiFile } from "./utils/types.js";
-import { categorizeFiles } from "./categorize.js";
-import { CMD_EXEC_PATH } from "../../constants.js";
-import { getConfigObj } from "./utils/mintConfigFile.js";
-const { readFile } = _promises;
-
-// TODO: Put in prebuild package
-const generateNavFromPages = (pages, mintConfigNav) => {
-  const createNav = (nav) => {
-    return {
-      group: nav.group,
-      version: nav.version,
-      pages: nav.pages.map((page) => {
-        if (typeof page === "string") {
-          return pages[page];
-        }
-        return createNav(page);
-      }),
-    };
-  };
-
-  if (mintConfigNav == null) {
-    return;
-  }
-
-  let navFile = mintConfigNav.map((nav) => createNav(nav));
-  const filterOutNullInPages = (pages) => {
-    const newPages = [];
-    pages.forEach((page) => {
-      if (page == null) {
-        return;
-      }
-      if (page?.pages) {
-        const newGroup = filterOutNullInGroup(page);
-        newPages.push(newGroup);
-      } else {
-        newPages.push(page);
-      }
-    });
-
-    return newPages;
-  };
-  const filterOutNullInGroup = (group) => {
-    const newPages = filterOutNullInPages(group.pages);
-    const newGroup = {
-      ...group,
-      pages: newPages,
-    };
-    return newGroup;
-  };
-  const newNavFile = navFile.map((group) => {
-    return filterOutNullInGroup(group);
-  });
-  return newNavFile;
-};
-
-// TODO: Put in prebuild package
-const createPagesAcc = async (
-  contentDirectoryPath: string,
-  contentFilenames: string[],
-  openApiFiles: OpenApiFile[],
-  clientPath?: string,
-  writeFiles = false
-) => {
-  let pagesAcc = {};
-  const contentPromises = [];
-  contentFilenames.forEach((filename) => {
-    contentPromises.push(
-      (async () => {
-        const sourcePath = path.join(contentDirectoryPath, filename);
-
-        const contentStr = (await readFile(sourcePath)).toString();
-        const { slug, pageMetadata, pageContent } = await createPage(
-          filename,
-          contentStr,
-          contentDirectoryPath,
-          openApiFiles
-        );
-        if (clientPath && writeFiles) {
-          const targetPath = path.join(clientPath, "src", "_props", filename);
-          await outputFile(targetPath, pageContent, {
-            flag: "w",
-          });
-        }
-        pagesAcc = {
-          ...pagesAcc,
-          [slug]: pageMetadata,
-        };
-      })()
-    );
-  });
-  await Promise.all(contentPromises);
-  return pagesAcc;
-};
-
-export const generateNav = async () => {
-  const { contentFilenames, openApiFiles } = await categorizeFiles(
-    CMD_EXEC_PATH
-  );
-  const [pageAcc, configObj] = await Promise.all([
-    createPagesAcc(CMD_EXEC_PATH, contentFilenames, openApiFiles),
-    getConfigObj(CMD_EXEC_PATH),
-  ]);
-  return generateNavFromPages(pageAcc, configObj?.navigation);
-};

package/src/local-preview/listener/index.ts

@@ -1,228 +0,0 @@
-import chokidar from "chokidar";
-import fse from "fs-extra";
-import pathUtil from "path";
-import Chalk from "chalk";
-import mintValidation from "@mintlify/validation";
-import { isFileSizeValid, openApiCheck } from "./utils.js";
-import { updateGeneratedNav, updateOpenApiFiles } from "./update.js";
-import { CLIENT_PATH, CMD_EXEC_PATH } from "../../constants.js";
-import { promises as _promises } from "fs";
-import createPage from "./utils/createPage.js";
-import { getCategory } from "./categorize.js";
-import { PotentialFileCategory, FileCategory } from "./utils/types.js";
-
-const { readFile } = _promises;
-
-const listener = () => {
-  chokidar
-    .watch(CMD_EXEC_PATH, {
-      ignoreInitial: true,
-      ignored: ["node_modules", ".git", ".idea"],
-      cwd: CMD_EXEC_PATH,
-    })
-    .on("add", async (filename: string) => {
-      try {
-        const category = await onUpdateEvent(filename);
-        switch (category) {
-          case "page":
-            console.log("New page detected: ", filename);
-            break;
-          case "snippet":
-            console.log("New snippet detected: ", filename);
-            break;
-          case "mintConfig":
-            console.log("Config added");
-            break;
-          case "openApi":
-            console.log("OpenApi spec added: ", filename);
-            break;
-          case "staticFile":
-            console.log("Static file added: ", filename);
-            break;
-        }
-      } catch (error) {
-        console.error(error.message);
-      }
-    })
-    .on("change", async (filename: string) => {
-      try {
-        const category = await onUpdateEvent(filename);
-        switch (category) {
-          case "page":
-            console.log("Page edited: ", filename);
-            break;
-          case "snippet":
-            console.log("Snippet edited: ", filename);
-            break;
-          case "mintConfig":
-            console.log("Config edited");
-            break;
-          case "openApi":
-            console.log("OpenApi spec edited: ", filename);
-            break;
-          case "staticFile":
-            console.log("Static file edited: ", filename);
-            break;
-        }
-      } catch (error) {
-        console.error(error.message);
-      }
-    })
-    .on("unlink", async (filename: string) => {
-      try {
-        const potentialCategory = getCategory(filename);
-        const targetPath = getTargetPath(potentialCategory, filename);
-        if (
-          potentialCategory === "page" ||
-          potentialCategory === "snippet" ||
-          potentialCategory === "mintConfig" ||
-          potentialCategory === "staticFile"
-        ) {
-          await fse.remove(targetPath);
-        }
-        switch (potentialCategory) {
-          case "page":
-            console.log(`Page deleted: ${filename}`);
-            break;
-          case "snippet":
-            console.log(`Snippet deleted: ${filename}`);
-            break;
-          case "mintConfig":
-            console.log(
-              "⚠️ mint.json deleted. Please create a new mint.json file as it is mandatory."
-            );
-            process.exit(1);
-          case "potentialJsonOpenApiSpec":
-          case "potentialYamlOpenApiSpec":
-            await updateOpenApiFiles();
-            await updateGeneratedNav();
-            break;
-          case "staticFile":
-            console.log("Static file deleted: ", filename);
-            break;
-        }
-      } catch (error) {
-        console.error(error.message);
-      }
-    });
-};
-
-const getTargetPath = (
-  potentialCategory: PotentialFileCategory,
-  filePath: string
-): string => {
-  switch (potentialCategory) {
-    case "page":
-    case "snippet":
-      return pathUtil.join(CLIENT_PATH, "src", "_props", filePath);
-    case "mintConfig":
-      return pathUtil.join(CLIENT_PATH, "src", "_props", "mint.json");
-    case "potentialYamlOpenApiSpec":
-    case "potentialJsonOpenApiSpec":
-      return pathUtil.join(CLIENT_PATH, "src", "_props", "openApiFiles.json");
-    case "staticFile":
-      return pathUtil.join(CLIENT_PATH, "public", filePath);
-    default:
-      throw new Error("Invalid category");
-  }
-};
-
-/**
- * This function is called when a file is added or changed
- * @param filename
- * @returns FileCategory
- */
-const onUpdateEvent = async (filename: string): Promise<FileCategory> => {
-  const filePath = pathUtil.join(CMD_EXEC_PATH, filename);
-  const potentialCategory = getCategory(filename);
-  const targetPath = getTargetPath(potentialCategory, filename);
-  let regenerateNav = false;
-  let category: FileCategory =
-    potentialCategory === "potentialYamlOpenApiSpec" ||
-    potentialCategory === "potentialJsonOpenApiSpec"
-      ? "staticFile"
-      : potentialCategory;
-
-  switch (potentialCategory) {
-    case "page":
-      regenerateNav = true;
-
-      const contentStr = (await readFile(filePath)).toString();
-      const { pageContent } = await createPage(
-        filename,
-        contentStr,
-        CMD_EXEC_PATH,
-        []
-      );
-      await fse.outputFile(targetPath, pageContent, {
-        flag: "w",
-      });
-      break;
-    case "snippet":
-      await fse.copy(filePath, targetPath);
-      break;
-    case "mintConfig":
-      regenerateNav = true;
-
-      const mintJsonFileContent = (await readFile(filePath)).toString();
-      try {
-        const mintConfig = JSON.parse(mintJsonFileContent);
-        const { status, errors, warnings } =
-          mintValidation.validateMintConfig(mintConfig);
-
-        errors.forEach((error) => {
-          console.error(`🚨 ${Chalk.red(error)}`);
-        });
-
-        warnings.forEach((warning) => {
-          console.warn(`⚠️ ${Chalk.yellow(warning)}`);
-        });
-
-        if (status === "success") {
-          await fse.copy(filePath, targetPath);
-        }
-      } catch (error) {
-        if (error.name === "SyntaxError") {
-          console.error(
-            `🚨 ${Chalk.red(
-              "mint.json has invalid JSON. You are likely missing a comma or a bracket. You can paste your mint.json file into https://jsonlint.com/ to get a more specific error message."
-            )}`
-          );
-        } else {
-          console.error(`🚨 ${Chalk.red(error.message)}`);
-        }
-      }
-
-      break;
-    case "potentialYamlOpenApiSpec":
-    case "potentialJsonOpenApiSpec":
-      let isOpenApi = false;
-      const openApiInfo = await openApiCheck(filePath);
-      isOpenApi = openApiInfo.isOpenApi;
-      if (isOpenApi) {
-        // TODO: Instead of re-generating all openApi files, optimize by just updating the specific file that changed.
-        await updateOpenApiFiles();
-        regenerateNav = true;
-        category = "openApi";
-      }
-      break;
-    case "staticFile":
-      if (await isFileSizeValid(filePath, 5)) {
-        await fse.copy(filePath, targetPath);
-      } else {
-        console.error(
-          Chalk.red(
-            `🚨 The file at ${filename} is too big. The maximum file size is 5 mb.`
-          )
-        );
-      }
-      break;
-  }
-  if (regenerateNav) {
-    // TODO: Instead of re-generating the entire nav, optimize by just updating the specific page that changed.
-    await updateGeneratedNav();
-  }
-  return category;
-};
-
-export default listener;

package/src/local-preview/listener/update.ts

@@ -1,27 +0,0 @@
-// TODO: Add Types
-import fse from "fs-extra";
-import { promises as _promises } from "fs";
-import { CLIENT_PATH, CMD_EXEC_PATH } from "../../constants.js";
-import { join } from "path";
-import { generateNav } from "./generate.js";
-import { categorizeFiles } from "./categorize.js";
-
-const { readFile } = _promises;
-
-// TODO: Put in prebuild package
-
-export const updateGeneratedNav = async () => {
-  const generatedNav = await generateNav();
-  const targetPath = join(CLIENT_PATH, "src", "_props", "generatedNav.json");
-  await fse.outputFile(targetPath, JSON.stringify(generatedNav, null, 2), {
-    flag: "w",
-  });
-};
-
-export const updateOpenApiFiles = async () => {
-  const { openApiFiles } = await categorizeFiles(CMD_EXEC_PATH);
-  const targetPath = join(CLIENT_PATH, "src", "_props", "openApiFiles.json");
-  await fse.outputFile(targetPath, JSON.stringify(openApiFiles, null, 2), {
-    flag: "w",
-  });
-};

package/src/local-preview/listener/utils/createPage.ts

@@ -1,211 +0,0 @@
-// TODO: Put in the prebuild package
-import matter from "gray-matter";
-import isAbsoluteUrl from "is-absolute-url";
-import { remark } from "remark";
-import remarkFrontmatter from "remark-frontmatter";
-import remarkGfm from "remark-gfm";
-import remarkMdx from "remark-mdx";
-import { visit } from "unist-util-visit";
-import type { OpenApiFile } from "./types.js";
-
-const createPage = async (
-  pagePath: string,
-  pageContent: string,
-  contentDirectoryPath: string,
-  openApiFiles: OpenApiFile[]
-) => {
-  let { data: metadata } = matter(pageContent);
-  try {
-    const parsedContent = await preParseMdx(pageContent, contentDirectoryPath);
-    pageContent = parsedContent;
-  } catch (error) {
-    pageContent = `🚧 A parsing error occured. Please contact the owner of this website.`;
-  }
-
-  // Replace .mdx so we can pass file paths into this function
-  const slug = pagePath.replace(/\.mdx?$/, "");
-  let defaultTitle = slugToTitle(slug);
-  // Append data from OpenAPI if it exists
-  const { title, description } = getOpenApiTitleAndDescription(
-    openApiFiles,
-    metadata?.openapi
-  );
-
-  if (title) {
-    defaultTitle = title;
-  }
-
-  const pageMetadata = {
-    title: defaultTitle,
-    description,
-    ...metadata,
-    href: optionallyAddLeadingSlash(slug),
-  };
-
-  return {
-    pageMetadata,
-    pageContent,
-    slug: removeLeadingSlash(slug),
-  };
-};
-
-const preParseMdx = async (fileContent, contentDirectoryPath) => {
-  const removeContentDirectoryPath = (filePath) => {
-    const pathArr = createPathArr(filePath);
-    const contentDirectoryPathArr = createPathArr(contentDirectoryPath);
-    contentDirectoryPathArr.reverse().forEach((dir, index) => {
-      if (pathArr[index] === dir) {
-        pathArr.pop();
-      }
-    });
-    return "/" + pathArr.join("/");
-  };
-
-  const removeContentDirectoryPaths = () => {
-    return (tree) => {
-      visit(tree, (node) => {
-        if (node == null) {
-          return;
-        }
-        if (node.name === "img" || node.name === "source") {
-          const srcAttrIndex = node.attributes.findIndex(
-            (attr) => attr?.name === "src"
-          );
-          const nodeUrl = node.attributes[srcAttrIndex].value;
-          if (
-            // <img/> component
-            srcAttrIndex !== -1 &&
-            !isAbsoluteUrl(nodeUrl) &&
-            !isDataString(nodeUrl)
-          ) {
-            node.attributes[srcAttrIndex].value =
-              removeContentDirectoryPath(nodeUrl);
-          }
-        } else if (
-          // ![]() format
-          node.type === "image" &&
-          node.url &&
-          !isAbsoluteUrl(node.url) &&
-          !isDataString(node.url)
-        ) {
-          node.url = removeContentDirectoryPath(node.url);
-        }
-      });
-      return tree;
-    };
-  };
-
-  const file = await remark()
-    .use(remarkMdx)
-    .use(remarkGfm)
-    .use(remarkFrontmatter, ["yaml", "toml"])
-    .use(removeContentDirectoryPaths)
-    .process(fileContent);
-  return String(file);
-};
-
-const removeLeadingSlash = (str) => {
-  const path = createPathArr(str);
-  return path.join("/");
-};
-
-const createPathArr = (path) => {
-  return path.split("/").filter((dir) => dir !== "");
-};
-
-const isDataString = (str) => str.startsWith("data:");
-
-const getOpenApiTitleAndDescription = (openApiFiles, openApiMetaField) => {
-  if (openApiFiles == null || !openApiMetaField || openApiMetaField == null) {
-    return {};
-  }
-
-  const { operation } = getOpenApiOperationMethodAndEndpoint(
-    openApiFiles,
-    openApiMetaField
-  );
-
-  if (operation == null) {
-    return {};
-  }
-
-  return {
-    title: operation.summary,
-    description: operation.description,
-  };
-};
-
-const getOpenApiOperationMethodAndEndpoint = (
-  openApiFiles,
-  openApiMetaField
-) => {
-  const { endpoint, method, filename } =
-    extractMethodAndEndpoint(openApiMetaField);
-
-  let path;
-
-  openApiFiles?.forEach((file) => {
-    const openApiFile = file.spec;
-    const openApiPath = openApiFile.paths && openApiFile.paths[endpoint];
-    const isFilenameOrNone = !filename || filename === file.filename;
-    if (openApiPath && isFilenameOrNone) {
-      path = openApiPath;
-    }
-  });
-
-  if (path == null) {
-    return {};
-  }
-
-  let operation;
-  if (method) {
-    operation = path[method.toLowerCase()];
-  } else {
-    const firstOperationKey = Object.keys(path)[0];
-    operation = path[firstOperationKey];
-  }
-
-  return {
-    operation,
-    method,
-    endpoint,
-  };
-};
-
-const extractMethodAndEndpoint = (openApiMetaField) => {
-  const methodRegex = /(get|post|put|delete|patch)\s/i;
-  const trimmed = openApiMetaField.trim();
-  const foundMethod = trimmed.match(methodRegex);
-
-  const startIndexOfMethod = foundMethod
-    ? openApiMetaField.indexOf(foundMethod[0])
-    : 0;
-  const endIndexOfMethod = foundMethod
-    ? startIndexOfMethod + foundMethod[0].length - 1
-    : 0;
-
-  const filename = openApiMetaField.substring(0, startIndexOfMethod).trim();
-
-  return {
-    method: foundMethod ? foundMethod[0].slice(0, -1).toUpperCase() : undefined,
-    endpoint: openApiMetaField.substring(endIndexOfMethod).trim(),
-    filename: filename ? filename : undefined,
-  };
-};
-
-function optionallyAddLeadingSlash(path) {
-  if (!path || path.startsWith("/")) {
-    return path;
-  }
-  return "/" + path;
-}
-
-export const slugToTitle = (slug) => {
-  const slugArr = slug.split("/");
-  let defaultTitle = slugArr[slugArr.length - 1].split("-").join(" "); //replace all dashes
-  defaultTitle = defaultTitle.split("_").join(" "); //replace all underscores
-  defaultTitle = defaultTitle.charAt(0).toUpperCase() + defaultTitle.slice(1); //capitalize first letter
-  return defaultTitle;
-};
-
-export default createPage;