mintlify 1.0.7 → 1.0.8

package/src/local-preview/getOpenApiContext.ts

@@ -0,0 +1,61 @@
+export const extractMethodAndEndpoint = (api) => {
+  const methodRegex = /^get|post|put|delete|patch/i;
+  const trimmed = api.trim();
+  const foundMethod = trimmed.match(methodRegex);
+
+  const endIndexOfMethod = foundMethod
+    ? api.indexOf(foundMethod[0]) + foundMethod[0].length
+    : 0;
+
+  return {
+    method: foundMethod ? foundMethod[0].toUpperCase() : undefined,
+    endpoint: api.substring(endIndexOfMethod).trim(),
+  };
+};
+
+export const getOpenApiOperationMethodAndEndpoint = (
+  openApiObj,
+  openApiMetaField
+) => {
+  const { endpoint, method } = extractMethodAndEndpoint(openApiMetaField);
+
+  const path = openApiObj?.paths && openApiObj.paths[endpoint];
+
+  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,
+  };
+};
+
+export const getOpenApiTitleAndDescription = (openApiObj, openApiMetaField) => {
+  if (openApiObj == null || !openApiMetaField || openApiMetaField == null) {
+    return {};
+  }
+
+  const { operation } = getOpenApiOperationMethodAndEndpoint(
+    openApiObj,
+    openApiMetaField
+  );
+
+  if (operation == null) {
+    return {};
+  }
+
+  return {
+    title: operation.summary,
+    description: operation.description,
+  };
+};

package/src/local-preview/index.ts

@@ -0,0 +1,164 @@
+import Chalk from "chalk";
+import open from "open";
+import { promises as _promises } from "fs";
+import fse, { pathExists } from "fs-extra";
+import { isInternetAvailable } from "is-internet-available";
+import path from "path";
+import shell from "shelljs";
+import categorizeFiles from "./categorizeFiles.js";
+
+import { CMD_EXEC_PATH, CLIENT_PATH, INSTALL_PATH } from "../constants.js";
+import { injectFavicons } from "./injectFavicons.js";
+import listener from "./listener.js";
+import { createPage, createMetadataFileFromPages } from "./metadata.js";
+import { updateConfigFile } from "./mintConfigFile.js";
+import { buildLogger } from "../util.js";
+
+const { readFile } = _promises;
+
+const copyFiles = async (logger: any) => {
+  logger.start("Syncing doc files...");
+  shell.cd(CMD_EXEC_PATH);
+  const { markdownFiles, staticFiles, openApiBuffer } = await categorizeFiles();
+
+  const configObj = await updateConfigFile(logger);
+
+  const openApiTargetPath = path.join(CLIENT_PATH, "src", "openapi.json");
+  let openApiObj = null;
+  if (openApiBuffer) {
+    logger.succeed("OpenApi file synced");
+    await fse.outputFile(openApiTargetPath, Buffer.from(openApiBuffer), {
+      flag: "w",
+    });
+    openApiObj = JSON.parse(openApiBuffer.toString());
+  } else {
+    await fse.outputFile(openApiTargetPath, "{}", { flag: "w" });
+  }
+  let pages = {};
+  const mdPromises = [];
+  markdownFiles.forEach((filename) => {
+    mdPromises.push(
+      (async () => {
+        const sourcePath = path.join(CMD_EXEC_PATH, filename);
+        const pagesDir = path.join(CLIENT_PATH, "src", "pages");
+        const targetPath = path.join(pagesDir, filename);
+
+        await fse.remove(targetPath);
+        await fse.copy(sourcePath, targetPath);
+
+        const fileContent = await readFile(sourcePath);
+        const contentStr = fileContent.toString();
+        const page = createPage(filename, contentStr, openApiObj);
+        pages = {
+          ...pages,
+          ...page,
+        };
+      })()
+    );
+  });
+  const staticFilePromises = [];
+  staticFiles.forEach((filename) => {
+    staticFilePromises.push(
+      (async () => {
+        const sourcePath = path.join(CMD_EXEC_PATH, filename);
+        const publicDir = path.join(CLIENT_PATH, "public");
+        const targetPath = path.join(publicDir, filename);
+
+        await fse.remove(targetPath);
+        await fse.copy(sourcePath, targetPath);
+      })()
+    );
+  });
+  await Promise.all([
+    ...mdPromises,
+    ...staticFilePromises,
+    await injectFavicons(configObj, logger),
+  ]);
+  createMetadataFileFromPages(pages, configObj);
+  logger.succeed("All files synced");
+};
+
+const gitExists = () => {
+  let doesGitExist = true;
+  try {
+    shell.exec("git --version", { silent: true });
+  } catch (e) {
+    doesGitExist = false;
+  }
+  return doesGitExist;
+};
+
+const dev = async () => {
+  shell.cd(INSTALL_PATH);
+  const logger = buildLogger("Starting a local Mintlify instance...");
+  if (!(await pathExists(path.join(INSTALL_PATH, "mint")))) {
+    shell.exec("mkdir mint");
+  }
+  shell.cd("mint");
+  let runYarn = true;
+  const gitInstalled = gitExists();
+  let firstInstallation = false;
+  if (!(await pathExists(path.join(INSTALL_PATH, "mint", ".git")))) {
+    firstInstallation = true;
+    if (gitInstalled) {
+      logger.start("Initializing local Mintlify instance...");
+      shell.exec("git init", { silent: true });
+      shell.exec(
+        "git remote add -f mint-origin https://github.com/mintlify/mint.git",
+        { silent: true }
+      );
+    } else {
+      logger.fail(
+        "git must be installed (https://github.com/git-guides/install-git)"
+      );
+      process.exit(1);
+    }
+  }
+
+  const internet = await isInternetAvailable();
+  let pullOutput = null;
+  if (internet && gitInstalled) {
+    shell.exec("git config core.sparseCheckout true", { silent: true });
+    shell.exec('echo "client/" >> .git/info/sparse-checkout', { silent: true });
+    pullOutput = shell.exec("git pull mint-origin main", {
+      silent: true,
+    }).stdout;
+    shell.exec("git config core.sparseCheckout false", { silent: true });
+    shell.exec("rm .git/info/sparse-checkout", { silent: true });
+  }
+  if (pullOutput === "Already up to date.\n") {
+    runYarn = false;
+  }
+  shell.cd(CLIENT_PATH);
+  if (internet && runYarn) {
+    if (firstInstallation) {
+      logger.succeed("Local Mintlify instance initialized");
+    }
+    logger.start("Updating dependencies...");
+
+    shell.exec("yarn", { silent: true });
+    if (firstInstallation) {
+      logger.succeed("Installation complete");
+    } else {
+      logger.succeed("Dependencies updated");
+    }
+  }
+
+  // TODO check for mint.json before copying over files
+  await copyFiles(logger);
+  run();
+};
+
+const run = () => {
+  shell.cd(CLIENT_PATH);
+  console.log(
+    `🌿 ${Chalk.green(
+      "Navigate to your local preview at https://localhost:3000"
+    )}`
+  );
+  shell.exec("npm run dev", { async: true });
+  open("http://localhost:3000");
+  listener();
+};
+
+export default dev;

