From db9da499cc07ee11265b35fb963825061e82b20e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 20 Dec 2024 17:41:47 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- advanced/subpath/cloudflare.mdx | 55 +-- integrations/analytics/overview.mdx | 514 ++-------------------------- integrations/privacy/overview.mdx | 6 +- migration.mdx | 143 ++------ quickstart.mdx | 187 +++------- 5 files changed, 102 insertions(+), 803 deletions(-) diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 763b44eda..22767539f 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -7,46 +7,20 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx"; -## Create Cloudflare Worker +## Setup Instructions -Navigate to the `Workers & Pages > Create application > Create worker`. You -should be able to presented with the following screen where you can create a new -Cloudlfare worker. +1. Create a Cloudflare Worker at `Workers & Pages > Create application > Create worker` - - Create a Cloudflare worker - +2. Configure Custom Domain + - Go to worker `Settings > Triggers` + - Click `Add Custom Domain` + - Add your domain (both with and without `www.`) -### Add custom domain - -Once the worker is created, click `Configure worker`. Navigate to the worker -`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain -into the list - we recommend you add both the version with and without `www.` -prepended to the domain. - - - Cloudflare worker custom domain - - -If you have trouble setting up a custom subdirectory, -[contact our support team](mailto:sales@mintlify.com) and we'll walk you through -upgrading your hosting with us. - -### Edit Worker Script - -Click on `Edit Code` and add the following script into the worker's code. - - - Cloudflare edit code - - - - Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and - `CUSTOM_URL` with your website's base URL. - +3. Add Worker Script + - Click `Edit Code` + - Paste the script below + - Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values + - Click `Deploy` ```javascript addEventListener("fetch", (event) => { @@ -56,9 +30,7 @@ addEventListener("fetch", (event) => { async function handleRequest(request) { try { const urlObject = new URL(request.url); - // If the request is to the docs subdirectory if (/^\/docs/.test(urlObject.pathname)) { - // Then Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; const CUSTOM_URL = "[YOUR_DOMAIN]"; @@ -66,7 +38,6 @@ async function handleRequest(request) { url.hostname = DOCS_URL; let proxyRequest = new Request(url, request); - proxyRequest.headers.set("Host", DOCS_URL); proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); proxyRequest.headers.set("X-Forwarded-Proto", "https"); @@ -74,11 +45,9 @@ async function handleRequest(request) { return await fetch(proxyRequest); } } catch (error) { - // if no action found, play the regular request return await fetch(request); } } ``` -Click on `Deploy` and wait for the changes to propagate (it can take up to a few -hours). +Note: Changes may take a few hours to propagate. For setup assistance, [contact our support team](mailto:sales@mintlify.com). \ No newline at end of file diff --git a/integrations/analytics/overview.mdx b/integrations/analytics/overview.mdx index dff95d35a..4784dccd2 100644 --- a/integrations/analytics/overview.mdx +++ b/integrations/analytics/overview.mdx @@ -10,514 +10,48 @@ description: "Integrate with an analytics platform to track viewer events" horizontal icon={ - - }> - - - - - - - - } -> - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - - - - - - } -> - - - - - - } -> - - - - - -} - -> - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - + } /> - } /> - } + /> + - - -}> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - } -> - - - - - - } -> - - - - - - - - - } -/> - ## Enabling Analytics -Set your analytics keys in `mint.json`. You can add an unlimited number of analytics integrations for free. - -The syntax for `mint.json` is below. You only need to include entries for the platforms you want to connect. +Add your analytics keys in `mint.json` to enable tracking. You can integrate with multiple platforms simultaneously. - - -```json Analytics options in mint.json +```json Analytics Configuration "analytics": { "amplitude": { "apiKey": "required" }, - "clearbit": { - "publicApiKey": "required" - }, - "fathom": { - "siteId": "required" - }, "ga4": { "measurementId": "required" }, - "gtm": { - "tagId": "required" - }, - "hotjar": { - "hjid": "required", - "hjsv": "required" - }, - "koala": { - "publicApiKey": "required" - }, - "logrocket": { - "appId": "required" - }, "mixpanel": { "projectToken": "required" }, - "pirsch": { - "id": "required" - }, - "plausible": { - "domain": "required" - }, - "posthog": { - "apiKey": "required", - "apiHost": "optional" - }, -} -``` - -```json Google Analytics 4 Example -"analytics": { - "ga4": { - "measurementId": "G-XXXXXXX" - } + // Additional platforms: + // clearbit, fathom, gtm, hotjar, koala, + // logrocket, pirsch, plausible, posthog } ``` - \ No newline at end of file +For platform-specific setup instructions, select the relevant integration card above. \ No newline at end of file diff --git a/integrations/privacy/overview.mdx b/integrations/privacy/overview.mdx index 737baebe5..dcb3e1a79 100644 --- a/integrations/privacy/overview.mdx +++ b/integrations/privacy/overview.mdx @@ -13,9 +13,9 @@ description: "Integrate with a data privacy platform" -## Enabling Data Privacy Integrations +## Setup -You can add data privacy platforms onto your docs. Add the `integrations` field into your `mint.json` file with your respective scripts. +Add the `integrations` field to your `mint.json`: ```json "integrations": { @@ -23,4 +23,4 @@ You can add data privacy platforms onto your docs. Add the `integrations` field } ``` -If you'd like to request a data privacy platform integration, please let us know in [our community](https://mintlify.com/community). +Need a different privacy platform? Request it in [our community](https://mintlify.com/community). \ No newline at end of file diff --git a/migration.mdx b/migration.mdx index 491e89454..f6cb20a17 100644 --- a/migration.mdx +++ b/migration.mdx @@ -4,141 +4,44 @@ description: 'How to migrate documentation from your existing provider' icon: 'arrow-up-from-bracket' --- -You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to scrape documentation frameworks to Mintlify. +Easily migrate your existing documentation to Mintlify using our automated scraping tools. -We currently support migration for: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +## Supported Providers - - - - - - - - - - - -} /> - - -} /> - - -} /> + + } /> + } /> + } /> -Don't see your docs provider or have a home grown system? We can still help! Please get in touch at sales@mintlify.com. - -## Commands +Don't see your provider? Contact sales@mintlify.com for custom migration support. -- `mintlify-scrape section [url]` - Scrapes multiple pages in a site. -- `mintlify-scrape page [url]` - Scrapes a single page in a site. +## Quick Start +Install the package: -The commands will automatically detect the framework. - -## 🚀 Installation - -First, install the package: - -``` +```bash npm i @mintlify/scraping ``` -One-time use: - -```bash Section -npx @mintlify/scraping@latest section [url] -``` +## Usage -```bash Page -npx @mintlify/scraping@latest page [url] -``` - +Two main commands are available: -Global installation: +```bash +# Scrape multiple pages +npx @mintlify/scraping section [url] +# Scrape single page +npx @mintlify/scraping page [url] ``` -npm install @mintlify/scraping@latest -g -``` - -Global usage: - - -```bash Section -mintlify-scrape section [url] -``` - -```bash Page -mintlify-scrape page [url] -``` - - -Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. +For OpenAPI specifications: +```bash +npx @mintlify/scraping openapi-file [filename] ``` -mintlify-scrape openapi-file [openApiFilename] --w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true] --o, --outDir The folder in which to write any created frontmatter files [string] -``` \ No newline at end of file +Options: +- `-w, --writeFiles` - Write frontmatter files (default: true) +- `-o, --outDir` - Output directory for generated files \ No newline at end of file diff --git a/quickstart.mdx b/quickstart.mdx index fc6eb786c..d85828b61 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -17,165 +17,58 @@ icon: "rocket" ## Getting Started -Welcome! Follow the instructions below to learn how to deploy, update and -supercharge your documentation with Mintlify. +Follow these steps to set up and customize your documentation with Mintlify. -### Creating the Repository +### Step 1: Create Your Documentation Repository -Mintlify docs are rendered from MDX files and configurations defined in our -[starter kit](https://github.com/mintlify/starter). We use GitHub to integrate -your docs with your code, and make source control effortless. +1. Use our [starter kit](https://github.com/mintlify/starter) to create your documentation repository +2. Install our [GitHub app](https://dashboard.mintlify.com/settings) for automatic deployments - - - - If you've created a docs repo in our onboarding, this step is complete. You can find your docs repository on your Mintlify [dashboard](https://dashboard.mintlify.com). - - To create your docs repo without logging into GitHub, follow these instructions: - 1. Clone our [starter template](https://github.com/mintlify/starter) into a new public repo. You can make the repo private later. - 2. [Get in touch](mailto:support@mintlify.com) with our team to deploy your repo. - - - ![Starter Template](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/starter-template.png) - - - - - - - The next step is to install our GitHub app. This ensures that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository. - - - ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) - - - - - +### Step 2: Edit Your Content -### Updating the Content - -Mintlify enables you to easily customize the style, structure, and content of -your docs. +Choose your preferred editing method: - - - 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - 2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - 3. Use your favorite IDE to open the repository. - 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`. + + 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + 2. Clone your repository: `git clone ` + 3. Install Mintlify CLI: `npm i -g mintlify` - Learn more about this in our [local development guide](/development). - + See our [local development guide](/development) for more details. - - - Learn more about how to use the web editor on our [guide](/web-editor). - - - - - - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: - - ```json - "name": "Your Company" - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg", - "href": "https://yourcompany.com" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#2AB673", - "light": "#55D799", - "dark": "#117866", - }, - ``` - - A full list of supported configurations can be found at [global settings](/settings/global). - - - - - - Add content with simple MDX files. Initiate your pages with this template: - - ```md - --- - title: "Page Title" - sidebarTitle: "Sidebar title (optional - if different from page title)" - description: "Subtitle (optional)" - --- - ``` - - Learn more about adding images, tables, lists, and more using the [MDX syntax](/text). We also offer a [wide array of components](/content/components). - - - - - - Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com). - - - ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) - - - - - - - You can easily set up your API references using an OpenAPI document. - - 1. Add your `openapi.yaml` or `openapi.json` file into your docs repository or define the `openapi` field in `mint.json` with a URL. - - ```json - "openapi": "link-to-your-openapi-file" - ``` - - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: - - ```bash - npx @mintlify/scraping@latest openapi-file - ``` - - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. - - For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview). - - - - - - Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). - - We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). - + + Use our web-based editor to make quick changes. Learn more in our [web editor guide](/web-editor). - - We provide a white-glove migration service as part of our Enterprise plan. - Interested? You can request it by [contacting us](mailto:sales@mintlify.com). - - -### Publishing - - - - Integrate your docs into your website by hosting them on a custom domain. This is included even in the free plan. - - Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/settings) to add a custom domain. +### Step 3: Customize Your Docs + +1. Configure your brand in `mint.json`: +```json +{ + "name": "Your Company", + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "colors": { + "primary": "#2AB673" + } +} +``` + +2. Add content using MDX files: +```md +--- +title: "Page Title" +description: "Description" +--- +``` - - ![Custom Domain](/images/custom-domain.png) - +### Step 4: Deploy - +1. Push your changes to GitHub for automatic deployment +2. Add a custom domain through your [dashboard settings](https://dashboard.mintlify.com/settings) -Congrats! You've set up your Mintlify Docs and it's looking amazing! Need -support or want to give some feedback? You can join our -[community](https://mintlify.com/community) or drop us an email at -[support@mintlify.com](mailto:support@mintlify.com). +Need help? Join our [community](https://mintlify.com/community) or contact [support@mintlify.com](mailto:support@mintlify.com). \ No newline at end of file