@docsalot/previewing 0.1.0-beta.0

package/README.md

@@ -0,0 +1,17 @@
+# @mintlify/previewing
+
+Preview Mintlify docs locally.
+
+## 🚀 Installation
+
+```
+npm install @mintlify/previewing
+```
+
+## Community
+
+Join our Discord community if you have questions or just want to chat:
+
+[![](https://dcbadge.vercel.app/api/server/ACREKdwjG5)](https://discord.gg/ACREKdwjG5)
+
+_Built with 💚 by the Mintlify community._

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const TARGET_MINT_VERSION = "v0.0.9";
+export declare const INSTALL_PATH: string;
+export declare const HOME_DIR: string;
+export declare const DOT_MINTLIFY: string;
+export declare const VERSION_PATH: string;
+export declare const CLIENT_PATH: string;
+export declare const MINT_PATH: string;
+export declare const CMD_EXEC_PATH: string;
+export declare const SUPPORTED_MEDIA_EXTENSIONS: string[];

package/dist/constants.js

@@ -0,0 +1,37 @@
+// ignore for ts
+// @ts-nocheck
+import path from "path";
+import * as url from "url";
+import os from "os";
+// Change this to bump to a newer version of mint's client
+export const TARGET_MINT_VERSION = "v0.0.9";
+// package installation location
+export const INSTALL_PATH = url.fileURLToPath(new URL(".", import.meta.url));
+export const HOME_DIR = os.homedir();
+// DOT_MINTLIFY can be overridden via environment variable
+// Priority: DOCSALOT_PATH env var > hardcoded local path
+// Docker: Set DOCSALOT_PATH=/app/mint-main
+const HARDCODED_PATH = '/Users/faizank/workspace/experiments/live_projects/slashml/mint-main';
+export const DOT_MINTLIFY = process.env.DOCSALOT_PATH || HARDCODED_PATH;
+export const VERSION_PATH = path.join(DOT_MINTLIFY, "mint", "mint-version.txt");
+export const CLIENT_PATH = path.join(DOT_MINTLIFY, "client");
+export const MINT_PATH = path.join(DOT_MINTLIFY, "mint");
+// command execution location
+export const CMD_EXEC_PATH = process.cwd();
+export const SUPPORTED_MEDIA_EXTENSIONS = [
+    "jpeg",
+    "jpg",
+    "jfif",
+    "pjpeg",
+    "pjp",
+    "png",
+    "svg",
+    "svgz",
+    "ico",
+    "webp",
+    "gif",
+    "apng",
+    "avif",
+    "bmp",
+    "mp4",
+];

package/dist/downloadImage.d.ts

@@ -0,0 +1,4 @@
+export declare function isValidImageSrc(src: string): boolean;
+export declare function removeMetadataFromImageSrc(src: string): string;
+export declare function cleanImageSrc(src: string, origin: string): string;
+export default function downloadImage(imageSrc: string, writePath: string, overwrite?: boolean): Promise<void>;

package/dist/downloadImage.js

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, createWriteStream } from "fs";
+import path from "path";
+import axios from "axios";
+import { getFileExtension } from "./util.js";
+import { SUPPORTED_MEDIA_EXTENSIONS } from "./constants.js";
+async function writeImageToFile(imageSrc, writePath, overwrite) {
+    // Avoid unnecessary downloads
+    if (existsSync(writePath) && !overwrite) {
+        return Promise.reject({
+            code: "EEXIST",
+        });
+    }
+    // Create the folders needed if they're missing
+    mkdirSync(path.dirname(writePath), { recursive: true });
+    const writer = createWriteStream(writePath);
+    try {
+        const response = await axios.get(imageSrc, {
+            responseType: "stream",
+        });
+        // wx prevents overwriting an image with the exact same name
+        // being created in the time we were downloading
+        response.data.pipe(writer, {
+            flag: "wx",
+        });
+        return new Promise((resolve, reject) => {
+            writer.on("finish", () => resolve(undefined));
+            writer.on("error", reject);
+        });
+    }
+    catch (e) {
+        return Promise.reject({
+            code: "ENOTFOUND",
+        });
+    }
+}
+export function isValidImageSrc(src) {
+    if (!src) {
+        return false;
+    }
+    // We do not support downloading base64 in-line images.
+    if (src.startsWith("data:")) {
+        return false;
+    }
+    const imageHref = removeMetadataFromImageSrc(src);
+    const ext = getFileExtension(imageHref);
+    if (ext && !SUPPORTED_MEDIA_EXTENSIONS.includes(ext)) {
+        console.error("🚨 We do not support the file extension: " + ext);
+        return false;
+    }
+    return true;
+}
+export function removeMetadataFromImageSrc(src) {
+    // Part of the URL standard
+    const metadataSymbols = ["?", "#"];
+    metadataSymbols.forEach((dividerSymbol) => {
+        // Some frameworks add metadata after the file extension, we need to remove that.
+        src = src.split(dividerSymbol)[0];
+    });
+    return src;
+}
+export function cleanImageSrc(src, origin) {
+    // Add origin if the image tags are using relative sources
+    return src.startsWith("http") ? src : new URL(src, origin).href;
+}
+export default async function downloadImage(imageSrc, writePath, overwrite = false) {
+    await writeImageToFile(imageSrc, writePath, overwrite)
+        .then(() => {
+        console.log("🖼️ - " + writePath);
+    })
+        .catch((e) => {
+        if (e.code === "EEXIST") {
+            console.log(`❌ Skipping existing image ${writePath}`);
+        }
+        else if (e.code === "ENOTFOUND") {
+            console.error(`🚨 Cannot download the image, address not found ${imageSrc}`);
+        }
+        else {
+            console.error(e);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import dev from "./local-preview/index.js";
+import prod from "./local-preview/prod.js";
+import installDepsCommand from "./local-preview/helper-commands/installDepsCommand.js";
+export { dev, prod, installDepsCommand };

package/dist/index.js

@@ -0,0 +1,4 @@
+import dev from "./local-preview/index.js";
+import prod from "./local-preview/prod.js";
+import installDepsCommand from "./local-preview/helper-commands/installDepsCommand.js";
+export { dev, prod, installDepsCommand };

package/dist/local-preview/helper-commands/installDepsCommand.d.ts

@@ -0,0 +1,2 @@
+declare const installDeps: () => Promise<void>;
+export default installDeps;

package/dist/local-preview/helper-commands/installDepsCommand.js

@@ -0,0 +1,11 @@
+import shell from "shelljs";
+import { CLIENT_PATH } from "../../constants.js";
+import { buildLogger, ensureYarn } from "../../util.js";
+const installDeps = async () => {
+    const logger = buildLogger("");
+    ensureYarn(logger);
+    shell.cd(CLIENT_PATH);
+    shell.exec("yarn");
+    logger.succeed("Dependencies installed.");
+};
+export default installDeps;

package/dist/local-preview/index.d.ts

@@ -0,0 +1,3 @@
+import { ArgumentsCamelCase } from "yargs";
+declare const dev: (argv: ArgumentsCamelCase) => Promise<void>;
+export default dev;

package/dist/local-preview/index.js

@@ -0,0 +1,159 @@
+// @ts-nocheck
+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 { getConfigPath } from "./listener/utils/mintConfigFile.js";
+const nodeModulesExists = async () => {
+    // return pathExists(path.join(DOT_MINTLIFY, "mint", "client", "node_modules"));
+    return pathExists(path.join(DOT_MINTLIFY, "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) => {
+    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));
+    // 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) => {
+    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) => {
+    buildLogger("DEVS");
+    shell.cd(HOME_DIR);
+    await promptForYarn();
+    const logger = buildLogger("Preparing local Docsalot 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 instance is ready. Launching your site...");
+    run(argv.port || "3000");
+};
+const run = (port) => {
+    shell.cd(CLIENT_PATH);
+    console.log("CLIENT PATH", CLIENT_PATH);
+    // For Cloud Run/Docker, use dev-host (binds to 0.0.0.0, no file watching)
+    // For local development, use dev-watch (binds to localhost, with file watching)
+    const isProduction = process.env.BIND_ALL_INTERFACES === "true";
+    const devScript = isProduction ? "npm run dev-host" : "npm run dev-watch";
+    const mintlifyDevProcess = child_process.spawn(devScript, {
+        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/dist/local-preview/listener/categorize.d.ts

@@ -0,0 +1,8 @@
+import { PotentialFileCategory } from "./utils/types.js";
+export declare const categorizeFiles: (contentDirectoryPath: string) => Promise<{
+    contentFilenames: string[];
+    staticFilenames: string[];
+    openApiFiles: OpenApiFile[];
+    snippets: string[];
+}>;
+export declare const getCategory: (filePath: string) => PotentialFileCategory;

package/dist/local-preview/listener/categorize.js

@@ -0,0 +1,96 @@
+// TODO - put in prebuild package
+// @ts-nocheck
+import path from "path";
+import { getFileList } from "@docsalot/prebuild";
+import { getFileExtension, openApiCheck } from "./utils.js";
+export const categorizeFiles = async (contentDirectoryPath) => {
+    const allFilesInCmdExecutionPath = 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) => {
+    filePath = filePath.toLowerCase();
+    const parsed = path.parse(filePath);
+    if (parsed.base === "mint.json" || parsed.base === "layout.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/dist/local-preview/listener/generate.d.ts

@@ -0,0 +1,12 @@
+type DecoratedMintNavigation = DecoratedMintNavigationEntry[];
+type DecoratedMintNavigationEntry = {
+    group: string;
+    version?: string;
+    pages: DecoratedMintNavigationEntryChild[];
+};
+type DecoratedMintNavigationEntryChild = DecoratedMintNavigationEntry | PageMetadata;
+type PageMetadata = Record<PageMetadataKeys, string>;
+declare const pageMetadataKeys: readonly ["title", "description", "sidebarTitle", "href", "api", "openapi", "contentType", "auth", "version", "mode", "hideFooterPagination", "authors", "lastUpdatedDate", "createdDate", "size"];
+type PageMetadataKeys = typeof pageMetadataKeys[number];
+export declare const generateNav: () => Promise<DecoratedMintNavigation>;
+export {};

package/dist/local-preview/listener/generate.js

@@ -0,0 +1,73 @@
+// 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;
+const pageMetadataKeys = [
+    "title",
+    "description",
+    "sidebarTitle",
+    "href",
+    "api",
+    "openapi",
+    "contentType",
+    "auth",
+    "version",
+    "mode",
+    "hideFooterPagination",
+    "authors",
+    "lastUpdatedDate",
+    "createdDate",
+    "size",
+];
+const generateDecoratedMintNavigationFromPages = (filenamePageMetadataMap, mintConfigNav) => {
+    const filenames = Object.keys(filenamePageMetadataMap);
+    const createNav = (nav) => {
+        return {
+            group: nav.group,
+            version: nav?.version,
+            pages: nav.pages.map((page) => {
+                if (typeof page === "string" && filenames.includes(page)) {
+                    return filenamePageMetadataMap[page];
+                }
+                return createNav(page);
+            }),
+        };
+    };
+    return mintConfigNav.map((nav) => createNav(nav));
+};
+const createFilenamePageMetadataMap = async (contentDirectoryPath, contentFilenames, openApiFiles, clientPath, 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 [filenamePageMetadataMap, configObj] = await Promise.all([
+        createFilenamePageMetadataMap(CMD_EXEC_PATH, contentFilenames, openApiFiles),
+        getConfigObj(CMD_EXEC_PATH),
+    ]);
+    return generateDecoratedMintNavigationFromPages(filenamePageMetadataMap, configObj?.navigation);
+};

package/dist/local-preview/listener/index.d.ts

@@ -0,0 +1,2 @@
+declare const listener: () => void;
+export default listener;