package/src/local-preview/injectFavicons.ts

@@ -0,0 +1,76 @@
+import favicons from "favicons";
+import { promises as _promises } from "fs";
+import { outputFile } from "fs-extra";
+import { join } from "path";
+import { CLIENT_PATH, CMD_EXEC_PATH } from "../constants.js";
+
+const { readFile } = _promises;
+
+export const injectFavicons = async (configObj, logger) => {
+  if (configObj?.favicon == null) return;
+
+  const desiredPath = join(CMD_EXEC_PATH, configObj.favicon);
+  const favicon = await readFile(desiredPath);
+  if (favicon == null) return;
+  logger.start("Generating favicons...");
+  const promises = [];
+  try {
+    const response = await favicons(favicon, faviconConfig(configObj?.name));
+    response.images.forEach((img) => {
+      promises.push(
+        (async () => {
+          const targetPath = join(CLIENT_PATH, "public", "favicons", img.name);
+          await outputFile(targetPath, Buffer.from(img.contents), {
+            flag: "w",
+          });
+        })()
+      );
+    });
+    response.files.forEach((file) => {
+      promises.push(
+        (async () => {
+          const targetPath = join(CLIENT_PATH, "public", "favicons", file.name);
+          await outputFile(targetPath, file.contents, { flag: "w" });
+        })()
+      );
+    });
+    await Promise.all(promises);
+    logger.succeed("Favicons generated");
+  } catch (err) {
+    console.log(err.message); // Error description e.g. "An unknown error has occurred"
+  }
+};
+
+const faviconConfig = (name) => ({
+  path: "/favicons", // Path for overriding default icons path. `string`
+  appName: name, // Your application's name. `string`
+  appShortName: name, // Your application's short_name. `string`. Optional. If not set, appName will be used
+  appDescription: null, // Your application's description. `string`
+  developerName: null, // Your (or your developer's) name. `string`
+  developerURL: null, // Your (or your developer's) URL. `string`
+  dir: "auto", // Primary text direction for name, short_name, and description
+  lang: "en-US", // Primary language for name and short_name
+  background: "#fff", // Background colour for flattened icons. `string`
+  theme_color: "#fff", // Theme color user for example in Android's task switcher. `string`
+  appleStatusBarStyle: "black-translucent", // Style for Apple status bar: "black-translucent", "default", "black". `string`
+  display: "standalone", // Preferred display mode: "fullscreen", "standalone", "minimal-ui" or "browser". `string`
+  orientation: "any", // Default orientation: "any", "natural", "portrait" or "landscape". `string`
+  scope: "/", // set of URLs that the browser considers within your app
+  start_url: "/?homescreen=1", // Start URL when launching the application from a device. `string`
+  preferRelatedApplications: false, // Should the browser prompt the user to install the native companion app. `boolean`
+  relatedApplications: undefined, // Information about the native companion apps. This will only be used if `preferRelatedApplications` is `true`. `Array<{ id: string, url: string, platform: string }>`
+  version: "1.0", // Your application's version string. `string`
+  logging: false, // Print logs to console? `boolean`
+  pixel_art: false, // Keeps pixels "sharp" when scaling up, for pixel art.  Only supported in offline mode.
+  loadManifestWithCredentials: true, // Browsers don't send cookies when fetching a manifest, enable this to fix that. `boolean`
+  manifestMaskable: false, // Maskable source image(s) for manifest.json. "true" to use default source. More information at https://web.dev/maskable-icon/. `boolean`, `string`, `buffer` or array of `string`
+  icons: {
+    android: ["android-chrome-192x192.png", "android-chrome-256x256.png"],
+    appleIcon: ["apple-touch-icon.png"],
+    appleStartup: false,
+    favicons: true,
+    windows: ["mstile-150x150.png"],
+    yandex: false,
+    firefox: false,
+  },
+});

