@mintlify/previewing 3.0.0

package/src/local-preview/index.ts

@@ -0,0 +1,196 @@
+import Chalk from "chalk";
+import child_process from "child_process";
+import open from "open";
+import fse, { pathExists } from "fs-extra";
+import inquirer from "inquirer";
+import { isInternetAvailable } from "is-internet-available";
+import path from "path";
+import shell from "shelljs";
+import { Octokit } from "@octokit/rest";
+import {
+  CLIENT_PATH,
+  HOME_DIR,
+  DOT_MINTLIFY,
+  CMD_EXEC_PATH,
+  TARGET_MINT_VERSION,
+  VERSION_PATH,
+  MINT_PATH,
+} from "../constants.js";
+import { buildLogger, ensureYarn } from "../util.js";
+import listener from "./listener/index.js";
+import { ArgumentsCamelCase } from "yargs";
+import { getConfigPath } from "./listener/utils/mintConfigFile.js";
+import type { Ora as OraType } from "ora";
+
+const nodeModulesExists = async () => {
+  return pathExists(path.join(DOT_MINTLIFY, "mint", "client", "node_modules"));
+};
+
+const promptForYarn = async () => {
+  const yarnInstalled = shell.which("yarn");
+  if (!yarnInstalled) {
+    await inquirer
+      .prompt([
+        {
+          type: "confirm",
+          name: "confirm",
+          message: "yarn must be globally installed. Install yarn?",
+          default: true,
+        },
+      ])
+      .then(({ confirm }) => {
+        if (confirm) {
+          shell.exec("npm install --global yarn");
+        } else {
+          console.log("Installation cancelled.");
+        }
+      });
+  }
+};
+
+const downloadTargetMint = async (logger: OraType) => {
+  fse.emptyDirSync(MINT_PATH);
+
+  logger.text = "Downloading Mintlify framework...";
+
+  const octokit = new Octokit();
+  const downloadRes = await octokit.repos.downloadTarballArchive({
+    owner: "mintlify",
+    repo: "mint",
+    ref: TARGET_MINT_VERSION,
+  });
+
+  logger.text = "Extracting Mintlify framework...";
+  const TAR_PATH = path.join(MINT_PATH, "mint.tar.gz");
+  fse.writeFileSync(TAR_PATH, Buffer.from(downloadRes.data as any));
+
+  // strip-components 1 removes the top level directory from the unzipped content
+  // which is a folder with the release sha
+  fse.mkdirSync(path.join(MINT_PATH, "mint-tmp"));
+  shell.exec("tar -xzf mint.tar.gz -C mint-tmp --strip-components 1", {
+    silent: true,
+  });
+
+  fse.removeSync(TAR_PATH);
+
+  fse.moveSync(
+    path.join(MINT_PATH, "mint-tmp", "client"),
+    path.join(CLIENT_PATH)
+  );
+
+  fse.writeFileSync(VERSION_PATH, TARGET_MINT_VERSION);
+
+  // Delete unnecessary content downloaded from GitHub
+  fse.removeSync(path.join(MINT_PATH, "mint-tmp"));
+
+  logger.text = "Installing dependencies...";
+
+  ensureYarn(logger);
+  shell.cd(CLIENT_PATH);
+  shell.exec("yarn", { silent: true });
+};
+
+const checkForMintJson = async (logger: OraType) => {
+  const configPath = await getConfigPath(CMD_EXEC_PATH);
+  if (configPath == null) {
+    logger.fail("Must be ran in a directory where a mint.json file exists.");
+    process.exit(1);
+  }
+  return;
+};
+
+const dev = async (argv: ArgumentsCamelCase) => {
+  shell.cd(HOME_DIR);
+  await promptForYarn();
+  const logger = buildLogger("Preparing local Mintlify instance...");
+  await fse.ensureDir(MINT_PATH);
+  shell.cd(MINT_PATH);
+
+  const internet = await isInternetAvailable();
+  if (!internet && !(await pathExists(CLIENT_PATH))) {
+    logger.fail(
+      "Running mintlify dev for the first time requires an internet connection."
+    );
+    process.exit(1);
+  }
+
+  if (internet) {
+    const mintVersionExists = await pathExists(VERSION_PATH);
+
+    let needToDownloadTargetMint = !mintVersionExists;
+
+    if (mintVersionExists) {
+      const currVersion = fse.readFileSync(VERSION_PATH, "utf8");
+      if (currVersion !== TARGET_MINT_VERSION) {
+        needToDownloadTargetMint = true;
+      }
+    }
+
+    if (needToDownloadTargetMint) {
+      await downloadTargetMint(logger);
+    }
+  }
+
+  if (!(await nodeModulesExists())) {
+    if (!internet) {
+      logger.fail(`Dependencies are missing and you are offline. Connect to the internet and run
+  
+      mintlify install
+      
+      `);
+    } else {
+      logger.fail(`Dependencies were not installed correctly, run
+  
+      mintlify install
+      
+      `);
+    }
+    process.exit(1);
+  }
+  await checkForMintJson(logger);
+  shell.cd(CLIENT_PATH);
+  const relativePath = path.relative(CLIENT_PATH, CMD_EXEC_PATH);
+  child_process.spawnSync("yarn preconfigure", [relativePath], { shell: true });
+  logger.succeed("Local Mintlify instance is ready. Launching your site...");
+  run((argv.port as string) || "3000");
+};
+
+const run = (port: string) => {
+  shell.cd(CLIENT_PATH);
+
+  // next-remote-watch can only receive ports as env variables
+  // https://github.com/hashicorp/next-remote-watch/issues/23
+  const mintlifyDevProcess = child_process.spawn("npm run dev-watch", {
+    env: {
+      ...process.env,
+      PORT: port,
+    },
+    cwd: CLIENT_PATH,
+    stdio: "pipe",
+    shell: true,
+  });
+  mintlifyDevProcess.stdout.on("data", (data) => {
+    const output = data.toString();
+    console.log(output);
+    if (output.startsWith("> Ready on http://localhost:")) {
+      console.log(
+        `🌿 ${Chalk.green(
+          `Your local preview is available at http://localhost:${port}`
+        )}`
+      );
+      console.log(
+        `🌿 ${Chalk.green("Press Ctrl+C any time to stop the local preview.")}`
+      );
+      open(`http://localhost:${port}`);
+    }
+  });
+  const onExit = () => {
+    mintlifyDevProcess.kill("SIGINT");
+    process.exit(0);
+  };
+  process.on("SIGINT", onExit);
+  process.on("SIGTERM", onExit);
+  listener();
+};
+
+export default dev;

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

