mintlify 1.0.7 → 1.0.8

package/bin/mint/client/scripts/local.js

@@ -0,0 +1,177 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+import favicons from 'favicons';
+import { promises as _promises } from 'fs';
+import pkg, { remove } from 'fs-extra';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+import faviconConfig from '../prebuild/faviconConfig.js';
+import { createPage, injectNav } from '../prebuild/injectNav.js';
+
+const { outputFileSync, readFileSync } = pkg;
+const { readdir, readFile } = _promises;
+
+const path = process.argv[2] ?? '../docs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const getFileList = async (dirName, og = dirName) => {
+  let files = [];
+  const items = await readdir(resolve(dirName), { withFileTypes: true });
+
+  for (const item of items) {
+    if (item.isDirectory()) {
+      files = [...files, ...(await getFileList(`${dirName}/${item.name}`, og))];
+    } else {
+      files.push(`${dirName}/${item.name}`);
+    }
+  }
+
+  return files;
+};
+
+const getFiles = async () => {
+  const fileList = await getFileList(path);
+  const markdownFiles = [];
+  const staticFiles = [];
+  let config = undefined;
+  let openApi = undefined;
+  const promises = [];
+  fileList.forEach((filename) => {
+    promises.push(
+      (async () => {
+        const content = await readFile(resolve(filename));
+        if (filename.endsWith('mint.config.json') || filename.endsWith('mint.json')) {
+          config = content;
+          return;
+        }
+        const absolutePath = filename.substring(path.length + 1);
+        const extension =
+          filename.substring(filename.lastIndexOf('.') + 1, filename.length) || filename;
+        if (extension && (extension === 'mdx' || extension === 'md' || extension === 'tsx')) {
+          markdownFiles.push({
+            path: absolutePath,
+            content: Buffer.from(content, 'base64'),
+          });
+          return;
+        }
+
+        if (extension === 'json' || extension === 'yaml' || extension === 'yml') {
+          try {
+            outputFileSync('openapi', Buffer.from(content, 'base64').toString('utf-8'));
+            const api = await SwaggerParser.validate('openapi');
+            openApi = Buffer.from(JSON.stringify(api, null, 2), 'utf-8');
+          } catch {
+            // not valid openApi
+          }
+        }
+        // every other file
+        staticFiles.push({
+          path: absolutePath,
+          content: Buffer.from(content, 'base64'),
+        });
+      })()
+    );
+  });
+  await Promise.all(promises);
+  return { markdownFiles, staticFiles, config, openApi };
+};
+
+const injectMarkdownFilesAndNav = (markdownFiles, configObj, openApiObj) => {
+  let pages = {};
+  markdownFiles.forEach((markdownFile) => {
+    const path = __dirname + `/../src/pages/${markdownFile.path}`;
+    const page = createPage(markdownFile.path, markdownFile.content, openApiObj);
+    if (page != null) {
+      pages = {
+        ...pages,
+        ...page,
+      };
+    }
+    outputFileSync(path, Buffer.from(markdownFile.content), { flag: 'w' });
+  });
+
+  console.log(`📄  ${markdownFiles.length} pages injected`);
+
+  injectNav(pages, configObj);
+};
+
+const injectStaticFiles = (staticFiles) => {
+  staticFiles.forEach((staticFile) => {
+    const path = __dirname + `/../public/${staticFile.path}`;
+    outputFileSync(path, Buffer.from(staticFile.content), { flag: 'w' });
+  });
+
+  console.log(`📄  ${staticFiles.length} static files injected`);
+};
+
+const injectConfig = (config) => {
+  const path = __dirname + `/../src/mint.json`;
+  outputFileSync(path, Buffer.from(config), { flag: 'w' });
+  console.log('⚙️  Config file set properly');
+};
+
+const injectOpenApi = (openApi) => {
+  const path = __dirname + `/../src/openapi.json`;
+  if (openApi) {
+    outputFileSync(path, Buffer.from(openApi), { flag: 'w' });
+    console.log('🖥️  OpenAPI file detected and set as openapi.json');
+    return;
+  }
+  outputFileSync(path, '{}', { flag: 'w' });
+};
+
+const injectFavicons = async (config) => {
+  const buffer = Buffer.from(config);
+  const configJSON = JSON.parse(buffer.toString());
+
+  if (configJSON?.favicon == null) return;
+
+  const desiredPath = resolve(__dirname + `/../public/${configJSON.favicon}`);
+  const favicon = readFileSync(desiredPath);
+  if (favicon == null) return;
+  console.log('Generating favicons...');
+  favicons(favicon, faviconConfig(config?.name), (err, response) => {
+    if (err) {
+      console.log(err.message); // Error description e.g. "An unknown error has occurred"
+      return;
+    }
+    response.images.forEach((img) => {
+      const path = __dirname + `/../public/favicons/${img.name}`;
+      outputFileSync(path, Buffer.from(img.contents), { flag: 'w' });
+    });
+    response.files.forEach((file) => {
+      const path = __dirname + `/../public/favicons/${file.name}`;
+      outputFileSync(path, file.contents, { flag: 'w' });
+    });
+    console.log('Favicons generated');
+  });
+};
+
+const deleteExistingOpenApi = async () => {
+  const path = __dirname + '/../openapi';
+  await remove(path);
+};
+
+const getAllFilesAndConfig = async () => {
+  await deleteExistingOpenApi();
+  const { markdownFiles, staticFiles, config, openApi } = await getFiles();
+  const openApiObj = openApi == null ? null : JSON.parse(openApi.toString());
+  const configObj = JSON.parse(config.toString());
+  injectMarkdownFilesAndNav(markdownFiles, configObj, openApiObj);
+  injectStaticFiles(staticFiles);
+  injectOpenApi(openApi);
+  injectConfig(config);
+  injectFavicons(config);
+};
+
+(async function () {
+  try {
+    console.log('🔍  Fetching files');
+    await getAllFilesAndConfig();
+  } catch (error) {
+    console.log(error);
+    console.error('⚠️   Error while prebuilding documents');
+  }
+})();