package/src/local-preview/listener.ts

@@ -0,0 +1,116 @@
+import chokidar from "chokidar";
+import fse from "fs-extra";
+import path from "path";
+import { CLIENT_PATH, CMD_EXEC_PATH } from "../constants.js";
+import { fileBelongsInPagesFolder, getFileExtension } from "../util.js";
+import { createMetadataFile } from "./metadata.js";
+import openApiCheck from "./openApiCheck.js";
+
+const listener = () => {
+  chokidar
+    .watch(CMD_EXEC_PATH, {
+      ignoreInitial: true,
+      ignored: "node_modules",
+      cwd: CMD_EXEC_PATH,
+    })
+    .on("all", async (event, filename) => {
+      if (event === "unlink" || event === "unlinkDir") {
+        if (fileBelongsInPagesFolder(filename)) {
+          const targetPath = path.join(CLIENT_PATH, "src", "pages", filename);
+          await fse.remove(targetPath);
+          console.log("Page deleted: ", filename);
+        } else if (
+          filename === "mint.config.json" ||
+          filename === "mint.json"
+        ) {
+          const targetPath = path.join(CLIENT_PATH, "src", "mint.json");
+          await fse.remove(targetPath);
+          console.log(
+            "⚠️ mint.json deleted. Please create a new mint.json file as it is mandatory."
+          );
+          process.exit(1);
+        } else {
+          // all other files
+          const targetPath = path.join(CLIENT_PATH, "public", filename);
+          await fse.remove(targetPath);
+          console.log("Static file deleted: ", filename);
+        }
+      } else {
+        const filePath = path.join(CMD_EXEC_PATH, filename);
+        let updateMetadata = false;
+        if (fileBelongsInPagesFolder(filename)) {
+          updateMetadata = true;
+          const targetPath = path.join(CLIENT_PATH, "src", "pages", filename);
+          await fse.copy(filePath, targetPath);
+          switch (event) {
+            case "add":
+            case "addDir":
+              console.log("New page detected: ", filename);
+              break;
+            default:
+              console.log("Page edited: ", filename);
+              break;
+          }
+        } else if (
+          filename === "mint.config.json" ||
+          filename === "mint.json"
+        ) {
+          updateMetadata = true;
+          const targetPath = path.join(CLIENT_PATH, "src", "mint.json");
+          await fse.copy(filePath, targetPath);
+          switch (event) {
+            case "add":
+            case "addDir":
+              console.log("Config added");
+              break;
+            default:
+              console.log("Config edited");
+              break;
+          }
+        } else {
+          const extension = getFileExtension(filename);
+          let isOpenApi = false;
+          if (
+            extension &&
+            (extension === "json" ||
+              extension === "yaml" ||
+              extension === "yml")
+          ) {
+            const openApiInfo = await openApiCheck(
+              path.join(CMD_EXEC_PATH, filename)
+            );
+            isOpenApi = openApiInfo.isOpenApi;
+          }
+          let targetPath = path.join(CLIENT_PATH, "public", filename);
+          if (isOpenApi) {
+            targetPath = path.join(CLIENT_PATH, "src", "openapi.json");
+            updateMetadata = true;
+          }
+          // all other files
+          await fse.copy(filePath, targetPath);
+          switch (event) {
+            case "add":
+            case "addDir":
+              if (isOpenApi) {
+                console.log("OpenApi file added: ", filename);
+              } else {
+                console.log("Static file added: ", filename);
+              }
+              break;
+            default:
+              if (isOpenApi) {
+                console.log("OpenApi file edited: ", filename);
+              } else {
+                console.log("Static file edited: ", filename);
+              }
+              break;
+          }
+        }
+        if (updateMetadata) {
+          await createMetadataFile();
+        }
+      }
+    });
+};
+
+export default listener;