@@ -0,0 +1,107 @@
+// 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: string[] = await getFileList(
+    contentDirectoryPath
+  );
+  const contentFilenames: string[] = [];
+  const staticFilenames: string[] = [];
+  const promises: Promise<void>[] = [];
+  const openApiFiles: OpenApiFile[] = [];
+  const snippets: string[] = [];
+  allFilesInCmdExecutionPath.forEach((filename: string) => {
+    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

@@ -0,0 +1,121 @@
+// 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 { categorizeFiles } from "./categorize.js";
+import { CMD_EXEC_PATH } from "../../constants.js";
+import { getConfigObj } from "./utils/mintConfigFile.js";
+
+const { readFile } = _promises;
+
+type DecoratedMintNavigation = DecoratedMintNavigationEntry[];
+
+type DecoratedMintNavigationEntry = {
+  group: string;
+  version?: string;
+  pages: DecoratedMintNavigationEntryChild[];
+};
+
+type DecoratedMintNavigationEntryChild =
+  | DecoratedMintNavigationEntry
+  | PageMetadata;
+
+type PageMetadata = Record<PageMetadataKeys, string>;
+
+const pageMetadataKeys = [
+  "title",
+  "description",
+  "sidebarTitle",
+  "href",
+  "api",
+  "openapi",
+  "contentType",
+  "auth",
+  "version",
+  "mode",
+  "hideFooterPagination",
+  "authors",
+  "lastUpdatedDate",
+  "createdDate",
+  "size",
+] as const;
+
+type PageMetadataKeys = typeof pageMetadataKeys[number];
+
+const generateDecoratedMintNavigationFromPages = (
+  filenamePageMetadataMap: Record<string, PageMetadata>,
+  mintConfigNav: MintNavigation[]
+): DecoratedMintNavigation => {
+  const filenames = Object.keys(filenamePageMetadataMap);
+  const createNav = (nav: MintNavigation): DecoratedMintNavigationEntry => {
+    return {
+      group: nav.group,
+      version: nav?.version,
+      pages: nav.pages.map((page: MintNavigationEntry) => {
+        if (typeof page === "string" && filenames.includes(page)) {
+          return filenamePageMetadataMap[page];
+        }
+        return createNav(page as MintNavigation);
+      }),
+    };
+  };
+
+  return mintConfigNav.map((nav) => createNav(nav));
+};
+
+const createFilenamePageMetadataMap = async (
+  contentDirectoryPath: string,
+  contentFilenames: string[],
+  openApiFiles: OpenApiFile[],
+  clientPath?: string,
+  writeFiles = false
+) => {
+  let pagesAcc = {};
+  const contentPromises: Promise<void>[] = [];
+  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 [filenamePageMetadataMap, configObj] = await Promise.all([
+    createFilenamePageMetadataMap(
+      CMD_EXEC_PATH,
+      contentFilenames,
+      openApiFiles
+    ),
+    getConfigObj(CMD_EXEC_PATH),
+  ]);
+  return generateDecoratedMintNavigationFromPages(
+    filenamePageMetadataMap,
+    configObj?.navigation
+  );
+};

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

@@ -0,0 +1,228 @@
+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

@@ -0,0 +1,27 @@
+// 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",
+  });
+};