package/bin/mint/client/sentry.client.config.js

@@ -0,0 +1,15 @@
+// This file configures the initialization of Sentry on the browser.
+// The config you add here will be used whenever a page is visited.
+// https://docs.sentry.io/platforms/javascript/guides/nextjs/
+
+import * as Sentry from '@sentry/nextjs';
+
+const SENTRY_DSN = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;
+
+if (process.env.VERCEL_ENV === 'production') {
+  Sentry.init({
+    dsn: SENTRY_DSN || 'https://817b9178a3aa4a01b57a91160d3a24bb@o1352345.ingest.sentry.io/6633662',
+    tracesSampleRate: 0.05,
+    enabled: process.env.VERCEL_ENV === 'production',
+  });
+}

package/bin/mint/client/sentry.properties

@@ -0,0 +1,4 @@
+defaults.url=https://sentry.io/
+defaults.org=mintlify
+defaults.project=docs-frontend
+cli.executable=../../../.npm/_npx/a8388072043b4cbc/node_modules/@sentry/cli/bin/sentry-cli

package/bin/mint/client/sentry.server.config.js

@@ -0,0 +1,15 @@
+// This file configures the initialization of Sentry on the server.
+// The config you add here will be used whenever the server handles a request.
+// https://docs.sentry.io/platforms/javascript/guides/nextjs/
+
+import * as Sentry from '@sentry/nextjs';
+
+const SENTRY_DSN = process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN;
+
+if (process.env.VERCEL_ENV === 'production') {
+  Sentry.init({
+    dsn: SENTRY_DSN || 'https://817b9178a3aa4a01b57a91160d3a24bb@o1352345.ingest.sentry.io/6633662',
+    tracesSampleRate: 0.05,
+    enabled: process.env.VERCEL_ENV === 'production',
+  });
+}

package/bin/mint/client/src/analytics/AbstractAnalyticsImplementation.ts