package/src/local-preview/metadata.ts

@@ -0,0 +1,154 @@
+// TODO - add types
+import fse from "fs-extra";
+import { promises as _promises } from "fs";
+import matter from "gray-matter";
+import path from "path";
+
+import categorizeFiles from "./categorizeFiles.js";
+import { getConfigObj } from "./mintConfigFile.js";
+import { getOpenApiTitleAndDescription } from "./getOpenApiContext.js";
+import { slugToTitle } from "./slugToTitle.js";
+import { CLIENT_PATH, CMD_EXEC_PATH } from "../constants.js";
+
+const { readFile } = _promises;
+
+// End matter is front matter, but at the end
+const getIndexOfEndMatter = (fileContents: string) => {
+  const frontMatters = fileContents.match(
+    /---\n(title:.+\n|description:.+\n|sidebarTitle:.+\n|api:.+\n|openapi:.+\n)+---$/m
+  );
+  if (frontMatters) {
+    return fileContents.indexOf(frontMatters[0]);
+  }
+
+  return -1;
+};
+
+export const potentiallyRemoveEndMatter = (fileContents: string) => {
+  const endMatterIndex = getIndexOfEndMatter(fileContents);
+
+  if (endMatterIndex === -1) {
+    return fileContents;
+  }
+
+  return fileContents.substring(0, endMatterIndex);
+};
+
+const getMetadata = (fileContents: string) => {
+  const { data } = matter(fileContents);
+
+  if (Object.keys(data).length > 0) {
+    return data;
+  }
+
+  const startIndex = getIndexOfEndMatter(fileContents);
+  if (startIndex === -1) {
+    return {};
+  }
+
+  const fileContentFromFrontMatter = fileContents.substring(startIndex);
+  const { data: nonTopFrontMatter } = matter(fileContentFromFrontMatter);
+  return nonTopFrontMatter;
+};
+
+export const createPage = (
+  path: string,
+  content: string,
+  openApiObj: object | null
+) => {
+  const slug = path.replace(/\.mdx?$/, "").substring(1);
+  let defaultTitle = slugToTitle(slug);
+  const metadata = getMetadata(content);
+  // Append data from OpenAPI if it exists
+  const { title, description } = getOpenApiTitleAndDescription(
+    openApiObj,
+    metadata?.openapi
+  );
+  if (title) {
+    defaultTitle = title;
+  }
+  return {
+    [slug]: { title: defaultTitle, description, ...metadata, href: `/${slug}` },
+  };
+};
+
+export const createMetadataFileFromPages = (pages: any, configObj: any) => {
+  const targetPath = path.join(CLIENT_PATH, "src", "metadata.json");
+  const createNav = (nav) => {
+    return {
+      group: nav.group,
+      pages: nav.pages.map((page) => {
+        if (typeof page === "string") {
+          return pages[page];
+        }
+
+        return createNav(page);
+      }),
+    };
+  };
+
+  if (configObj?.navigation == null) {
+    return;
+  }
+
+  let navFile = configObj.navigation.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);
+  });
+  fse.outputFileSync(targetPath, JSON.stringify(newNavFile, null, 2), {
+    flag: "w",
+  });
+};
+
+export const createMetadataFile = async () => {
+  // create pages
+  const { markdownFiles, openApiBuffer } = await categorizeFiles();
+  let openApiObj = null;
+  if (openApiBuffer) {
+    openApiObj = JSON.parse(openApiBuffer.toString());
+  }
+  // create config object
+  const configObj = await getConfigObj();
+  let pages = {};
+  const mdPromises = [];
+  markdownFiles.forEach((filename) => {
+    mdPromises.push(
+      (async () => {
+        const sourcePath = path.join(CMD_EXEC_PATH, filename);
+        const fileContent = await readFile(sourcePath);
+        const contentStr = fileContent.toString();
+        const page = createPage(filename, contentStr, openApiObj);
+        pages = {
+          ...pages,
+          ...page,
+        };
+      })()
+    );
+  });
+  await Promise.all(mdPromises);
+  createMetadataFileFromPages(pages, configObj);
+};

