@mintlify/previewing 3.0.2 → 3.0.3

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,0BAA0B,CAAC;AAC3C,OAAO,kBAAkB,MAAM,uDAAuD,CAAC;AAEvF,OAAO,EAAE,GAAG,EAAE,kBAAkB,EAAE,CAAC"}

package/package.json

@@ -1,32 +1,41 @@
 {
   "name": "@mintlify/previewing",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Preview Mintlify docs locally",
   "engines": {
     "node": ">=18.0.0"
   },
-  "license": "Elastic-2.0",
-  "scripts": {
-    "prepare": "npm run build",
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "lint": "eslint . --cache"
-  },
   "author": "Mintlify, Inc.",
   "repository": {
     "type": "git",
     "url": "https://github.com/mintlify/mint",
     "directory": "packages/mintlify-previewing"
   },
+  "bugs": {
+    "url": "https://github.com/mintlify/mint/issues"
+  },
+  "license": "Elastic-2.0",
+  "keywords": [
+    "mintlify",
+    "mint",
+    "previewing"
+  ],
+  "type": "module",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "exports": "./bin/index.js",
-  "bin": {
-    "mintlify-preview": "bin/index.js"
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "lint": "eslint . --cache"
   },
-  "type": "module",
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
     "@mintlify/validation": "^0.1.9",

package/.eslintignore

@@ -1 +0,0 @@
-bin/

package/.eslintrc.json

@@ -1,3 +0,0 @@
-{
-  "extends": "@mintlify/eslint-config-typescript"
-}

package/CONTRIBUTING.md

@@ -1,17 +0,0 @@
-# Running CLI Locally
-
-Note - contributing requires `yarn` and it's recommended you install it as a global installation. If you don't have yarn installed already run `npm install --global yarn` in your terminal.
-
-Run `npm run local` to build and install the CLI locally.
-
-You need to run the command after every change you want to test.
-
-## Updating Version of Mint Client
-
-The CLI uses GitHub releases to download specific versions of the client code used in `mintlify dev`. Older CLI versions will continue using the client code they were bundled with. Users need to update to a newer version of the CLI to get the newest client code. CLI contributors bump the client version used by the CLI whenever there are major changes.
-
-Here's how to publish new client changes to the CLI:
-
-1. Publish a new GitHub release. You can click the releases menu at the right of the repo page. Make the release title the same as the new release tag. Optionally, you can also use the description to keep track of what changed in that release.
-2. Set `TARGET_MINT_VERSION` in `src/constants.ts` to to the new release tag.
-3. Publish a new CLI version to npm.

package/bin/index.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable @typescript-eslint/no-empty-function */
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-import dev from "./local-preview/index.js";
-import installDepsCommand from "./local-preview/helper-commands/installDepsCommand.js";
-yargs(hideBin(process.argv))
-    .command("dev", "Runs Mintlify locally (Must run in directory with mint.json)", () => { }, async (argv) => {
-    await dev(argv);
-})
-    .command("install", "Install dependencies for local Mintlify", () => { }, installDepsCommand)
-    // Print the help menu when the user enters an invalid command.
-    .strictCommands()
-    .demandCommand(1, "Unknown command. See above for the list of supported commands.")
-    // Alias option flags --help = -h, --version = -v
-    .alias("h", "help")
-    .alias("v", "version")
-    .parse();
-//# sourceMappingURL=index.js.map

package/bin/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,yDAAyD;AAEzD,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,GAAG,MAAM,0BAA0B,CAAC;AAC3C,OAAO,kBAAkB,MAAM,uDAAuD,CAAC;AAEvF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACzB,OAAO,CACN,KAAK,EACL,8DAA8D,EAC9D,GAAG,EAAE,GAAE,CAAC,EACR,KAAK,EAAE,IAAI,EAAE,EAAE;IACb,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC,CACF;KACA,OAAO,CACN,SAAS,EACT,yCAAyC,EACzC,GAAG,EAAE,GAAE,CAAC,EACR,kBAAkB,CACnB;IACD,+DAA+D;KAC9D,cAAc,EAAE;KAChB,aAAa,CACZ,CAAC,EACD,gEAAgE,CACjE;IAED,iDAAiD;KAChD,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC;KAClB,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC;KAErB,KAAK,EAAE,CAAC"}

package/scraper.md

@@ -1,121 +0,0 @@
-# CLI Scraping
-
-The CLI has many commands. This doc focuses on how we coded scraping websites.
-
-## User Interface
-
-There are two main commands:
-
-`mintlify scrape-page [url]`
-
-and
-
-`mintlify scrape-section [url]`
-
-Scraping a page downloads a single page’s content. Scraping a section goes through the navigation and scrapes each page. The code for downloading a page’s content is shared between the two commands.
-
-Important files: `scraping/scrapePageCommands.ts`, `scraping/scrapeSectionAutomatically.ts`
-
-We have `scrape-gitbook-page` and similar commands for debugging. Ignore them, they just call internal functions directly. You should not need to use them unless you are debugging issues with Detecting Frameworks.
-
-## Overwriting
-
-The user has to add a `--overwrite` flag if they want to overwrite their current files.
-
-## Sections vs Websites
-
-We call the command `scrape-section` instead of `scrape-website` because we cannot scrape pages not in the navigation of the URL first passed in. For example, ReadMe has API Reference and other sections accessible through a separate top-navigation which we do not parse. We only scrape the navigation on the left: [https://docs.readme.com/main/docs](https://docs.readme.com/main/docs)
-
-## Detecting Frameworks
-
-The commands look in the page HTML to detect what framework scraper to use. For example, all Docusaurus sites have a metatag with the word Docusaurus in it. Some times, the metatag even has the Docusaurus version.
-
-Each framework’s scrapers live in `scraping/site-scrapers/`
-
-We currently support:
-
-- Docusaurus
-- GitBook
-- ReadMe
-- Intercom
-
-## Terminal Output
-
-We print a line in the terminal for every file we write. `util.ts` has a createPage function that takes care of writing the file and logging.
-
-We use a pencil emoji when we successfully write a file. Images get a picture emoji. Likewise, we print a X emoji when we find a file that already exists and the user has not enabled overwriting files. We use emojis so you can tell what the command is doing without reading each file path.
-
-We also print the file paths when scraping sections so the user can easily copy paste them into mint.json. Note that pages the user already added in Mintlify are not included in the printed example. We do not generate mint.json completely, we are just giving a small example to help users starting from scratch.
-
-```jsx
-Add the following to your navigation in mint.json:
-
-{
-   "group": "Guides",
-   "pages": ["page-we-scraped"]
-}
-```
-
-# Navigation Scraping
-
-Most sites use JavaScript to open navigation menus which do not automatically include the menu buttons in the HTML. We use Puppeteer to click every nested menu so the site adds the menu buttons to the HTML. For example the original site’s HTML:
-
-```jsx
-<div>
-  <a id="my-nested-menu"></a>
-</div>
-```
-
-can turn into this after opening the nested menu:
-
-```jsx
-<div>
-  <a id="my-nested-menu" aria-expanded=true></a>
-  <div>
-     <a href="/page"></a>
-     <a href="/other-page"></a>
-  </div>
-</div>
-```
-
-Ultimately, all section scrapers need to find an array of links to visit then call the scrape page function in a loop.
-
-We use axios instead of Puppeteer if a site doesn’t hide links. Puppeteer is slow.
-
-# Image File Locations
-
-Images go in an `images/` folder because that’s what most users want. Scraping per section uses the same root-level images folder. Scraping per page downloads them to the current location. Thus, scraping a single page from a folder means the user always has to move the images themselves. That’s a trade-off we are comfortable with — trying to detect an existing images folder gets too complicated too fast.
-
-# Cheerio
-
-Cheerio is a library to scrape/handle the HTML after we have it in a string. Most of the work is using inspect-element to view a website and figure out where the content we want is, then writing the corresponding Cheerio code.
-
-# HTML to MDX
-
-We use an open-source library to convert HTML to Markdown: https://github.com/crosstype/node-html-markdown
-
-The `util.ts` createPage function assembles the MDX metadata, we just need to return an object of the form `{ title, description, content }` from each page scraper.
-
-## Parsing Issues
-
-Parsing struggles when documentation websites are using non-standard HTML. For example, code blocks are supposed to use. `<pre><code></code></pre>` but GitBook just uses divs.
-
-We can write custom translators for the library that determine how we parse certain objects.
-
-In some cases, we will want custom translators even if parsing succeeds. For example, ReadMe callouts are using quote syntax
-
-```jsx
-> 💡
-> Callout text
->
-```
-
-When we want to convert them to:
-
-```jsx
-<Tip>Callout text</Tip>
-```
-
-## Regex
-
-You can use regex to make small changes where translators are overkill or there’s no obvious component to modify. For example, here’s the end of `scrapeDocusaurusPage.ts`:

package/src/constants.ts

@@ -1,40 +0,0 @@
-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();
-
-export const DOT_MINTLIFY = path.join(HOME_DIR, ".mintlify");
-
-export const VERSION_PATH = path.join(DOT_MINTLIFY, "mint", "mint-version.txt");
-
-export const CLIENT_PATH = path.join(DOT_MINTLIFY, "mint", "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/src/downloadImage.ts

@@ -1,102 +0,0 @@
-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: string,
-  writePath: string,
-  overwrite: boolean
-) {
-  // 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);
-      writer.on("error", reject);
-    });
-  } catch (e) {
-    return Promise.reject({
-      code: "ENOTFOUND",
-    });
-  }
-}
-
-export function isValidImageSrc(src: string) {
-  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: string) {
-  // 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: string, origin: string) {
-  // 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: string,
-  writePath: string,
-  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/src/index.ts

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable @typescript-eslint/no-empty-function */
-
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-import dev from "./local-preview/index.js";
-import installDepsCommand from "./local-preview/helper-commands/installDepsCommand.js";
-
-yargs(hideBin(process.argv))
-  .command(
-    "dev",
-    "Runs Mintlify locally (Must run in directory with mint.json)",
-    () => {},
-    async (argv) => {
-      await dev(argv);
-    }
-  )
-  .command(
-    "install",
-    "Install dependencies for local Mintlify",
-    () => {},
-    installDepsCommand
-  )
-  // Print the help menu when the user enters an invalid command.
-  .strictCommands()
-  .demandCommand(
-    1,
-    "Unknown command. See above for the list of supported commands."
-  )
-
-  // Alias option flags --help = -h, --version = -v
-  .alias("h", "help")
-  .alias("v", "version")
-
-  .parse();

package/src/local-preview/helper-commands/installDepsCommand.ts

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