@@ -0,0 +1,50 @@
+export type AmplitudeConfigInterface = {
+  apiKey?: string;
+};
+
+export type FathomConfigInterface = {
+  siteId?: string;
+};
+
+export type GoogleAnalyticsConfigInterface = {
+  measurementId?: string;
+};
+
+export type HotjarConfigInterface = {
+  hjid?: string;
+  hjsv?: string;
+};
+
+export type MixpanelConfigInterface = {
+  projectToken?: string;
+};
+
+export type PostHogConfigInterface = {
+  apiKey?: string;
+  apiHost?: string;
+};
+
+// We can use & instead of | because all keys are optional
+export type ConfigInterface = AmplitudeConfigInterface &
+  FathomConfigInterface &
+  GoogleAnalyticsConfigInterface &
+  HotjarConfigInterface &
+  MixpanelConfigInterface &
+  PostHogConfigInterface;
+
+// TypeScript doesn't recommend setting interfaces on constructors.
+// How an object is constructed should not matter because an interface
+// only cares about what it does.
+export abstract class AbstractAnalyticsImplementation {
+  // New implementations need their own config interface.
+  abstract init(implementationConfig: ConfigInterface): void;
+  createEventListener(eventName: string): (eventProperties: object) => Promise<void> {
+    return async function doNothing(_: object) {};
+  }
+  onRouteChange(url: string, routeProps: any): void {}
+}
+
+export type AnalyticsMediatorInterface = {
+  createEventListener: (eventName: string) => (eventConfig: object) => Promise<void>;
+  onRouteChange: (url: string, routeProps: any) => void;
+};

package/bin/mint/client/src/analytics/AnalyticsContext.ts

@@ -0,0 +1,5 @@
+import { createContext } from 'react';
+import { AnalyticsMediatorInterface } from './AbstractAnalyticsImplementation';
+
+const AnalyticsContext = createContext({} as AnalyticsMediatorInterface);
+export default AnalyticsContext;

package/bin/mint/client/src/analytics/AnalyticsMediator.ts