package/src/local-preview/mintConfigFile.ts

@@ -0,0 +1,48 @@
+import { promises as _promises } from "fs";
+import fse, { pathExists } from "fs-extra";
+import path from "path";
+
+import { CLIENT_PATH, CMD_EXEC_PATH } from "../constants.js";
+
+const { readFile } = _promises;
+
+const getConfigPath = async (): Promise<string | null> => {
+  let configPath = null;
+  if (await pathExists(path.join(CMD_EXEC_PATH, "mint.config.json"))) {
+    configPath = path.join(CMD_EXEC_PATH, "mint.config.json");
+  }
+
+  if (await pathExists(path.join(CMD_EXEC_PATH, "mint.json"))) {
+    configPath = path.join(CMD_EXEC_PATH, "mint.json");
+  }
+  return configPath;
+};
+
+export const getConfigObj = async (): Promise<object | null> => {
+  const configPath = await getConfigPath();
+  let configObj = null;
+  if (configPath) {
+    const configContents = await readFile(configPath);
+    configObj = JSON.parse(configContents.toString());
+  }
+  return configObj;
+};
+
+export const updateConfigFile = async (logger: any) => {
+  const configTargetPath = path.join(CLIENT_PATH, "src", "mint.json");
+  await fse.remove(configTargetPath);
+  let configObj = null;
+  const configPath = await getConfigPath();
+
+  if (configPath) {
+    await fse.remove(configTargetPath);
+    await fse.copy(configPath, configTargetPath);
+    logger.succeed("mint config file synced");
+    const configContents = await readFile(configPath);
+    configObj = JSON.parse(configContents.toString());
+  } else {
+    logger.fail("Must be ran in a directory where a mint.json file exists.");
+    process.exit(1);
+  }
+  return configObj;
+};

package/src/local-preview/openApiCheck.ts

@@ -0,0 +1,19 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { promises as _promises } from "fs";
+
+const openApiCheck = async (
+  path: string
+): Promise<{ buffer: Buffer | undefined; isOpenApi: boolean }> => {
+  let buffer = undefined;
+  let isOpenApi = false;
+  try {
+    const api = await SwaggerParser.validate(path);
+    buffer = Buffer.from(JSON.stringify(api, null, 2), "utf-8");
+    isOpenApi = true;
+  } catch {
+    // not valid openApi
+  }
+  return { buffer, isOpenApi };
+};
+
+export default openApiCheck;

package/src/local-preview/slugToTitle.ts

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

package/src/navigation.ts

@@ -0,0 +1,12 @@
+export type NavigationEntry = string | Navigation;
+
+export type Navigation = {
+  group: string;
+  pages: NavigationEntry[];
+};
+
+export function isNavigation(
+  navEntry: NavigationEntry
+): navEntry is Navigation {
+  return typeof navEntry !== "string";
+}

package/src/pageTemplate.ts

@@ -0,0 +1,32 @@
+import inquirer from "inquirer";
+import { createPage } from "./util.js";
+
+const generatePageTemplate = () => {
+  inquirer
+    .prompt([
+      {
+        type: "input",
+        name: "title",
+        message: "What is the title of the new page?",
+      },
+      {
+        type: "input",
+        name: "description",
+        message: "What is the description?",
+        default: "",
+      },
+    ])
+    .then((answers) => {
+      const { title, description } = answers;
+
+      createPage(title, description);
+      console.log("🌱 Created initial files for Mintlify docs");
+      process.exit(0);
+    })
+    .catch((error) => {
+      console.error(error);
+      process.exit(1);
+    });
+};
+
+export default generatePageTemplate;