@@ -0,0 +1,101 @@
+import * as Sentry from '@sentry/nextjs';
+
+import {
+  AmplitudeConfigInterface,
+  AbstractAnalyticsImplementation,
+  AnalyticsMediatorInterface,
+  FathomConfigInterface,
+  HotjarConfigInterface,
+  MixpanelConfigInterface,
+  PostHogConfigInterface,
+  GoogleAnalyticsConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+import PostHogAnalytics from '@/analytics/implementations/posthog';
+
+import AmplitudeAnalytics from './implementations/amplitude';
+import FathomAnalytics from './implementations/fathom';
+import GA4Analytics from './implementations/ga4';
+import HotjarAnalytics from './implementations/hotjar';
+import MixpanelAnalytics from './implementations/mixpanel';
+
+export type AnalyticsMediatorConstructorInterface = {
+  amplitude?: AmplitudeConfigInterface;
+  fathom?: FathomConfigInterface;
+  ga4?: GoogleAnalyticsConfigInterface;
+  hotjar?: HotjarConfigInterface;
+  mixpanel?: MixpanelConfigInterface;
+  posthog?: PostHogConfigInterface;
+};
+
+export default class AnalyticsMediator implements AnalyticsMediatorInterface {
+  analyticsIntegrations: AbstractAnalyticsImplementation[] = [];
+
+  constructor(analytics?: AnalyticsMediatorConstructorInterface) {
+    // Ran first so we can assign the Sentry tags to false when not set.
+    const amplitudeEnabled = Boolean(analytics?.amplitude?.apiKey);
+    const fathomEnabled = Boolean(analytics?.fathom?.siteId);
+    const ga4Enabled = Boolean(analytics?.ga4?.measurementId);
+    const hotjarEnabled = Boolean(analytics?.hotjar?.hjid && analytics?.hotjar?.hjsv);
+    const mixpanelEnabled = Boolean(analytics?.mixpanel?.projectToken);
+    const posthogEnabled = Boolean(analytics?.posthog?.apiKey);
+    Sentry.setTag('amplitude_enabled', `${amplitudeEnabled}`);
+    Sentry.setTag('fathom_enabled', `${fathomEnabled}`);
+    Sentry.setTag('ga4_enabled', `${ga4Enabled}`);
+    Sentry.setTag('hotjar_enabled', `${hotjarEnabled}`);
+    Sentry.setTag('mixpanel_enabled', `${mixpanelEnabled}`);
+    Sentry.setTag('posthog_enabled', `${posthogEnabled}`);
+
+    if (!analytics || Object.keys(analytics).length === 0) {
+      return;
+    }
+
+    if (amplitudeEnabled) {
+      const amplitude = new AmplitudeAnalytics();
+      amplitude.init(analytics.amplitude!);
+      this.analyticsIntegrations.push(amplitude);
+    }
+
+    if (fathomEnabled) {
+      const fathom = new FathomAnalytics();
+      fathom.init(analytics.fathom!);
+      this.analyticsIntegrations.push(fathom);
+    }
+
+    if (ga4Enabled) {
+      const ga4 = new GA4Analytics();
+      ga4.init(analytics.ga4!);
+      this.analyticsIntegrations.push(ga4);
+    }
+
+    if (hotjarEnabled) {
+      const hotjar = new HotjarAnalytics();
+      hotjar.init(analytics.hotjar!);
+      this.analyticsIntegrations.push(hotjar);
+    }
+
+    if (posthogEnabled) {
+      const posthog = new PostHogAnalytics();
+      posthog.init(analytics.posthog!);
+      this.analyticsIntegrations.push(posthog);
+    }
+
+    if (mixpanelEnabled) {
+      const mixpanel = new MixpanelAnalytics();
+      mixpanel.init(analytics.mixpanel!);
+      this.analyticsIntegrations.push(mixpanel);
+    }
+  }
+
+  createEventListener(eventName: string) {
+    const listeners = this.analyticsIntegrations.map((integration) =>
+      integration.createEventListener(eventName)
+    );
+    return async function (eventConfig: object) {
+      listeners.forEach((listener) => listener(eventConfig));
+    };
+  }
+
+  onRouteChange(url: string, routeProps: any) {
+    this.analyticsIntegrations.forEach((integration) => integration.onRouteChange(url, routeProps));
+  }
+}

package/bin/mint/client/src/analytics/FakeAnalyticsMediator.ts

@@ -0,0 +1,9 @@
+import { AnalyticsMediatorInterface } from './AbstractAnalyticsImplementation';
+
+export default class FakeAnalyticsMediator implements AnalyticsMediatorInterface {
+  createEventListener(_: string) {
+    return async function () {};
+  }
+
+  onRouteChange(_: string, __: any) {}
+}

package/bin/mint/client/src/analytics/GA4Script.tsx

@@ -0,0 +1,33 @@
+import Script from 'next/script';
+
+import { GoogleAnalyticsConfigInterface } from './AbstractAnalyticsImplementation';
+
+export default function GA4Script({ ga4 }: { ga4?: GoogleAnalyticsConfigInterface }) {
+  if (!ga4?.measurementId || process.env.NODE_ENV !== 'production') {
+    return null;
+  }
+
+  // There is no npm package for Google Analytics 4 so set up happens by placing this script.
+  // We can send events using window.gtag.
+  return (
+    <>
+      <Script
+        strategy="afterInteractive"
+        src={`https://www.googletagmanager.com/gtag/js?id=${ga4.measurementId}`}
+      />
+      <Script
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{
+          __html: `
+            window.dataLayer = window.dataLayer || [];
+            function gtag(){dataLayer.push(arguments);}
+            gtag('js', new Date());
+            gtag('config', '${ga4.measurementId}', {
+              page_path: window.location.pathname,
+            });
+          `,
+        }}
+      />
+    </>
+  );
+}

package/bin/mint/client/src/analytics/implementations/amplitude.ts

@@ -0,0 +1,26 @@
+import { init as amplitudeInit, track } from '@amplitude/analytics-browser';
+
+import {
+  AbstractAnalyticsImplementation,
+  ConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+
+export default class AmplitudeAnalytics extends AbstractAnalyticsImplementation {
+  initialized = false;
+
+  init(implementationConfig: ConfigInterface) {
+    if (implementationConfig?.apiKey && process.env.NODE_ENV === 'production') {
+      amplitudeInit(implementationConfig.apiKey);
+      this.initialized = true;
+    }
+  }
+
+  createEventListener(eventName: string) {
+    if (this.initialized) {
+      return async function capture(eventProperties: object) {
+        track(eventName, eventProperties);
+      };
+    }
+    return async function doNothing(_: object) {};
+  }
+}

package/bin/mint/client/src/analytics/implementations/fathom.ts

@@ -0,0 +1,38 @@
+import * as Sentry from '@sentry/nextjs';
+
+import {
+  AbstractAnalyticsImplementation,
+  ConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+
+export default class FathomAnalytics extends AbstractAnalyticsImplementation {
+  initialized = false;
+  trackPageview: any;
+
+  init(implementationConfig: ConfigInterface) {
+    if (implementationConfig.siteId && process.env.NODE_ENV === 'production') {
+      import('fathom-client')
+        .then((_fathom) => {
+          if (!this.initialized) {
+            _fathom.load(implementationConfig.siteId!);
+
+            // The Fathom library uses asterisk imports (ie. * as Fathom)
+            // so there is no default export for us to store a reference to.
+            // Instead, we keep a reference to the method we need.
+            this.trackPageview = _fathom.trackPageview;
+
+            this.initialized = true;
+          }
+        })
+        .catch((e) => {
+          Sentry.captureException(e);
+        });
+    }
+  }
+
+  onRouteChange(_: string, routeProps: any) {
+    if (this.trackPageview && !routeProps.shallow) {
+      this.trackPageview();
+    }
+  }
+}

package/bin/mint/client/src/analytics/implementations/ga4.ts

@@ -0,0 +1,33 @@
+import {
+  AbstractAnalyticsImplementation,
+  ConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+
+export default class GA4Analytics extends AbstractAnalyticsImplementation {
+  measurementId: string | undefined;
+
+  init(implementationConfig: ConfigInterface) {
+    // GA4 setup happens by placing GA4Script.
+    // This implementation only exists to send custom events using window.gtag.
+    if (process.env.NODE_ENV === 'production') {
+      this.measurementId = implementationConfig.measurementId;
+    }
+  }
+
+  createEventListener(eventName: string) {
+    if (this.measurementId && (window as any).gtag) {
+      return async function capture(_: object) {
+        (window as any).gtag('event', eventName, {});
+      };
+    }
+    return async function doNothing(_: object) {};
+  }
+
+  onRouteChange(url: string): void {
+    if (this.measurementId && (window as any).gtag) {
+      (window as any).gtag('config', this.measurementId, {
+        page_path: url,
+      });
+    }
+  }
+}

package/bin/mint/client/src/analytics/implementations/hotjar.ts

@@ -0,0 +1,53 @@
+import * as Sentry from '@sentry/nextjs';
+
+import {
+  AbstractAnalyticsImplementation,
+  ConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+
+export default class HotjarAnalytics extends AbstractAnalyticsImplementation {
+  initialized = false;
+
+  // Store events to submit after the library is loaded.
+  waitTracking: string[] = [];
+  hotjar = {
+    event: (name: string) => this.waitTracking.push(name),
+  } as any;
+
+  init(implementationConfig: ConfigInterface) {
+    if (
+      implementationConfig?.hjid &&
+      implementationConfig?.hjsv &&
+      process.env.NODE_ENV === 'production'
+    ) {
+      const hjid = parseInt(implementationConfig.hjid, 10);
+      const hjsv = parseInt(implementationConfig.hjsv, 10);
+
+      import('react-hotjar')
+        .then((_hotjar) => {
+          if (!this.initialized) {
+            // Get default module export
+            this.hotjar = _hotjar;
+            this.hotjar.initialize(hjid, hjsv);
+            this.initialized = true;
+
+            this.waitTracking.forEach((eventName) => {
+              this.hotjar.event(eventName);
+            });
+          }
+
+          return this.hotjar;
+        })
+        .catch((e) => {
+          Sentry.captureException(e);
+        });
+    }
+  }
+
+  createEventListener(eventName: string) {
+    const captureFunc = async function capture(this: HotjarAnalytics, _: object) {
+      this.hotjar.event(eventName);
+    };
+    return captureFunc.bind(this);
+  }
+}

package/bin/mint/client/src/analytics/implementations/mixpanel-browser.d.ts

@@ -0,0 +1 @@
+declare module 'mixpanel-browser';

package/bin/mint/client/src/analytics/implementations/mixpanel.ts

@@ -0,0 +1,52 @@
+import * as Sentry from '@sentry/nextjs';
+
+import {
+  AbstractAnalyticsImplementation,
+  ConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+
+export default class MixpanelAnalytics extends AbstractAnalyticsImplementation {
+  initialized = false;
+
+  // Store events to submit after the library is loaded.
+  waitTracking: { name: string; properties: object }[] = [];
+  mixpanel = {
+    track: (name: string, properties: object) => this.waitTracking.push({ name, properties }),
+  } as any;
+
+  init(implementationConfig: ConfigInterface) {
+    if (implementationConfig.projectToken && process.env.NODE_ENV === 'production') {
+      // Dynamic import reduces our First Load JS by 18 kB
+      import('mixpanel-browser')
+        .then((_mixpanel) => {
+          if (!this.initialized) {
+            // Get default module export
+            const mixpanelLib = _mixpanel.default;
+            mixpanelLib.init(implementationConfig.projectToken, {
+              secure_cookie: true,
+            });
+
+            this.initialized = true;
+            this.mixpanel = mixpanelLib;
+
+            this.waitTracking.forEach((event) => {
+              this.mixpanel.track(event.name, event.properties);
+            });
+          }
+        })
+        .catch((e) => {
+          Sentry.captureException(e);
+        });
+    } else {
+      // Stop storing events, we don't need them because the library will not be loaded.
+      this.mixpanel.track = (_name: string, _properties: object) => {};
+    }
+  }
+
+  createEventListener(eventName: string) {
+    const captureFunc = async function capture(this: MixpanelAnalytics, eventProperties: object) {
+      this.mixpanel.track(eventName, eventProperties);
+    };
+    return captureFunc.bind(this);
+  }
+}

package/bin/mint/client/src/analytics/implementations/posthog.ts

@@ -0,0 +1,37 @@
+import Router from 'next/router';
+import posthog from 'posthog-js';
+
+import {
+  AbstractAnalyticsImplementation,
+  ConfigInterface,
+} from '@/analytics/AbstractAnalyticsImplementation';
+
+export default class PostHogAnalytics extends AbstractAnalyticsImplementation {
+  initialized = false;
+
+  init(implementationConfig: ConfigInterface) {
+    if (implementationConfig.apiKey && !this.initialized) {
+      this.initialized = true;
+      // apiHost only has to be passed in if the user is self-hosting PostHog
+      posthog.init(implementationConfig.apiKey, {
+        api_host: implementationConfig.apiHost || 'https://app.posthog.com',
+        loaded: (posthogInstance) => {
+          if (process.env.NODE_ENV !== 'production') posthogInstance.opt_out_capturing();
+        },
+      });
+
+      // Track page views
+      const handleRouteChange = () => posthog.capture('$pageview');
+      Router.events.on('routeChangeComplete', handleRouteChange);
+    }
+  }
+
+  createEventListener(eventName: string) {
+    if (this.initialized) {
+      return async function capture(eventProperties: object) {
+        posthog.capture(eventName, eventProperties);
+      };
+    }
+    return async function doNothing(_: object) {};
+  }
+}