From 26c568b0c7fd819677f0700bf4d418d4b28cf591 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 7 May 2026 18:16:46 -0700 Subject: [PATCH 1/2] update help center and product guide --- .../getting-started/billing/compare-plans.mdx | 39 +++--- help-center/getting-started/billing/index.mdx | 6 +- .../billing/invoices-receipts.mdx | 34 +++--- .../billing/upgrade-downgrade.mdx | 31 +++-- .../getting-started/create-account.mdx | 35 +++--- help-center/getting-started/index.mdx | 6 +- .../integrations/connect-crm.mdx | 46 +++---- .../integrations/connect-slack.mdx | 42 ++++--- .../integrations/developer/api-keys.mdx | 38 +++--- .../integrations/developer/index.mdx | 6 +- .../integrations/developer/oauth-apps.mdx | 40 ++++--- .../integrations/developer/webhooks.mdx | 36 +++--- .../getting-started/integrations/index.mdx | 8 +- .../partners/custom-connector-template.mdx | 48 +++++--- .../integrations/partners/hubspot.mdx | 47 ++++---- .../integrations/partners/index.mdx | 8 +- .../integrations/partners/salesforce.mdx | 51 ++++---- help-center/getting-started/quickstart.mdx | 35 +++--- .../getting-started/sign-in-security.mdx | 40 +++---- .../getting-started/workspace/index.mdx | 8 +- .../workspace/invite-teammates.mdx | 42 ++++--- .../workspace/organization-settings.mdx | 38 +++--- .../workspace/roles-permissions.mdx | 39 +++--- help-center/index.mdx | 52 ++++---- .../automation/advanced/idempotency.mdx | 60 +++++++--- .../product/automation/advanced/index.mdx | 8 +- .../automation/advanced/rate-limits.mdx | 38 +++--- .../automation/advanced/retry-policies.mdx | 41 ++++--- help-center/product/automation/index.mdx | 8 +- .../product/automation/rules-triggers.mdx | 41 ++++--- .../product/automation/scheduled-tasks.mdx | 63 +++++++--- .../workflows/build-first-workflow.mdx | 51 ++++---- .../workflows/conditions-branches.mdx | 46 ++++--- .../automation/workflows/error-handling.mdx | 61 ++++++---- .../product/automation/workflows/index.mdx | 8 +- .../product/editor/comments-mentions.mdx | 45 ++++--- .../product/editor/drafts-publishing.mdx | 34 +++--- help-center/product/editor/index.mdx | 8 +- .../product/editor/version-history.mdx | 45 ++++--- help-center/product/index.mdx | 6 +- help-center/product/interface-overview.mdx | 38 +++--- help-center/product/keyboard-shortcuts.mdx | 46 +++---- .../product/projects/archive-restore.mdx | 46 ++++--- .../product/projects/create-project.mdx | 48 ++++---- help-center/product/projects/index.mdx | 6 +- help-center/product/search-navigation.mdx | 38 +++--- .../support/account-data/delete-account.mdx | 41 ++++--- .../support/account-data/export-data.mdx | 38 +++--- help-center/support/account-data/index.mdx | 6 +- help-center/support/contact-support.mdx | 56 +++++---- help-center/support/index.mdx | 6 +- help-center/support/legal/index.mdx | 6 +- help-center/support/legal/privacy/dpa.mdx | 35 +++--- help-center/support/legal/privacy/index.mdx | 8 +- .../support/legal/privacy/privacy-policy.mdx | 37 +++--- .../support/legal/privacy/subprocessors.mdx | 37 +++--- help-center/support/legal/regions/apac.mdx | 28 ++--- .../support/legal/regions/eu-residency.mdx | 32 ++--- help-center/support/legal/regions/index.mdx | 8 +- .../support/legal/regions/us-residency.mdx | 28 ++--- .../support/legal/terms-of-service.mdx | 35 ++++-- help-center/support/status-incidents.mdx | 36 ++++-- help-center/support/troubleshooting/index.mdx | 6 +- .../support/troubleshooting/login-issues.mdx | 43 ++++--- .../troubleshooting/performance-issues.mdx | 45 ++++--- product-guide/analytics/connect-data.mdx | 99 +++++++++------- .../analytics/dashboards/create-dashboard.mdx | 56 ++++----- product-guide/analytics/quickstart.mdx | 58 +++++---- .../analytics/reports/scheduled-reports.mdx | 73 +++++++----- product-guide/index.mdx | 38 +++--- product-guide/integrations/authentication.mdx | 56 ++++----- product-guide/integrations/connectors/crm.mdx | 68 ++++++----- product-guide/integrations/quickstart.mdx | 50 ++++---- .../integrations/webhooks/configure.mdx | 112 ++++++++++-------- .../administration/roles-permissions.mdx | 57 ++++----- .../platform/configuration/settings.mdx | 90 +++++++++----- .../configuration/user-management.mdx | 50 ++++---- product-guide/platform/key-concepts.mdx | 74 ++++++++---- product-guide/platform/quickstart.mdx | 47 ++++---- 79 files changed, 1704 insertions(+), 1315 deletions(-) diff --git a/help-center/getting-started/billing/compare-plans.mdx b/help-center/getting-started/billing/compare-plans.mdx index 200ce25..2f4e4a3 100644 --- a/help-center/getting-started/billing/compare-plans.mdx +++ b/help-center/getting-started/billing/compare-plans.mdx @@ -1,35 +1,34 @@ --- -title: "Compare plans" +title: "Compare Mintlify plans" sidebarTitle: "Compare plans" -description: "Feature matrix across Free, Team, and Enterprise tiers for this demo help center." +description: "Feature comparison across Mintlify's Starter, Growth, and Enterprise plans." --- -Plans bundle limits, support, and compliance features. Use this page to shortlist options before legal review—exact numbers change, but the pattern usually holds: pay for seats, automation volume, and the audit artifacts you need. +Mintlify offers plans for teams at every stage. All plans include unlimited pages, deployments, and the full component library. -## Highlights +## Plan highlights -- **Free** — Core projects and limited automation runs. Best for evaluation and tiny teams with light automation. -- **Team** — SSO options, higher limits, and priority email support. Common step after product-market fit when coordination overhead grows. -- **Enterprise** — Regional options, advanced audit, and dedicated support channels. Typical when procurement, security questionnaires, or data residency enter the conversation. - -### Hidden costs - -Count integrations, API volume, and retained history—not just seats. A team on paper may exceed automation quotas during a busy quarter. +- **Starter** — One project, community support, and `*.mintlify.app` hosting. Best for individuals and early-stage products getting their first docs site live. +- **Growth** — Multiple projects, custom domains, analytics, AI search, password protection, and priority support. The right tier for most teams shipping a real product. +- **Enterprise** — SSO, audit logs, SLA guarantees, custom contracts, dedicated support, and advanced security controls. For teams with procurement, compliance, or data residency requirements. ## How to choose -Start where your current limits hurt first—usually automation volume or member count—then add Enterprise when procurement or compliance requires it. +Start with Starter to validate the workflow, then upgrade when you need custom domains, analytics, or team collaboration features. Upgrade to Enterprise when security questionnaires, SSO, or a signed DPA enter the conversation. -### Proof points +## Common questions -Before upgrading, reproduce one painful workflow in a trial project and measure time saved. Finance teams respond to minutes per week reclaimed, not feature lists alone. +**Can I use a custom domain on Starter?** +Custom domains require the Growth plan or above. -## Pilot checklist +**Does Mintlify charge per seat?** +Mintlify pricing is project-based, not per seat — you can invite as many editors as you need without per-user fees. -- Confirm how many seats you truly need after removing inactive accounts. -- List must-have integrations and confirm they are included or priced as add-ons. -- Align legal and security on DPA, subprocessors, and data residency before you sign. +**Can I try Growth features before upgrading?** +Contact [support](mailto:support@mintlify.com) to request a trial of Growth features for your team. -## When to revisit +## Before upgrading -Re-evaluate plans at major milestones: funding rounds, geographic expansion, or a spike in automation usage after a new workflow goes live. Annual true-ups catch drift between contract and reality. +- Confirm your repository setup and first deployment are working on Starter. +- Check whether you need a custom domain, analytics, or AI search — those are the main Growth additions. +- For Enterprise, loop in your legal and security teams early — DPA review and SSO setup add lead time. diff --git a/help-center/getting-started/billing/index.mdx b/help-center/getting-started/billing/index.mdx index 21bd16f..d888332 100644 --- a/help-center/getting-started/billing/index.mdx +++ b/help-center/getting-started/billing/index.mdx @@ -1,9 +1,9 @@ --- title: "Billing and plans" sidebarTitle: "Overview" -description: "Plans, invoices, and upgrades for your workspace." +description: "Mintlify plans, pricing, and how billing works for your organization." --- -Billing is tied to your organization. This section explains how plans compare, how changes propagate, and where to find invoices. +Mintlify billing is tied to your organization. One subscription covers all projects under the organization, and all Admins can access billing settings. -If you need a custom agreement, contact sales from the billing page—dummy numbers here are for demonstration only. \ No newline at end of file +Use the articles in this section to compare plans, manage your subscription, and find invoices. diff --git a/help-center/getting-started/billing/invoices-receipts.mdx b/help-center/getting-started/billing/invoices-receipts.mdx index 162fb19..18dc0cb 100644 --- a/help-center/getting-started/billing/invoices-receipts.mdx +++ b/help-center/getting-started/billing/invoices-receipts.mdx @@ -1,31 +1,35 @@ --- title: "Invoices and receipts" sidebarTitle: "Invoices & receipts" -description: "Download invoices, update tax details, and reconcile charges." +description: "Download invoices, update billing information, and reconcile charges." --- -Finance teams need clean paper trails: invoices for accruals, receipts for reimbursements, and tax IDs that match what is on file with vendors. Keep addresses and VAT numbers current before month-end close. +Invoices and payment history are available to Admins in **Settings → Billing → Invoices**. -## Where to find invoices +## Download invoices -Navigate to **Settings → Billing → Invoices** for PDF copies and line items. Download CSV or structured exports if your ERP ingests them automatically. +Each invoice is available as a PDF with a line-item breakdown. Click **Download** next to any invoice in the invoice list. -### Line items +Invoices include: +- Billing period +- Plan name and quantity +- Prorated charges or credits for plan changes mid-cycle +- Tax if applicable based on your billing address -Verify seat counts and add-ons against internal headcount reports. Discrepancies often trace to deactivated users still occupying paid seats until the next true-up. +### Updating your billing address or tax ID -## Tax and VAT +Update your billing details in **Settings → Billing → Billing information** before your next renewal. Mintlify can reissue invoices if your tax ID was missing at the time of the charge — contact [support](mailto:support@mintlify.com) with the invoice number and the correct details. -Update tax IDs before renewal to avoid delays. This demo does not constitute tax advice—run final numbers past your accounting partner, especially for cross-border entities. - -### Reverse charge and treaties +## Receipts -Document which party remits VAT or sales tax for each entity. Store evidence with the invoice PDF for audit readiness. +Stripe sends an email receipt to your billing address after each successful charge. Receipts are suitable for expense reporting. -## Receipts +If the receipt didn't arrive, check your billing email's spam folder, or download the invoice PDF from the dashboard — both contain the charge amount and date. -Card charges include a receipt link suitable for expense tools that accept emailed PDFs. Forward receipts immediately after charge—matching six months later is painful. +## Failed payments -### Corporate cards +If a charge fails, Mintlify retries automatically and notifies the billing contact by email. Update your payment method in **Settings → Billing → Payment method** before the retry window closes to avoid service interruption. -If the cardholder rotates, update billing profiles so receipts reach the person who must attest to expenses. + + Mintlify uses Stripe for payment processing. If your finance team needs Stripe's supplier information for vendor onboarding, contact [support](mailto:support@mintlify.com). + diff --git a/help-center/getting-started/billing/upgrade-downgrade.mdx b/help-center/getting-started/billing/upgrade-downgrade.mdx index f01fd3c..076135e 100644 --- a/help-center/getting-started/billing/upgrade-downgrade.mdx +++ b/help-center/getting-started/billing/upgrade-downgrade.mdx @@ -1,31 +1,36 @@ --- title: "Upgrade or downgrade your plan" sidebarTitle: "Upgrade or downgrade" -description: "Change plans, proration, and limit changes for subscriptions." +description: "How plan changes work, what happens to your features, and when changes take effect." --- -Plan changes affect billing, feature gates, and sometimes data retention. Read the fine print on your order form—this article describes typical patterns for illustration only. +Plan changes are made by an Admin in **Settings → Billing**. ## Upgrade -Upgrades take effect immediately in this template content. Proration is calculated against your billing cycle for illustration. +Upgrades take effect immediately. You gain access to the new plan's features right away, and your card is charged a prorated amount for the remainder of the current billing period. -### Capacity planning +### After upgrading -After upgrading, revisit automation and storage settings—you may need to raise internal quotas now that platform limits moved. - -### Communication - -Tell finance when upgrades happen mid-cycle so invoices match purchase orders. Link to the order confirmation in your ticket. +- **Custom domains** — You can configure custom domains for your projects right after upgrading. +- **Analytics** — The analytics dashboard becomes available immediately. Historical data from before the upgrade is not backfilled. +- **AI search** — Enable AI search per project in project settings after upgrading to Growth. ## Downgrade -Downgrades apply at the next renewal unless your contract states otherwise. Features above the new cap become read-only until you adjust usage. +Downgrades take effect at the end of your current billing period. Until then, you continue to have access to all current plan features. -### Export first +When the downgrade takes effect: +- Custom domains are disabled — your site will redirect to its `*.mintlify.app` URL. +- Analytics and AI search features become unavailable. +- The site itself stays live and deployments continue. -Download critical exports before downgrade if retention windows shrink. You cannot always rely on grace periods for compliance archives. +### Before downgrading + +Export any analytics data you want to keep — historical data is not accessible after downgrading. ## Billing contacts -Ensure finance and IT stakeholders are copied on invoices if your organization requires it. Rotate contacts when owners change roles—stale addresses delay tax validation and payment. +Make sure the billing email on file in **Settings → Billing** is monitored. Invoices, receipts, and renewal notices go to that address. + +If your billing contact changes (someone leaves, finance wants a shared inbox), update the billing email before the next renewal cycle. diff --git a/help-center/getting-started/create-account.mdx b/help-center/getting-started/create-account.mdx index 916ab5d..03fac70 100644 --- a/help-center/getting-started/create-account.mdx +++ b/help-center/getting-started/create-account.mdx @@ -1,32 +1,37 @@ --- -title: "Create your account" +title: "Create your Mintlify account" sidebarTitle: "Create account" -description: "Sign up, verify your email, and choose the right organization type for your team." +description: "Sign up, connect your Git provider, and set up your organization." --- -Creating an account should take minutes. The decisions that matter—company vs personal workspace, who pays, and which email domain owns the org—are easier to correct now than after you have invited dozens of people. +Getting started with Mintlify takes a few minutes. The key decisions — which Git provider to use, who manages billing, and how your organization is named — are easiest to get right up front. ## Sign up -Visit the signup page and enter your work email. We send a one-time link to verify ownership of the address. Links expire; request a fresh one if your inbox is slow. +Go to [mintlify.com/start](https://mintlify.com/start) and sign up with your work email or GitHub account. If you sign up with email, we send a verification link — check your spam folder if it doesn't arrive within a minute. -### Domains and policy +### Work email vs GitHub -Some companies block consumer email providers. If signup fails silently, try your corporate domain or ask IT to allow the notification sender. +Signing up with GitHub is faster and connects your account to your repositories immediately. Work email is preferred if your organization has SSO policies that require it. -## Organization type +## Create your organization -- **Company** — Multiple teams under one billing profile. Choose this when finance expects a single invoice and you want shared administration. -- **Personal** — Individual use with the option to upgrade later. Appropriate for evaluation before you commit a legal entity. +After signing in, you'll be prompted to create an organization. Your organization name appears in the Mintlify dashboard and in email notifications to teammates. -### Switching later +- Use a recognizable name — your company name or product name work well. +- Avoid internal codenames if external collaborators will see it. -Moving between types may require support or export/import if your product separates billing identities. When in doubt, start as **Company** if you know you will onboard a team within a month. +## Connect your Git provider -## Verification issues +Mintlify deploys from your Git repository. During setup, you'll install the Mintlify GitHub App (or connect GitLab). Grant it access to the repositories you plan to use for documentation. -If the email does not arrive within a few minutes, check spam folders and ensure your IT allowlist includes notification domains. Corporate filters sometimes delay the first message more than subsequent ones. + + You can install the GitHub App on an individual account or a GitHub organization. If your docs repository belongs to a GitHub organization, install the app on that organization so all members can collaborate. + -### Shared inboxes +## Verification issues -Avoid signing up with distribution lists—you lose account recovery if nobody owns the mailbox. Prefer a named admin who can delegate later. +If the verification email doesn't arrive: +- Check your spam and promotions folders. +- Ask your IT team whether the Mintlify sender domain is filtered. +- Try signing up with GitHub instead if email delivery is unreliable in your environment. diff --git a/help-center/getting-started/index.mdx b/help-center/getting-started/index.mdx index 6f0143d..a06ae69 100644 --- a/help-center/getting-started/index.mdx +++ b/help-center/getting-started/index.mdx @@ -1,9 +1,9 @@ --- title: "Getting started" sidebarTitle: "Overview" -description: "Create your account, secure access, and connect the product to the tools your team already uses." +description: "Create your account, deploy your first docs site, and connect your team in minutes." --- -Welcome. This section walks you through account setup, your workspace, billing, and integrations so you can get productive quickly. +Welcome to Mintlify. This section covers everything you need to go from signup to a live, deployed docs site with your team contributing. -Use the articles below to go deeper—each guide is written for busy teams who need clear steps without fluff. \ No newline at end of file +Use the articles below to move at your own pace — most teams are live within an hour. diff --git a/help-center/getting-started/integrations/connect-crm.mdx b/help-center/getting-started/integrations/connect-crm.mdx index 2eef772..7cc7f8d 100644 --- a/help-center/getting-started/integrations/connect-crm.mdx +++ b/help-center/getting-started/integrations/connect-crm.mdx @@ -1,32 +1,38 @@ --- -title: "Connect your CRM" -sidebarTitle: "CRM" -description: "Link Salesforce or HubSpot through partner connectors or a custom sync strategy." +title: "Connect your repository" +sidebarTitle: "Repository" +description: "How Mintlify connects to GitHub and GitLab to deploy your docs." --- -CRM integrations keep customer context next to internal work. The hardest part is agreeing which system owns which field—decide that before you flip the sync on. +Mintlify deploys directly from your Git repository. Connecting your repository is the first step to getting your docs site live. -## Supported paths +## GitHub -- Official partner connectors (see partner guides) -- CSV or API-based sync via developer tools + + + During signup (or from **Settings → Integrations → GitHub**), click **Install GitHub App**. Choose the GitHub organization or personal account where your docs repository lives. -### When to use each + Grant the app access to the specific repository (or all repositories, if you prefer). Mintlify only reads your repository content — it does not write to your repo. + + + After installing the app, return to the Mintlify dashboard and select the repository to use for your project. Mintlify clones the repo and starts the first build. + + + By default, Mintlify deploys from your repository's default branch (usually `main`). You can change the deployment branch in **Project Settings → Git**. + + -Partner connectors trade flexibility for speed. Custom sync suits unusual object models or heavy transformations mid-pipeline. +## GitLab -## Data expectations +GitLab integration uses a webhook instead of an app: -Define which objects sync and how conflicts resolve. Document owner fields so automation behaves predictably. +1. In your Mintlify project settings, go to **Settings → Git → GitLab**. +2. Copy the provided webhook URL and secret. +3. In your GitLab repository, go to **Settings → Webhooks** and add the URL and secret. +4. Enable the **Push events** trigger. -### Conflict rules +Mintlify will deploy whenever you push to the configured branch. -“CRM wins” vs “product wins” should be explicit for every field. Ambiguity shows up first when sales reassigns accounts during a territory change. +## Monorepos -## Privacy - -Limit synced fields to the minimum needed for your workflows and review access regularly. - -### Retention - -Align deletion policies: when a CRM record disappears, decide whether related artifacts should archive, anonymize, or remain linked for audits. +If your documentation lives in a subdirectory of a larger repository, set the **Docs root** in **Project Settings → Git** to the path of the subdirectory (for example, `docs/`). Mintlify will treat that directory as the root of your docs site. diff --git a/help-center/getting-started/integrations/connect-slack.mdx b/help-center/getting-started/integrations/connect-slack.mdx index 3c9f3e4..7625925 100644 --- a/help-center/getting-started/integrations/connect-slack.mdx +++ b/help-center/getting-started/integrations/connect-slack.mdx @@ -1,31 +1,41 @@ --- -title: "Connect Slack" +title: "Slack notifications" sidebarTitle: "Slack" -description: "Install the Slack app, pick channels, and manage notifications." +description: "Get deployment notifications and alerts in your Slack workspace." --- -Slack puts updates where people already work. A disciplined channel strategy keeps signal high—one noisy channel trains everyone to mute the integration entirely. +Connect Mintlify to Slack to receive notifications about deployments, failed builds, and other project activity directly in your channels. -## Install +## Set up Slack notifications -From **Integrations → Slack**, authorize the workspace you use every day. You need admin approval if your Slack org restricts apps. +Mintlify can send deployment status updates to Slack via a webhook. The most common setup routes these through GitHub or GitLab Actions. -### Scopes +### Using GitHub Actions -Review requested OAuth scopes during install. If something looks broader than needed, ask your Slack admin whether a reduced app configuration exists. +Add a Slack notification step to your CI workflow that fires after Mintlify deploys: -## Channels +```yaml +- name: Notify Slack on deploy + uses: slackapi/slack-github-action@v1 + with: + payload: | + { + "text": "Docs deployed: ${{ github.event.head_commit.message }}" + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} +``` -Map events to public or private channels. Start with a low-noise channel for pilot testing. +Store your Slack webhook URL as a GitHub Actions secret (`SLACK_WEBHOOK_URL`) — never hardcode it in the workflow file. -### Naming +### Channel strategy -Use a consistent prefix (`#help-`, `#docs-`) so people can browse related channels. Archive pilot channels after go-live to reduce clutter. +- Use a dedicated `#docs-deploys` channel for deployment notifications — this keeps the signal separate from other engineering noise. +- Reserve `@channel` mentions for failed builds or broken links, not routine deploys. ## Troubleshooting -If messages stop, reauthorize the app and confirm the bot was not removed from the channel. - -### Rate limits - -Bursty events can hit Slack posting limits—back off or batch summaries if you see `429` responses in integration logs. +If notifications stop: +- Confirm the webhook URL is still valid — Slack deactivates webhook URLs when a workspace app is removed. +- Check whether the bot was removed from the target channel. +- Re-create the webhook in **Slack → Apps → Incoming Webhooks** if needed. diff --git a/help-center/getting-started/integrations/developer/api-keys.mdx b/help-center/getting-started/integrations/developer/api-keys.mdx index d2470a7..67a7e98 100644 --- a/help-center/getting-started/integrations/developer/api-keys.mdx +++ b/help-center/getting-started/integrations/developer/api-keys.mdx @@ -1,31 +1,37 @@ --- title: "API keys" sidebarTitle: "API keys" -description: "Create, rotate, and scope API keys for server-side automation." +description: "Generate and manage API keys for programmatic access to Mintlify." --- -API keys authenticate machine-to-machine calls. They are simpler than OAuth but easier to leak—never embed them in browsers or mobile apps. +Mintlify API keys allow you to interact with your docs programmatically — triggering deployments, managing content, and automating your docs workflow. -## Create keys +## Generate an API key -Generate keys with descriptive labels and store them in a secrets manager—never in client-side code. +1. Go to [dashboard.mintlify.com](https://dashboard.mintlify.com) and open your organization. +2. Go to **Settings → API keys**. +3. Click **New key**, give it a descriptive name (for example, `ci-deploy` or `content-automation`), and click **Create**. +4. Copy the key immediately — it won't be shown again after you close the dialog. -### Scoping +Store the key in your secrets manager (GitHub Actions Secrets, AWS Secrets Manager, HashiCorp Vault, etc.) — never hardcode it in source code or config files. -If your platform supports scoped keys, split read vs write access so a compromised read-only key cannot mutate data. +## Key naming -## Rotation - -Rotate keys on a schedule or immediately after someone leaves the team with access. +Use descriptive names that identify the service using the key: +- `github-actions-deploy` for CI/CD workflows +- `content-generator-production` for automated content tools -### Dual-key rotation +This makes it easy to identify and rotate the right key if credentials are compromised. -Issue a new key, deploy everywhere, verify traffic, then revoke the old key—avoids hard cutovers at midnight. - -## Revocation +## Rotation -Revoked keys stop working immediately. Update dependent services before revoking. +Rotate API keys regularly or immediately if you suspect exposure: -### Runbooks +1. Generate a new key in **Settings → API keys**. +2. Update the key in every system that uses it. +3. Verify the new key works in all dependent systems. +4. Revoke the old key. -Document which cron jobs and CI pipelines use which key so rotation does not miss a dusty integration. + + Revoking a key takes effect immediately. Update all dependent systems before revoking to avoid broken deployments or automation. + diff --git a/help-center/getting-started/integrations/developer/index.mdx b/help-center/getting-started/integrations/developer/index.mdx index 1ea69da..557c191 100644 --- a/help-center/getting-started/integrations/developer/index.mdx +++ b/help-center/getting-started/integrations/developer/index.mdx @@ -1,9 +1,9 @@ --- title: "Developer integrations" sidebarTitle: "Overview" -description: "OAuth apps, webhooks, and API keys for building on the platform." +description: "API keys, webhooks, and authentication options for building on Mintlify." --- -Developer integrations are for teams building custom workflows or connecting internal systems. +Developer integrations are for teams automating their docs workflow or connecting Mintlify to their own systems. -Use OAuth for user-delegated access, webhooks for reactive automation, and API keys for secure server-to-server calls. \ No newline at end of file +Use API keys for server-side automation, webhooks for event-driven triggers, and OAuth for user-delegated access in private docs setups. diff --git a/help-center/getting-started/integrations/developer/oauth-apps.mdx b/help-center/getting-started/integrations/developer/oauth-apps.mdx index ac24403..9da1e39 100644 --- a/help-center/getting-started/integrations/developer/oauth-apps.mdx +++ b/help-center/getting-started/integrations/developer/oauth-apps.mdx @@ -1,31 +1,39 @@ --- -title: "OAuth apps" -sidebarTitle: "OAuth apps" -description: "Register an OAuth client, scopes, and redirect URLs for the API." +title: "Authentication for private docs" +sidebarTitle: "Auth & OAuth" +description: "Restrict access to your docs site with password protection, SSO, or JWT tokens." --- -OAuth connects user-authorized clients to your APIs without sharing primary passwords. Treat client secrets like production credentials—rotate them and restrict who can create apps. +By default, Mintlify sites are publicly accessible. If your docs contain sensitive information — internal APIs, private playbooks, or unreleased product documentation — you can restrict access. -## Register an app +## Password protection -Create an application in **Developer settings** and note the client ID and secret. +The simplest option: set a password in **Project Settings → Authentication → Password**. Anyone visiting the site must enter the password before seeing any content. -### Environments +Password protection is available on Growth and Enterprise plans. -Maintain separate apps for staging and production so tokens never cross environments accidentally. +## SSO (SAML) -## Scopes +Connect your identity provider so readers must sign in with their company credentials. Available on Enterprise plans. -Request the smallest scope set that satisfies your feature. Review quarterly as APIs expand. +1. Go to **Project Settings → Authentication → SSO**. +2. Provide your IdP's metadata URL or XML. +3. Map the required attributes (email, name). +4. Enable SSO enforcement. -### User consent +Readers who aren't authenticated are redirected to your IdP's login page. -Write user-facing copy that explains why each scope is needed—reviewers and security questionnaires ask. +## JWT tokens -## Redirect URLs +For tighter integration with your own authentication system, Mintlify supports JWT-based authentication. Your backend generates a signed JWT that grants access to specific docs sections. -Use HTTPS endpoints and avoid wildcards in production. Register separate entries for staging and production. +This approach lets you: +- Show different content to different user tiers. +- Gate specific sections of your docs behind feature flags or subscription levels. +- Integrate with your own login system without requiring a separate IdP connection. -### PKCE +See the [Mintlify authentication documentation](https://mintlify.com/docs) for JWT format requirements and example implementations. -Prefer PKCE for public clients to reduce interception risk on mobile and SPA flows. + + All authentication options require the Growth or Enterprise plan. Starter sites are always publicly accessible. + diff --git a/help-center/getting-started/integrations/developer/webhooks.mdx b/help-center/getting-started/integrations/developer/webhooks.mdx index 7d9ab4b..3535c81 100644 --- a/help-center/getting-started/integrations/developer/webhooks.mdx +++ b/help-center/getting-started/integrations/developer/webhooks.mdx @@ -1,31 +1,35 @@ --- -title: "Webhooks" +title: "Deployment webhooks" sidebarTitle: "Webhooks" -description: "Subscribe to events, verify signatures, and retry safely." +description: "Trigger and receive events around Mintlify deployments." --- -Webhooks push events to your infrastructure so you can react without polling. Reliability hinges on verification, idempotency, and fast HTTP responses—treat the endpoint like a mini product. +Mintlify integrates with webhooks in two directions: it receives webhooks from GitHub and GitLab to trigger deployments, and you can configure outgoing webhooks to notify external systems when deployments complete. -## Subscriptions +## Incoming: GitHub and GitLab webhooks -Create a webhook endpoint and select event types. The platform sends a signing secret for HMAC verification. +Mintlify automatically configures a webhook on your repository when you connect it. Every push to your default branch (or a configured branch) triggers a new deployment. Pull request events trigger preview deployments. -### Filtering +You don't need to configure these manually — they're set up when you install the GitHub App or connect GitLab. -Subscribe only to events you handle. Unused events still cost verification CPU and clutter logs. +### Custom branch triggers -## Verification +By default, Mintlify deploys from your default branch. To change the branch or add additional triggers, go to **Project Settings → Git → Deployment triggers**. -Always validate signatures before processing payloads. Reject stale timestamps when present. +## Outgoing: deployment status notifications -### Clock skew +You can use GitHub Actions or GitLab CI to send notifications to external systems after a Mintlify deployment completes. -Allow a small clock skew window between signer and verifier, but bound it to limit replay windows. +A common pattern is to call a webhook endpoint after a successful push: -## Retries +```yaml +- name: Notify on deploy + run: | + curl -X POST https://your-endpoint.example.com/hooks/docs \ + -H "Content-Type: application/json" \ + -d '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}' +``` -Failed deliveries retry with exponential backoff. Ensure your endpoint is idempotent. +### Verifying payloads -### Response codes - -Return **2xx** only after you have safely persisted or handed off work. Use **5xx** to signal transient failures worth retrying; **4xx** for permanent misconfiguration. +If your endpoint receives events from GitHub (not just Mintlify), always validate the `X-Hub-Signature-256` header using your webhook secret before processing the payload. diff --git a/help-center/getting-started/integrations/index.mdx b/help-center/getting-started/integrations/index.mdx index e25bdf0..39b3039 100644 --- a/help-center/getting-started/integrations/index.mdx +++ b/help-center/getting-started/integrations/index.mdx @@ -1,9 +1,9 @@ --- -title: "Integrations overview" +title: "Integrations" sidebarTitle: "Overview" -description: "Connect Slack, CRMs, and custom tools using OAuth, webhooks, and partner connectors." +description: "Connect Mintlify to GitHub, GitLab, analytics tools, chat widgets, and your own systems." --- -Integrations let you meet your team where they already work. Start with managed connectors, then explore developer tools for custom workflows. +Mintlify integrates with the tools your team already uses. The articles in this section cover the most common integration paths — from connecting your Git repository to adding a live chat widget. -Each subsection below focuses on a different depth: quick connections, developer primitives, and packaged partner integrations. \ No newline at end of file +Start with connecting your repository if you haven't already — that's the foundation every other workflow builds on. diff --git a/help-center/getting-started/integrations/partners/custom-connector-template.mdx b/help-center/getting-started/integrations/partners/custom-connector-template.mdx index 97758b9..9cf8115 100644 --- a/help-center/getting-started/integrations/partners/custom-connector-template.mdx +++ b/help-center/getting-started/integrations/partners/custom-connector-template.mdx @@ -1,33 +1,43 @@ --- -title: "Custom connector template" -sidebarTitle: "Custom template" -description: "Fork the connector template to build a private integration faster." +title: "Custom domain setup" +sidebarTitle: "Custom domain" +description: "Point a custom domain to your Mintlify docs site." --- -The template encodes opinions: structured logging, retry policies, and test harnesses you would otherwise rebuild for every integration. Fork it, rename packages to match your org, and delete sample data before your first production credential touches it. +A custom domain makes your docs feel like a native part of your product — for example, `docs.yourcompany.com` instead of `yourcompany.mintlify.app`. -## What you get +Custom domains are available on Growth and Enterprise plans. -- Authentication scaffolding -- Webhook handlers -- Example tests +## Steps -### Conventions + + + Open your project in the Mintlify dashboard and go to **Settings → Custom domain**. Enter the domain you want to use (for example, `docs.yourcompany.com`) and click **Save**. -Follow the included directory layout so future contributors know where to add mappers, clients, and fixtures. + Mintlify will show you the DNS record you need to add. + + + In your DNS provider's settings, create a CNAME record: -## Customize + | Type | Name | Value | + |------|------|-------| + | CNAME | `docs` | `hosting.mintlify.com` | -Replace sample mappings with your schema and add monitoring for sync failures. + If you want to use a root domain (for example, `yourcompany.com`), use an ALIAS or ANAME record instead — standard CNAME records don't support root domains. + + + DNS changes can take a few minutes to a few hours to propagate. Mintlify checks your DNS automatically and provisions an SSL certificate once it can verify the domain. + + -### Observability +## SSL -Emit metrics for lag, error categories, and record counts—dashboards beat grep when something breaks at 2 a.m. +Mintlify provisions a free TLS certificate (via Let's Encrypt) for your custom domain automatically. You don't need to manage certificates manually. -## Support +## Troubleshooting -Partner engineering can review architecture for Enterprise customers in real deployments; this demo text is illustrative. +**The domain shows as "pending" after several hours.** +Run `dig docs.yourcompany.com CNAME` to verify the CNAME is pointing to `hosting.mintlify.com`. If not, double-check the DNS record and try again. Some DNS providers cache records aggressively — flush the cache if available. -### Security review - -Schedule architecture review before handling regulated data—catch network paths and key storage issues early. +**I'm getting an SSL error.** +SSL provisioning happens after DNS propagates. Wait a few hours after the DNS check passes. If it still fails after 24 hours, contact [support](mailto:support@mintlify.com). diff --git a/help-center/getting-started/integrations/partners/hubspot.mdx b/help-center/getting-started/integrations/partners/hubspot.mdx index 6bfb2d9..39e8bea 100644 --- a/help-center/getting-started/integrations/partners/hubspot.mdx +++ b/help-center/getting-started/integrations/partners/hubspot.mdx @@ -1,31 +1,36 @@ --- -title: "HubSpot connector" -sidebarTitle: "HubSpot" -description: "Connect HubSpot CRM for deals and company records." +title: "Cloudflare Pages deployment" +sidebarTitle: "Cloudflare" +description: "Deploy your Mintlify docs on Cloudflare Pages for edge hosting." --- -HubSpot works well when marketing and sales already live there—your product becomes the execution layer while HubSpot remains the system of record for pipeline stages and company attributes. +Cloudflare Pages is another option for hosting Mintlify docs close to your users. This approach uses Cloudflare's global edge network and works well if your team already uses Cloudflare for DNS and CDN. -## OAuth +## When to use Cloudflare Pages -Authorize HubSpot with a user who can grant CRM scopes. Use a service account if your policy requires it. +Use Cloudflare Pages when you: +- Already use Cloudflare for your DNS and want everything in one place. +- Need Cloudflare Access for authentication in front of your docs. +- Want Cloudflare's DDoS protection and WAF on your docs site. -### Scope review +## Setup overview -Confirm read vs write scopes against what your workflows actually need. Over-scoped tokens worry security reviewers. + + + Run `mintlify build` locally or in CI to generate a static build of your docs: -## Pipelines + ```bash + mintlify build + ``` + + + In the Cloudflare dashboard, go to **Pages → Create a project** and connect your Git repository. Set the build command to `mintlify build` and the output directory to `.mintlify/build`. + + + Add a custom domain in **Pages → [Your project] → Custom domains**. Cloudflare manages the DNS automatically if your domain's nameservers point to Cloudflare. + + -Align HubSpot deal stages with project states for cleaner reporting. +## Cloudflare Access -### Definitions - -Maintain a shared glossary of stage names so dashboards match what revenue teams say on calls. - -## Limits - -Watch API rate limits during large backfills; throttle initial syncs accordingly. - -### Pagination - -Use cursor-based APIs where available—safer than offset paging on large datasets. +To require authentication before readers can access your docs, add a Cloudflare Access policy in front of your Pages project. This works independently of Mintlify's built-in authentication features. diff --git a/help-center/getting-started/integrations/partners/index.mdx b/help-center/getting-started/integrations/partners/index.mdx index 03cfc6d..d081747 100644 --- a/help-center/getting-started/integrations/partners/index.mdx +++ b/help-center/getting-started/integrations/partners/index.mdx @@ -1,9 +1,9 @@ --- -title: "Partner connectors" +title: "Deployment and hosting options" sidebarTitle: "Overview" -description: "Packaged integrations for Salesforce, HubSpot, and custom connector templates." +description: "Host your Mintlify docs on a custom domain, Vercel, Cloudflare, or a reverse proxy." --- -Partner connectors ship maintained field mappings and sane defaults. Use them when you want speed over full custom control. +Mintlify deploys your docs to a `*.mintlify.app` URL by default. On Growth and Enterprise plans, you can also host on a custom domain or serve your docs from your own infrastructure. -Pick a vendor-specific guide below or start from the custom template when your stack is unique. \ No newline at end of file +Use the articles in this section to set up the hosting option that fits your setup. diff --git a/help-center/getting-started/integrations/partners/salesforce.mdx b/help-center/getting-started/integrations/partners/salesforce.mdx index cba1497..2033dad 100644 --- a/help-center/getting-started/integrations/partners/salesforce.mdx +++ b/help-center/getting-started/integrations/partners/salesforce.mdx @@ -1,31 +1,42 @@ --- -title: "Salesforce connector" -sidebarTitle: "Salesforce" -description: "Install, authenticate, and map Salesforce objects to the product." +title: "Vercel deployment" +sidebarTitle: "Vercel" +description: "Deploy your Mintlify docs on Vercel for custom routing and edge performance." --- -The Salesforce connector reduces copy-paste between CRM and your workspace. Plan object mapping before you sync thousands of rows—rework is cheaper in a spreadsheet than in production data. +You can deploy a Mintlify docs site as a Next.js project on Vercel. This gives you full control over routing, redirects, and CDN configuration. -## Prerequisites +## When to use Vercel -Admin access in Salesforce and an administrator to approve the connector. +Use Vercel hosting when you: +- Need to serve docs from a path on your own domain (for example, `yourdomain.com/docs`). +- Want to use Vercel's edge network for CDN and performance. +- Need custom middleware for authentication or routing. -### Sandboxes +For most teams, Mintlify's built-in hosting with a custom subdomain (`docs.yourdomain.com`) is simpler and requires no additional infrastructure. -Pilot against a full or partial sandbox before production. Validate picklist values, required fields, and validation rules that might block writes. +## Setup overview -## Field mapping + + + Use the Mintlify CLI to export your project as a Next.js static build: -Map accounts, contacts, and opportunities to entities. Resolve duplicates by external ID where possible. + ```bash + mintlify build + ``` + + + Push the build output to a Git repository connected to Vercel, or use the Vercel CLI: -### Ownership + ```bash + vercel deploy + ``` + + + In the Vercel dashboard, add your custom domain under **Project → Settings → Domains**. + + -Decide who owns records when Salesforce and the product disagree. Document the rule in your runbook so support can answer “why did this flip?” - -## Sync modes - -Choose one-way or two-way sync depending on which system owns each field. - -### Monitoring - -Alert on sync lag and error rates. Backfills can look healthy while a handful of poison records retry forever. + + When deploying to Vercel, you manage your own hosting infrastructure. Mintlify's built-in analytics and AI search features may behave differently in this configuration — check the [Mintlify docs](https://mintlify.com/docs) for any limitations. + diff --git a/help-center/getting-started/quickstart.mdx b/help-center/getting-started/quickstart.mdx index e7781de..90a2b86 100644 --- a/help-center/getting-started/quickstart.mdx +++ b/help-center/getting-started/quickstart.mdx @@ -1,32 +1,33 @@ --- -title: "Quickstart: get set up in under 15 minutes" +title: "Deploy your docs in under 15 minutes" sidebarTitle: "Quickstart" -description: "A fast path from signup to first project: invites, roles, and your first integration." +description: "Connect your repository, deploy your site, and make your first edit." --- -This checklist gets a small team from zero to a credible pilot: verified accounts, a safe place to collaborate, and one integration proving data can flow in and out. Adjust order if your security team requires SSO before invites. +This guide gets you from zero to a live Mintlify docs site with a deployed URL and your first published change. ## Before you begin -- A verified email you can access -- Admin access if you are enabling SSO later -- Rough idea of who belongs in the pilot (five to fifteen people is typical) - -If you are migrating from another tool, keep a CSV of users and roles handy—you will move faster than recreating access from memory. +- A GitHub or GitLab account (either will work) +- A repository for your documentation, or permission to create one ## Steps -1. **Create your organization** — Pick a name your team will recognize in notifications. Avoid internal codenames if customers might see the name on shared artifacts. -2. **Invite teammates** — Start with a small pilot group before rolling out widely. Ask them to accept within a week so you are not debugging expired invites during launch. -3. **Connect one integration** — Choose Slack or your CRM to see data flow end to end. Validate credentials in a sandbox or test channel first. -4. **Create a first project** — Use it as a sandbox for workflows and permissions. Seed a few realistic tasks so demos feel grounded. +1. **Sign up** — Go to [mintlify.com/start](https://mintlify.com/start) and create your account. You can sign up with GitHub for a faster setup. -### Time checks +2. **Connect your repository** — Select the GitHub or GitLab repo that contains your docs. Mintlify installs a GitHub App that watches for pushes and triggers deployments automatically. -If any step waits on IT (DNS, SSO metadata, firewall rules), parallelize what you can—draft project structure while tickets move. +3. **Wait for the first deploy** — The initial build takes about a minute. When it's done, your site is live at a `*.mintlify.app` URL shown in your dashboard. -## Next steps +4. **Make your first edit** — Choose your path: + - **Web editor** — Click **Edit** in the dashboard. Edit pages in the browser and click **Publish** when ready. + - **CLI** — Run `npm i -g mintlify && mintlify dev` to preview locally, then push to Git to deploy. -Review [sign-in and security](/getting-started/sign-in-security) and explore the [workspace](/getting-started/workspace) guides when you are ready to tighten access. +5. **Share a preview** — Open a pull request. Mintlify automatically builds a preview deployment and posts the URL as a status check on the PR. + +## Next steps -Consider a short retro after week one: what confused newcomers, which doc they opened first, and whether search surfaced the right page. +- Set a [custom domain](/getting-started/integrations/partners/custom-connector-template) so your docs live at `docs.yourcompany.com`. +- [Invite teammates](/getting-started/workspace/invite-teammates) to edit and review. +- [Connect an analytics provider](/getting-started/integrations/connect-crm) to track page views and search queries. +- Explore [Mintlify's component library](https://mintlify.com/docs/components) to add Cards, Steps, Tabs, and more. diff --git a/help-center/getting-started/sign-in-security.mdx b/help-center/getting-started/sign-in-security.mdx index 6fe013c..1cc9604 100644 --- a/help-center/getting-started/sign-in-security.mdx +++ b/help-center/getting-started/sign-in-security.mdx @@ -1,37 +1,37 @@ --- -title: "Sign-in and security basics" +title: "Sign-in and security" sidebarTitle: "Sign-in & security" -description: "Passwords, SSO, session length, and how we protect your workspace." +description: "Authentication options, SSO, and security best practices for your Mintlify account." --- -Good security balances friction for attackers without blocking legitimate work. Understand how people authenticate, how long sessions last, and what admins can require before high-risk actions. +Mintlify supports several authentication methods. Choose the one that fits your team's security requirements and identity provider setup. ## Authentication options -- Email and password with optional MFA -- SAML SSO on eligible plans -- IdP-initiated login where supported +- **GitHub or GitLab OAuth** — Sign in with your Git provider account. Fast to set up and familiar to developers. +- **Email and password** — Standard email-based login with an optional magic link. +- **SAML SSO** — Available on Growth and Enterprise plans. Connect your identity provider (Okta, Azure AD, Google Workspace, etc.) for centralized authentication. -### MFA +### Enabling SSO -Require MFA for every member when your data classification demands it—not only admins. Attackers target contributors with broad file access too. +SSO is configured at the organization level by an Admin: -### SSO cutover +1. Go to **Settings → Security → SSO**. +2. Select your identity provider. +3. Enter the metadata URL or upload the XML metadata file from your IdP. +4. Map the required attributes (email, name). +5. Test with a pilot user before enforcing SSO for all members. -Plan a maintenance window when enabling SAML: communicate downtime, validate attribute mapping with a pilot group, and keep a break-glass local admin. + + Keep at least one non-SSO admin account as a break-glass access method while you validate SSO. If the IdP configuration is wrong, you could lock everyone out. + ## Sessions -Sessions expire after a period of inactivity. Admins can require re-authentication for sensitive actions. Shorter sessions reduce risk on shared machines; longer sessions reduce nagging on trusted laptops. - -### Device hygiene - -Encourage disk encryption and screen locks on machines that hold session cookies. Remote wipe policies complement session timeouts for lost hardware. +Mintlify sessions stay active until you sign out or the session expires. If your organization requires shorter session lifetimes, configure the session duration in **Settings → Security**. ## Best practices -Enforce MFA for all admins, use separate staging and production workspaces, and review connected OAuth apps quarterly. - -### OAuth review - -Remove tokens for tools you no longer use—old integrations keep API access until revoked. Pair reviews with offboarding checklists when people change roles. +- Use a dedicated service account to connect Mintlify to your CI/CD pipeline rather than a personal account — this prevents access loss when team members change. +- Rotate API keys periodically and immediately when someone with access leaves the team. +- Review connected OAuth apps quarterly and revoke any you no longer use. diff --git a/help-center/getting-started/workspace/index.mdx b/help-center/getting-started/workspace/index.mdx index 0a8cfef..c86f74f 100644 --- a/help-center/getting-started/workspace/index.mdx +++ b/help-center/getting-started/workspace/index.mdx @@ -1,9 +1,9 @@ --- -title: "Workspace: teams, roles, and settings" +title: "Your Mintlify organization" sidebarTitle: "Overview" -description: "Configure how people collaborate: membership, roles, and org-wide preferences." +description: "Manage members, roles, and organization-wide settings for your Mintlify account." --- -Your workspace is where members, permissions, and org settings come together. +Your Mintlify organization is the top-level container for all your docs projects. Members, billing, and organization-wide settings are all managed here. -The guides in this section explain how to invite people, align roles with how you operate, and keep administrative control as you grow. \ No newline at end of file +The articles in this section explain how to invite people, assign roles, and configure your organization settings. diff --git a/help-center/getting-started/workspace/invite-teammates.mdx b/help-center/getting-started/workspace/invite-teammates.mdx index fc5e9d7..b957e58 100644 --- a/help-center/getting-started/workspace/invite-teammates.mdx +++ b/help-center/getting-started/workspace/invite-teammates.mdx @@ -1,35 +1,39 @@ --- -title: "Invite teammates to your workspace" +title: "Invite teammates" sidebarTitle: "Invite teammates" -description: "Send invites, assign initial roles, and manage pending invitations." +description: "Add editors and admins to your Mintlify organization." --- -Invitations are the front door to your workspace. Clear roles and timely follow-up prevent “I never got access” threads during launches. Treat pending invites like inventory—review them weekly until cleared. +Mintlify has two places where you can invite collaborators: the organization level (for broad access) and the project level (for access to a specific docs site). -## Send invites +## Invite to your organization -From **Settings → Members**, enter email addresses and pick a default role. Invites expire after fourteen days unless resent. +1. Go to [dashboard.mintlify.com](https://dashboard.mintlify.com) and open your organization. +2. Go to **Settings → Members**. +3. Enter the email address of the person you want to invite. +4. Select their role: **Admin** or **Editor**. +5. Click **Send invite**. -### Bulk import +The invitee receives an email with a link to accept. Invitation links expire after 7 days — resend from the Members page if the link expires. -If your product supports CSV import, validate columns against HR data first—typos in email addresses generate unnecessary support tickets. +### Role assignment -### Messaging +Assign the **Editor** role to most teammates — they can write and publish content but can't access billing or organization settings. Reserve **Admin** for people who need to manage the organization, billing, or security settings. -Tell people to expect an invite from a specific sender name so corporate filters do not hide it. Link to your internal wiki for “why we adopted this tool.” +## Invite to a specific project -## Roles at invite time +To give someone access to one project without adding them to the organization: -You can assign **Member**, **Admin**, or custom roles if your plan supports them. You can change roles after someone joins. +1. Open the project in your dashboard. +2. Go to **Settings → Members**. +3. Enter their email and select a project-level role. -### Principle of least privilege +Project-level access doesn't grant access to other projects or organization settings. -Default to Member unless someone truly needs billing or security settings. Elevate admins in pairs so coverage exists during PTO. +## Pending invites -## Revoking invites +Pending invites are listed in **Settings → Members → Pending**. You can resend or revoke them from there. Revoking an invite doesn't notify the recipient — the link simply stops working. -Pending invites can be revoked individually. Revocation does not notify the recipient beyond the link no longer working. - -### Audit trail - -Keep a note if you revoke because someone left the company—helps during access reviews and prevents accidental re-invite from stale spreadsheets. + + Tell new teammates to expect an invite email from Mintlify. Corporate email filters sometimes flag unfamiliar senders and send the message to spam. + diff --git a/help-center/getting-started/workspace/organization-settings.mdx b/help-center/getting-started/workspace/organization-settings.mdx index 002393b..2991c95 100644 --- a/help-center/getting-started/workspace/organization-settings.mdx +++ b/help-center/getting-started/workspace/organization-settings.mdx @@ -1,31 +1,37 @@ --- title: "Organization settings" sidebarTitle: "Org settings" -description: "Name, branding touches, defaults, and workspace-level policies." +description: "Configure your organization name, default settings, and security policies." --- -Organization settings define how your workspace presents itself and which guardrails apply by default. Changes here often require admin rights and may notify all members—communicate before big switches. +Organization settings control how your Mintlify account is identified and what default behaviors apply to all projects. Only Admins can access organization settings. -## Profile +Navigate to **Settings** from your dashboard to manage these options. -Update display name and public-facing details shown in invites and notification footers. Align spelling with your legal entity where invoices and DPA references matter. +## Organization profile -### Logos and assets +- **Name** — Shown in the dashboard, email notifications, and invitation emails. Use your company or product name. +- **Slug** — The URL-safe identifier used in your Mintlify project URLs. Changing the slug updates all project URLs — notify your team before making this change. -Use brand-approved logos and color contrast checks for accessibility. Store source files in your brand portal so future admins are not hunting attachments in chat. +## Security -## Defaults + + + Connect a SAML 2.0 or OIDC identity provider so team members sign in through your company's existing auth system. Available on Growth and Enterprise plans. -Set default project visibility and automation limits for new projects created by members. + Once SSO is configured, you can optionally enforce it — members who haven't connected their SSO account will be locked out until they do. + + + Restrict who can be invited to your organization by email domain. When set, only email addresses from the approved domains can accept invitations. -### Templates + Useful for organizations with multiple email domains (acquired companies, contractors) where you want to control who can join. + + -Pair defaults with project templates so teams inherit sane labels, sections, and automation caps without starting from zero every time. +## Default project settings -## Policies +New projects inherit organization-level defaults for visibility and member access. Configure defaults in **Settings → Projects** so teams don't need to configure every new project from scratch. -Admins can require MFA, restrict invite domains, and define data residency expectations where features exist for your region. - -### Exceptions - -Document how to request exceptions (contractors, acquisitions) so security can approve without inventing a new process each time. + + Organization settings changes can affect all members immediately. Test significant changes (like enforcing SSO) with a small group before rolling out to the whole team. + diff --git a/help-center/getting-started/workspace/roles-permissions.mdx b/help-center/getting-started/workspace/roles-permissions.mdx index 8c0c515..a90115f 100644 --- a/help-center/getting-started/workspace/roles-permissions.mdx +++ b/help-center/getting-started/workspace/roles-permissions.mdx @@ -1,38 +1,33 @@ --- title: "Roles and permissions" sidebarTitle: "Roles & permissions" -description: "Understand what admins, members, and custom roles can see and change." +description: "What admins and editors can do in Mintlify." --- -Permissions translate org structure into enforceable rules. When in doubt, mirror how your company already thinks about data classification—customer data vs internal-only vs public marketing. +Mintlify uses two roles at the organization level and the same two roles at the project level. Project-level roles take precedence within that project. -## Default roles +## Organization roles -| Role | Typical use | -|------|-------------| -| Admin | Billing, security, workspace-wide settings | -| Member | Day-to-day work inside assigned projects | +| Role | What they can do | +|------|-----------------| +| **Admin** | Full access to all projects, organization settings, billing, and member management. | +| **Editor** | Can create, edit, and publish pages in any project they're a member of. Cannot access billing or organization settings. | -### Admin count +## Project roles -Keep the admin group small and named. Too many admins increases accidental misconfiguration; too few blocks urgent fixes. +Each project has its own member list. A person can be an Admin in one project and an Editor in another. -## Custom roles +| Role | What they can do | +|------|-----------------| +| **Admin** | Full access to project settings, custom domain configuration, and member management for that project. | +| **Editor** | Can write and publish pages using the web editor. Cannot change project settings. | -On supported plans, create roles that map to your internal job functions and restrict exports or automation actions. +## The web editor vs Git -### Design tips +Editors who use the web editor work within Mintlify — no Git knowledge required. Anyone with write access to the underlying Git repository can also make changes via Git and the CLI, regardless of their Mintlify role. -Name roles after outcomes (“Support – view only”) not job titles alone (“Engineer”), because titles drift faster than access needs. - -### Testing - -Before rolling out a new role, impersonate or test with a sandbox user—verify denied actions fail closed with a clear error. +If you want to restrict who can deploy changes, use branch protection rules in GitHub or GitLab to require pull request reviews before merges to your default branch. ## Auditing -Admins can review a lightweight access log of role changes and exports (retention varies by plan). - -### Reviews - -Schedule quarterly access reviews for high-sensitivity projects. Export logs before reviews if you need to join them to HR systems. +Admins can view a log of membership changes in **Settings → Audit log** (available on Enterprise plans). Review access quarterly when team members change roles or leave the organization. diff --git a/help-center/index.mdx b/help-center/index.mdx index 3362b4b..b34339a 100644 --- a/help-center/index.mdx +++ b/help-center/index.mdx @@ -11,7 +11,7 @@ mode: custom How can we help?

- Search the Help Center for setup guides, product how-tos, automation tips, and policies—all in one + Search the Mintlify Help Center for setup guides, deployment how-tos, editor tips, and legal docs—all in one place.

@@ -59,7 +59,7 @@ mode: custom
Popular searches
- {['integrations', 'workspace', 'billing'].map((term) => ( + {['custom domain', 'deployment', 'web editor'].map((term) => (
@@ -102,13 +102,13 @@ mode: custom

All guides

- Invites, roles, and organization settings + Invite editors, assign roles, and configure org settings - Compare plans, upgrades, and invoices + Compare plans, upgrade, and download invoices - OAuth apps, webhooks, and API keys + API keys, deployment webhooks, and private docs auth - Create projects and archive or restore them + Create and manage your Mintlify docs projects - Login issues and performance troubleshooting + Login issues, build failures, and performance problems - Terms of service, privacy & GDPR, and regional specifics + Terms of service, privacy policy, DPA, and regional data
@@ -169,40 +169,40 @@ mode: custom - A fast path from signup to first project: invites, roles, and your first integration. + Connect your repo, deploy your site, and make your first edit. - Model conditional paths and merge strategies in workflows. + Review docs changes at a unique URL before merging to production. - Demo privacy policy for this help center. + Point docs.yourcompany.com to your Mintlify project. - Link Salesforce or HubSpot through partner connectors or a custom sync strategy. + Add PostHog, GA4, or another analytics tool to your docs site. diff --git a/help-center/product/automation/advanced/idempotency.mdx b/help-center/product/automation/advanced/idempotency.mdx index da39a82..c0e4454 100644 --- a/help-center/product/automation/advanced/idempotency.mdx +++ b/help-center/product/automation/advanced/idempotency.mdx @@ -1,31 +1,59 @@ --- -title: "Idempotency" -sidebarTitle: "Idempotency" -description: "Use idempotency keys to make automation safe under retries." +title: "Redirects and URL stability" +sidebarTitle: "Redirects" +description: "Set up redirects to preserve links when you restructure your docs." --- -Networks drop packets, clients retry, and queues redeliver. Without idempotency, the same user intent can create duplicate charges, tickets, or posts. Idempotency keys make “exactly-once behavior” practical on “at-least-once” infrastructure. +When you rename, move, or delete pages, existing links break. Redirects let you preserve those links and maintain SEO value when your docs structure changes. -## Why it matters +## Setting up redirects -Retries can duplicate side effects without idempotent design. Payment and ticketing integrations are the usual victims—duplicate idempotency keys should return the original result, not create a second record. +Add a `redirects` array to your `docs.json`: -### Scope +```json +"redirects": [ + { + "source": "/old-path/page", + "destination": "/new-path/page" + }, + { + "source": "/getting-started/old-name", + "destination": "/quickstart" + } +] +``` -Decide whether keys are global, per-tenant, or per-user. Collisions across tenants are rare but catastrophic if namespaces overlap. +Redirects are 301 (permanent) by default. Mintlify applies them at the CDN level, so they're fast. -## Keys +## When to use redirects -Supply a stable idempotency key derived from natural identifiers—order ID, request UUID, or hash of canonical fields. Avoid keys that change when unrelated whitespace changes. +Use redirects whenever you: +- Rename a page. +- Move a page to a different section. +- Delete a page and want to point visitors to a related page. +- Restructure your navigation hierarchy. -### Rotation +## Wildcard redirects -If you must rotate key material, dual-write during transition and document the overlap window. +Use wildcards to redirect entire sections at once: -## Storage +```json +{ + "source": "/old-section/:path*", + "destination": "/new-section/:path*" +} +``` -Record processed keys long enough to cover your retry window plus clock skew. Expire old keys to bound storage, but not before your longest plausible retry storm. +This redirects `/old-section/page-a` to `/new-section/page-a`, `/old-section/page-b` to `/new-section/page-b`, and so on. -### Conflicts +## Keeping URLs stable -When a new payload arrives with an existing key but different body, reject loudly—something is inconsistent and needs human review. +The best way to avoid broken links is to keep URLs stable from the start: + +- Choose page slugs that reflect the content's purpose, not its position in the navigation. +- Use short, descriptive slugs that won't need to change when content evolves. +- Avoid including version numbers in slugs unless you're explicitly versioning your docs. + + + Before a major restructure, run a link check on your docs and on external sites that link to you. Prioritize redirects for high-traffic pages and frequently linked anchors. + diff --git a/help-center/product/automation/advanced/index.mdx b/help-center/product/automation/advanced/index.mdx index 40e4672..b7db4ff 100644 --- a/help-center/product/automation/advanced/index.mdx +++ b/help-center/product/automation/advanced/index.mdx @@ -1,9 +1,7 @@ --- -title: "Advanced patterns" +title: "Advanced deployment topics" sidebarTitle: "Overview" -description: "Rate limits, idempotency, and retry policies for high-volume automation." +description: "Build optimization, redirects, and edge cases for large Mintlify docs sites." --- -At scale, small mistakes amplify. This section covers defensive patterns so automation stays reliable under load. - -Read these articles before opening your integration to high-traffic events. \ No newline at end of file +As your docs site grows, you'll run into questions about build performance, URL management, and edge cases. This section covers the more advanced aspects of running Mintlify at scale. diff --git a/help-center/product/automation/advanced/rate-limits.mdx b/help-center/product/automation/advanced/rate-limits.mdx index 218f347..871b240 100644 --- a/help-center/product/automation/advanced/rate-limits.mdx +++ b/help-center/product/automation/advanced/rate-limits.mdx @@ -1,33 +1,33 @@ --- -title: "Rate limits" -sidebarTitle: "Rate limits" -description: "Understand automation rate limits and how to design around them." +title: "Build limits and quotas" +sidebarTitle: "Build limits" +description: "Mintlify build limits, concurrent deployments, and what to do when you hit them." --- -Rate limits keep shared infrastructure healthy. Treat them as part of your design—not surprises—when you connect automation to external APIs or run fan-out jobs across many tenants. +Mintlify imposes some limits on deployments to keep the build infrastructure reliable for all customers. -## Defaults +## Concurrent builds -Limits protect shared infrastructure. Burst allowances exist for short spikes, but sustained traffic above quota will throttle or fail requests—often with `429` responses you must handle. +By default, a project can have one active build at a time. If a new push arrives while a build is in progress, Mintlify queues the new build and starts it when the current one finishes. -### Headers +For high-velocity teams that push frequently, this means two rapid pushes may result in one of them being built after a short wait. -Many APIs return `Retry-After` or rate-limit headers. Log them during integration testing so your backoff code respects server hints instead of guessing. +## Build frequency -## Strategies +There's no hard limit on how many deployments you can trigger per day, but very frequent deployments (many per minute) may be rate-limited temporarily. If you're triggering programmatic deployments, add a delay between requests. -- Batch work where possible—one request with twenty IDs beats twenty serial requests. -- Queue externally when needed so spikes flatten into steady throughput. -- Shed load with sampling under stress: process every Nth event until pressure drops. +## Large repositories -### Tenant fairness +Build times scale with the number of pages in your docs site. Most sites with fewer than 1,000 pages build in under a minute. Very large sites (thousands of pages) may take a few minutes. -Multi-tenant systems sometimes enforce per-tenant caps. Coordinate with platform admins if one customer’s automation crowds others. +To reduce build times: +- Avoid generating pages dynamically from external sources — pre-render content where possible. +- Keep images optimized — large image files slow down builds and page loads. -## Monitoring +## Plan limits -Graph throttle events to spot hot workflows early. Alert when throttle rates exceed a baseline for more than a few minutes—often the first sign of an infinite loop or misconfigured poll interval. +Starter plans are limited to one project. Growth and Enterprise plans support multiple projects. Check **Settings → Billing** for the limits on your current plan. -### Capacity planning - -Before launch week, rehearse peak traffic with load tests against staging. Compare observed QPS to your quotas and pad headroom for retries. + + If you're consistently hitting build quotas or need higher concurrency, contact [support](mailto:support@mintlify.com) — Enterprise plans include custom limits. + diff --git a/help-center/product/automation/advanced/retry-policies.mdx b/help-center/product/automation/advanced/retry-policies.mdx index e4b2b4b..754532f 100644 --- a/help-center/product/automation/advanced/retry-policies.mdx +++ b/help-center/product/automation/advanced/retry-policies.mdx @@ -1,31 +1,40 @@ --- -title: "Retry policies" -sidebarTitle: "Retry policies" -description: "Configure exponential backoff, max attempts, and dead-letter handling." +title: "Build retries and recovery" +sidebarTitle: "Build retries" +description: "How Mintlify handles failed builds, retries, and recovery paths." --- -Retries turn transient failures into success stories—when configured carefully. Backoff spreads load; max attempts bound damage; dead-letter queues preserve poison messages for inspection instead of infinite loops. +When a Mintlify build fails, the previous successful deployment continues to serve traffic. Your live site stays up even when a build fails. -## Backoff +## Automatic retries -Exponential backoff reduces thundering herds. Add jitter to desynchronize clients so retries do not align on the same second. +Mintlify does not automatically retry failed builds — a failed build means there's a problem that needs to be fixed (usually a syntax error or misconfiguration). Fix the issue and push a new commit to trigger a new build. -### Caps +## Manual retries -Put an upper bound on delay so a permanently broken endpoint does not stall workers for hours between attempts—pair backoff with a max attempts ceiling. +If a build failed due to a transient issue (network timeout, external resource unavailable), you can retry from the dashboard: -## Max attempts +1. Go to **[Project] → Deployments**. +2. Find the failed deployment. +3. Click **Retry**. -Stop after N tries and surface to operators with context. Include the last error code, truncated body, and correlation ID so the first responder does not reproduce the whole incident from scratch. +Only retry if you believe the failure was transient — retrying a build with the same code will fail again if the root cause isn't fixed. -### Idempotency +## Recovering from a bad deployment -Retries assume idempotent handlers. If a step is not idempotent, disable blind retries or scope them to safe sub-operations. +If a deployment succeeded but introduced a problem (broken layout, incorrect content, broken links), you have two recovery paths: -## Dead letters +**Option 1: Revert in Git** +Revert the problematic commit in your repository. Mintlify deploys the reverted version automatically. -Send poison messages to a dead-letter queue for manual inspection. Monitor DLQ depth: a flat line at zero might mean alerts are misconfigured; a rising line means systemic failure. +```bash +git revert HEAD +git push +``` -### Replay +**Option 2: Redeploy a previous version** +In **[Project] → Deployments**, find the last known-good deployment and click **Redeploy**. -Document a safe replay procedure after fixing root cause—sometimes replay requires a new idempotency key or compensating cleanup first. +## Monitoring deployments + +Set up GitHub Actions notifications (see [Slack notifications](/getting-started/integrations/connect-slack)) to alert your team when a deployment fails. Catching failures early prevents readers from hitting broken preview links or outdated content. diff --git a/help-center/product/automation/index.mdx b/help-center/product/automation/index.mdx index ef3dc39..57a5fa8 100644 --- a/help-center/product/automation/index.mdx +++ b/help-center/product/automation/index.mdx @@ -1,9 +1,9 @@ --- -title: "Automation" +title: "Deployments" sidebarTitle: "Overview" -description: "Rules, workflows, schedules, and advanced reliability patterns." +description: "How Mintlify builds and deploys your docs, and how to configure your deployment pipeline." --- -Automation reduces manual work by reacting to events and running trusted sequences. Start with simple rules, graduate to workflows, and apply advanced patterns when volume grows. +Every change to your docs site — whether from the web editor or a Git push — goes through a deployment. Deployments are fast, automatic, and auditable. -This hub introduces each layer—use the child articles for specifics. \ No newline at end of file +This section explains how deployments work, how to configure triggers, and how to handle failures. diff --git a/help-center/product/automation/rules-triggers.mdx b/help-center/product/automation/rules-triggers.mdx index b15aeef..0a0b963 100644 --- a/help-center/product/automation/rules-triggers.mdx +++ b/help-center/product/automation/rules-triggers.mdx @@ -1,35 +1,40 @@ --- -title: "Rules and triggers" -sidebarTitle: "Rules & triggers" -description: "Define when automation runs using events, filters, and guardrails." +title: "Deployment triggers" +sidebarTitle: "Triggers" +description: "What causes a Mintlify deployment and how to configure which events trigger builds." --- -Rules answer **when** something should run. Triggers are the signals—product events, webhooks, or schedules—that start evaluation. Filters and guardrails keep runs safe when traffic spikes or data is messy. +Mintlify builds and deploys your docs automatically in response to Git events. Here's what triggers a deployment and how to configure each type. -## Events +## Push to default branch -Pick source events such as item created, status changed, or webhook received. Prefer the narrowest event that still captures your intent so you do not wake automation on unrelated edits. +Every push to your repository's default branch (typically `main`) triggers a production deployment. This is the primary trigger for most teams. -### Ordering +To change the production branch, go to **Project Settings → Git → Production branch**. -If multiple rules subscribe to the same event, understand whether execution is parallel or ordered. Side-effect-heavy rules may need explicit sequencing or a queue. +## Pull request previews -### Payload shape +Every pull request against your default branch gets a preview deployment at a unique URL. Preview URLs look like `https://[project]-[pr-number].mintlify.app`. -Automation often receives a structured payload with IDs and timestamps. Log sample payloads in a sandbox when writing conditions so you do not guess field names. +Share preview links in your PR description for reviews before merging. Preview deployments are deleted automatically when the PR closes. -## Filters +### Disabling previews -Narrow by project, label, or field values to avoid noisy runs. Combine predicates carefully: over-filtering misses legitimate cases; under-filtering spams logs and external systems. +Preview deployments are enabled by default. Disable them in **Project Settings → Git → Pull request previews** if you don't want them. -### Testing filters +## Manual redeploys -Use historical replay or dry-run tools when available. “It worked once” is not the same as “it works for every region code.” +Trigger a deployment manually from the dashboard without making a code change: -## Guardrails +1. Go to **[Project] → Deployments**. +2. Click **Redeploy** on the most recent successful deployment. -Set concurrency caps and failure alerts before automation touches production data. Caps protect downstream APIs; alerts help humans notice misconfigured filters before customers do. +This is useful if you've updated an external resource (like an OpenAPI spec hosted at a URL) that your docs reference. -### Kill switches +## Branch deployments -Document how to disable a rule quickly—feature flag, toggle, or removal—during incidents. Practice the rollback path once per quarter. +Beyond the default branch, you can configure specific branches to deploy automatically. Go to **Project Settings → Git → Additional branches** to add branch patterns. + + + Branch deployments are useful for long-running feature branches or staging environments. Each branch gets its own subdomain under `mintlify.app`. + diff --git a/help-center/product/automation/scheduled-tasks.mdx b/help-center/product/automation/scheduled-tasks.mdx index 2272771..d69644a 100644 --- a/help-center/product/automation/scheduled-tasks.mdx +++ b/help-center/product/automation/scheduled-tasks.mdx @@ -1,35 +1,62 @@ --- -title: "Scheduled tasks" +title: "Scheduled tasks and checks" sidebarTitle: "Scheduled tasks" -description: "Cron-style schedules, timezone handling, and backoff." +description: "Automate link validation, content audits, and other recurring checks for your docs." --- -Scheduled tasks run without a human click: nightly syncs, weekly digests, or maintenance windows. Get timezones right once, then monitor failures—silent misses are harder to spot than user-triggered errors. +Mintlify deployments are event-driven (triggered by Git pushes), but you can use GitHub Actions or GitLab CI to run scheduled checks on your docs independently of deploys. -## Schedules +## Scheduled link validation -Use cron expressions or friendly presets. All times respect the project timezone unless overridden explicitly for global teams. +Broken links erode trust and hurt SEO. Set up a weekly or daily link check to catch broken links before readers do: -### Cadence choices +```yaml +name: Link check +on: + schedule: + - cron: '0 9 * * 1' # Every Monday at 9am UTC -Prefer off-peak windows for heavy jobs. If you need “every hour,” confirm your platform’s minimum interval and whether missed runs catch up or skip. +jobs: + link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check links + uses: lycheeverse/lychee-action@v1 + with: + args: --verbose --no-progress './**/*.mdx' +``` -### Holidays +Fix broken links in a PR — the preview deployment lets you verify the fix before merging. -Some teams pause schedules on holidays via a calendar flag or a wrapper rule—otherwise your “Monday report” might fire on a quiet day with no fresh data. +## Scheduled content audits -## Daylight saving +Use a scheduled job to check for pages that haven't been updated in a long time: -Ambiguous local times may skip or repeat—prefer UTC for critical jobs. If you must stay local, document the DST transition dates for your region and test around them. +```bash +# Find MDX files not modified in the last 90 days +git log --all --format="%ai %H %s" -- "**/*.mdx" | \ + awk -v cutoff="$(date -d '90 days ago' +%Y-%m-%d)" '$1 < cutoff {print $0}' +``` -### Jitter +Route the output to a Slack channel or create GitHub issues to track stale content. -Add small random delay when many schedules align at midnight to avoid thundering herds against shared databases. +## Scheduled deployments -## Monitoring +If you reference external data (an OpenAPI spec, a changelog, etc.) that updates independently of your docs repository, you can trigger a manual redeploy on a schedule: -Failed runs surface in the automation console with logs for debugging. Wire alerts to the same channel as user-facing incidents when the job protects revenue or compliance. +```yaml +name: Scheduled redeploy +on: + schedule: + - cron: '0 6 * * *' # Daily at 6am UTC -### Runbooks - -Link a short runbook from each alert: what failed, what to check first, and who owns the downstream integration. +jobs: + redeploy: + runs-on: ubuntu-latest + steps: + - name: Trigger Mintlify redeploy + run: | + curl -X POST https://api.mintlify.com/v1/projects/${{ secrets.MINTLIFY_PROJECT_ID }}/deploy \ + -H "Authorization: Bearer ${{ secrets.MINTLIFY_API_KEY }}" +``` diff --git a/help-center/product/automation/workflows/build-first-workflow.mdx b/help-center/product/automation/workflows/build-first-workflow.mdx index fd5a3c6..a2f7a87 100644 --- a/help-center/product/automation/workflows/build-first-workflow.mdx +++ b/help-center/product/automation/workflows/build-first-workflow.mdx @@ -1,34 +1,41 @@ --- -title: "Build your first workflow" -sidebarTitle: "First workflow" -description: "Step-by-step creation of a simple approval workflow." +title: "Set up PR previews" +sidebarTitle: "PR previews" +description: "Use pull request previews to review docs changes before they go live." --- -This walkthrough builds confidence before you model complex branching. You will route new items to a human, time out if nobody responds, and notify a channel when the outcome is approved—patterns common to access requests, content launches, and finance approvals. +Pull request previews give every docs change its own live URL for review before merging. This is the foundation of a safe docs review workflow. -## Goal +## How PR previews work -Route new items to a reviewer and notify Slack on approval. Keep scope intentionally small: one project, one template, one external integration. +When you open a pull request against your default branch, Mintlify automatically builds and deploys the changes at a unique preview URL. The URL appears in your PR comments as a status check. -### Success criteria +No configuration required — previews are enabled by default for all projects connected to GitHub or GitLab. -Define what “done” means: reviewer assigned within five minutes, decision within one business day, and an audit log entry for compliance. +## Using previews effectively -## Steps + + + Make your docs changes in a branch and open a pull request. The Mintlify GitHub App posts a comment with a link to the preview deployment once the build completes. + + + Copy the preview URL and add it to the PR description or a comment. Reviewers can see the rendered page without checking out the branch locally. + + + Push additional commits to the branch — each push updates the preview deployment automatically. Reviewers can reload the preview URL to see changes. + + + When approved, merge the PR. Mintlify deploys to production automatically within seconds. + + -1. Create a workflow from a template. Pick the closest match, then rename steps so stakeholders recognize language from your internal process doc. -2. Add a human approval step with timeout. Escalate or cancel when time expires—avoid infinite waits. -3. Connect Slack notification on success. Map channel names to environments (`#proj-approvals-staging` vs production). -4. Test in a sandbox project. Seed fake items that mirror real field shapes, including edge cases like missing optional fields. +## Adding Mintlify as a required check -### Data contracts +To enforce previews and require a successful build before merging: -Confirm the payload your steps receive matches what integrations expect. A missing `requesterId` in test data can hide a production-only failure. +1. In GitHub, go to **Repository → Settings → Branches → Branch protection rules**. +2. Add a rule for your default branch. +3. Enable **Require status checks to pass before merging**. +4. Search for and add the Mintlify status check. -## Validation - -Run dry-run executions with sample payloads before enabling for all projects. Capture logs for the first ten production runs and compare timings to your SLA. - -### Rollout - -Enable for a pilot team, gather feedback on wording and timeouts, then expand. Feature-flag the workflow if your platform supports gradual exposure. +This prevents broken docs changes from reaching production. diff --git a/help-center/product/automation/workflows/conditions-branches.mdx b/help-center/product/automation/workflows/conditions-branches.mdx index d4f7759..efdbf49 100644 --- a/help-center/product/automation/workflows/conditions-branches.mdx +++ b/help-center/product/automation/workflows/conditions-branches.mdx @@ -1,35 +1,43 @@ --- -title: "Conditions and branches" -sidebarTitle: "Conditions & branches" -description: "Model conditional paths and merge strategies in workflows." +title: "Branch deployments" +sidebarTitle: "Branch deployments" +description: "Deploy specific branches to dedicated environments for staging and feature preview." --- -Branches let workflows mirror real decisions: approvals vs auto-reject, regional routing, or parallel reviews that must all pass. Invest time in condition clarity—ambiguous logic becomes expensive to debug under load. +Beyond PR previews, you can configure Mintlify to deploy specific branches to dedicated, persistent environments. This is useful for staging environments or long-running feature branches. -## Conditions +## Configure branch deployments -Express rules with comparisons on fields, regex, and presence checks. Prefer explicit comparisons over implicit truthiness so empty strings and nulls behave predictably. +1. Go to **Project Settings → Git → Additional branches**. +2. Add the branches or branch patterns you want to deploy automatically. +3. Each branch gets a unique subdomain: `[project]-[branch].mintlify.app`. -### Short-circuit behavior +### Branch patterns -Know whether conditions evaluate lazily. If expensive checks run even when a prior clause already failed, you may hit rate limits unnecessarily. +You can use wildcards to match multiple branches: +- `staging` — deploy the `staging` branch. +- `feature/*` — deploy any branch starting with `feature/`. +- `release/*` — deploy any branch starting with `release/`. -### Testing matrices +## Common patterns -Build a small table of inputs and expected branches before go-live. Include malformed payloads your API might emit during incidents. +### Staging environment -## Branches +Use a `staging` branch as a buffer before production. Writers merge to `staging` for internal review, then merge to `main` for production release. -Run mutually exclusive branches or parallel branches that join later. Parallel paths reduce latency but require clear merge semantics when both sides finish out of order. +``` +feature/update-api-docs → staging (internal review) → main (production) +``` -### Dependencies +### Version-specific docs -If branch B needs artifacts from branch A, enforce ordering with explicit dependencies rather than hoping wall-clock timing works out. +For products with multiple supported versions, deploy each version from a separate branch: -## Merge +- `v1` branch → `v1.docs.yourcompany.com` +- `v2` branch → `v2.docs.yourcompany.com` -Define how conflicting branch outputs combine—first wins, merge maps, or custom reducers. Document the merge rule in the workflow description so the next editor does not “simplify” it incorrectly. +Use Mintlify's versioning feature in `docs.json` to add a version selector within a single project instead if you prefer to keep versions in one place. -### Conflicts - -When two branches set the same field, specify precedence. Last-write-wins is easy but surprising; structured merges are safer for financial totals. + + Branch deployments count toward your plan's project limits. Check your plan details if you're adding many branch environments. + diff --git a/help-center/product/automation/workflows/error-handling.mdx b/help-center/product/automation/workflows/error-handling.mdx index eeb8e85..d07c747 100644 --- a/help-center/product/automation/workflows/error-handling.mdx +++ b/help-center/product/automation/workflows/error-handling.mdx @@ -1,39 +1,54 @@ --- -title: "Error handling" -sidebarTitle: "Error handling" -description: "Retries, compensating steps, and alerting when workflows fail." +title: "Handling build failures" +sidebarTitle: "Build failures" +description: "What to do when a Mintlify deployment fails." --- -Workflows fail in the real world: APIs time out, databases lock, humans go offline. Good error handling turns chaos into retries, compensations, and clear operator signals instead of silent data drift. +Build failures prevent your changes from going live. They're usually caused by MDX syntax errors, invalid `docs.json` configuration, or broken component references. -## Failures +## Find the error -Classify transient versus permanent failures. Transient steps should retry with jitter; permanent failures should stop fast and surface a crisp error code. +1. Go to **[Project] → Deployments** in your Mintlify dashboard. +2. Click the failed deployment to open its details. +3. Open the **Build log** tab. The error message near the bottom of the log usually identifies the file and line number causing the failure. -### Observability +## Common failure causes -Attach correlation IDs across steps so support can trace a single user action through every hop. Log HTTP status bodies at reduced verbosity to avoid leaking secrets. + + + MDX is stricter than Markdown. Common mistakes: + - Unclosed JSX tags (for example, `` without ``) + - HTML entities that need escaping (use `&` instead of `&`, `<` instead of `<`) + - Invalid frontmatter YAML (missing quotes around strings with special characters) -### Poison messages + Fix: Find the file and line mentioned in the build log and correct the syntax. + + + Invalid `docs.json` configuration fails the build. Common mistakes: + - A page listed in navigation that doesn't exist as an `.mdx` file + - Invalid JSON syntax (trailing commas, missing quotes) + - A required field missing (`name`, `theme`, `colors.primary`, or `navigation`) -If the same payload fails repeatedly, stop retrying and quarantine it—otherwise you starve healthy traffic. + Fix: Validate `docs.json` with a JSON linter and check that all referenced pages exist. + + + If your `docs.json` references a file that doesn't exist (for example, after renaming or deleting a page), the build fails. -## Compensation + Fix: Update `docs.json` to match the actual file paths in your repository. + + -Undo partial effects when a downstream step fails—especially for payments or external posts. Compensation may mean voiding an invoice, deleting a draft record, or sending a corrective webhook. +## Test locally before pushing -### Ordering +Use the Mintlify CLI to catch errors before they reach your repository: -Design compensations in reverse dependency order: undo the last successful side effect first. +```bash +npm i -g mintlify +mintlify dev +``` -### Partial success +The local dev server shows the same errors the build system would catch. Fix issues locally and push only when the local preview looks correct. -When only one of two external systems succeeded, document the manual reconciliation path in the alert body. +## Revert if needed -## Alerts - -Route failures to on-call channels with runbook links. Include workflow name, step name, and last payload hash—not full PII—in the first line of the alert. - -### Fatigue - -Throttle duplicate alerts for the same root cause. Pair alerts with dashboards so responders can see whether failures are trending or isolated. +If a deploy broke your live site, the quickest recovery is to revert the commit in Git. Mintlify deploys the reverted version automatically on the next push. diff --git a/help-center/product/automation/workflows/index.mdx b/help-center/product/automation/workflows/index.mdx index d6cdda6..75f48c8 100644 --- a/help-center/product/automation/workflows/index.mdx +++ b/help-center/product/automation/workflows/index.mdx @@ -1,9 +1,9 @@ --- -title: "Workflow builder" +title: "Deployment workflows" sidebarTitle: "Overview" -description: "Build multi-step workflows with branches and error handling." +description: "Set up branch deployments, PR previews, and CI/CD workflows for your docs." --- -Workflows chain steps with explicit data handoff. Use branches for conditional logic and centralized error handling to avoid partial updates. +Mintlify fits into your existing Git workflow. This section covers how to structure your deployment pipeline for different team sizes and review processes. -The following articles walk through your first workflow and deeper branching strategies. \ No newline at end of file +The following articles cover PR previews, branch deployment strategies, and handling build failures. diff --git a/help-center/product/editor/comments-mentions.mdx b/help-center/product/editor/comments-mentions.mdx index 77ccddd..c2ae130 100644 --- a/help-center/product/editor/comments-mentions.mdx +++ b/help-center/product/editor/comments-mentions.mdx @@ -1,39 +1,36 @@ --- -title: "Comments and mentions" -sidebarTitle: "Comments & mentions" -description: "Threaded comments, @mentions, and notification controls." +title: "Comments and collaboration" +sidebarTitle: "Comments" +description: "Leave comments on docs pages and collaborate with your team during review." --- -Comments turn static pages into lightweight review spaces. Mentions pull the right people into the loop without forwarding threads in email. This article covers threading, @mentions, and how to stay sane when notification volume spikes. +The Mintlify web editor supports inline comments, making it easy to give feedback on specific sections of a page during the review process. -## Threads +## Adding a comment -Start a thread on a selection. Resolve threads when addressed so everyone can see what is still open versus done. +1. Select the text you want to comment on. +2. Click the comment icon that appears in the toolbar. +3. Type your comment and press **Enter** to submit. -### Best practices +Comments are visible to all editors with access to the project. They appear as markers on the text and in a comments panel on the right side of the editor. -Keep one topic per thread when you can—easier to resolve and easier for newcomers to scan. Quote or anchor to specific paragraphs so replies stay in context months later. +## Resolving comments -### Permissions +When a comment has been addressed, click **Resolve** to close the thread. Resolved comments are hidden from the active view but remain in the comment history. -Readers may or may not see comment sidebars depending on project policy. If someone says they cannot view a thread, check their project role and whether the page is in a restricted space. +### Reviewing before publish -## Mentions - -@mention teammates to pull them in. Mentions respect project membership: you cannot @mention someone who should not already access the underlying content. - -### Typing and suggestions - -Most editors autocomplete @handles after a few characters. If a colleague recently joined, refresh the member list or wait for directory sync before assuming a name is missing. - -### Bots and integrations - -Some integrations post as service accounts. Mentions to those accounts may open tickets or chat channels—confirm behavior in your automation settings. +Before publishing a page, check the comments panel to make sure all open threads have been resolved. Unresolved comments don't block publishing, but they're a signal that someone is still waiting on a response. ## Notifications -Mute noisy threads or adjust frequency in personal notification settings. Batch digests work well for deep work; real-time alerts suit on-call rotations or launch weeks. +Mintlify sends email notifications when: +- Someone leaves a comment on a page you've edited. +- Someone replies to a thread you're part of. + +Adjust notification preferences in your account settings if the volume is too high. -### Email vs in-app +## Best practices -If email feels loud, switch critical threads to in-app only and reserve email for @mentions directly to you. Mobile push can mirror desktop preferences or be disabled for weekends. +- Use comments for feedback during review, not for long-term notes. Resolve threads once the issue is addressed. +- If you need to leave a note for future editors (not just reviewers), add it as a code comment in the MDX source instead — those persist in the file. diff --git a/help-center/product/editor/drafts-publishing.mdx b/help-center/product/editor/drafts-publishing.mdx index d0e013e..aa1fa4c 100644 --- a/help-center/product/editor/drafts-publishing.mdx +++ b/help-center/product/editor/drafts-publishing.mdx @@ -1,37 +1,39 @@ --- title: "Drafts and publishing" sidebarTitle: "Drafts & publishing" -description: "Draft states, review cues, and what happens when you publish." +description: "How drafts work in the web editor and what happens when you publish." --- -Drafts let you iterate without exposing work-in-progress to every reader. Publishing turns a snapshot into what visitors and integrations see. Use this guide to understand visibility rules, the publish action, and scheduled releases. +The web editor auto-saves your work as you type. Changes are private — they won't appear on your live docs site — until you click **Publish**. ## Drafts -Drafts are visible to editors you invite. Unpublished changes never appear to read-only roles, which keeps reviews and experiments contained until you are ready. +While you're editing, your changes are saved as a draft in Mintlify. Drafts are visible to other editors with access to the project, so collaborators can review your work before it goes live. -### Who can edit +### Multiple editors -Editors with access to the project can create and update drafts. Viewers and external roles only see the last published version for pages that use publishing—there is no “preview link” leakage unless you explicitly enable one. +If two editors are working on the same page at the same time, Mintlify merges changes on a section-by-section basis. For busy pages with frequent edits, coordinate with teammates to avoid editing the same section simultaneously. -### Autosave and conflicts +### Exiting without publishing -Edits typically save as you work. If two people edit the same section, you may see a merge prompt or last-write-wins behavior depending on your client—coordinate on busy pages or assign an owner during launches. +If you close the editor without publishing, your draft is saved. The next time you open the editor, you'll see the unpublished changes and can continue editing or discard them. -## Publish +## Publishing -Publishing snapshots content for readers and triggers webhooks if configured. Think of publish as a labeled release: SEO, feeds, and automations usually key off the published revision, not every keystroke. +Click **Publish** in the top-right corner of the editor to deploy your changes. Publishing commits your changes to the repository and triggers a new deployment. -### Before you publish +Deployments typically complete in 30–60 seconds. You can monitor the progress in your Mintlify dashboard under **Deployments**. -Skim the title, metadata, and any embedded media. Run a quick link check on high-traffic pages. If you use approvals, wait for the green light from reviewers named in your process. +### Before publishing -### After you publish +- Preview the page using the preview toggle in the editor. +- Check that all links point to valid pages. +- If the page includes a code example, verify it's accurate. -The prior published version remains in history, so you can roll forward again or restore if something looks off. Downstream systems that consume webhooks should treat duplicate delivery as idempotent where possible. +### After publishing -## Scheduling +The previous version of the page is preserved in your Git history. If you need to revert a change, you can do so via Git or by contacting support. -Schedule publish for a future time when your team coordinates launches—useful for announcements, pricing pages, and docs that must go live after a contract or feature flag flips. +## Scheduled publishing -Pick a timezone that matches how your team communicates (“end of day PT”) and confirm daylight-saving edge cases for global audiences. You can usually reschedule or cancel a queued publish until it actually runs. +Mintlify does not currently support scheduled publishing from the web editor. If you need to publish at a specific time, you can push a commit to your Git repository at the desired time, which will trigger a deployment automatically. diff --git a/help-center/product/editor/index.mdx b/help-center/product/editor/index.mdx index 634ef44..4b7a7e0 100644 --- a/help-center/product/editor/index.mdx +++ b/help-center/product/editor/index.mdx @@ -1,9 +1,9 @@ --- -title: "Editor and content" +title: "Web editor" sidebarTitle: "Overview" -description: "Drafts, publishing, comments, and version history in the editor." +description: "Write and publish docs in Mintlify's browser-based editor — no Git required." --- -The editor balances structured content with fast collaboration. Draft privately, publish when ready, and loop in teammates with comments. +The Mintlify web editor lets editors write, preview, and publish documentation directly in the browser. It's designed for writers and product managers who want to contribute to docs without learning Git or the command line. -Version history helps you recover from mistakes and audit meaningful changes. \ No newline at end of file +Changes made in the web editor are committed to your repository automatically and deploy when you publish. diff --git a/help-center/product/editor/version-history.mdx b/help-center/product/editor/version-history.mdx index 77510b9..6dcf2b2 100644 --- a/help-center/product/editor/version-history.mdx +++ b/help-center/product/editor/version-history.mdx @@ -1,39 +1,38 @@ --- -title: "Version history" +title: "Deployment history" sidebarTitle: "Version history" -description: "Browse versions, compare changes, and restore content." +description: "Browse past deployments, see what changed, and redeploy a previous version." --- -Version history is your safety net: every meaningful save becomes a checkpoint you can compare, audit, or restore. Use it after bad merges, to see who changed a policy line, or to copy text from an older revision without undoing newer work elsewhere. +Every time you publish changes, Mintlify creates a new deployment. You can browse deployment history, see what changed in each deploy, and redeploy a previous version if needed. -## Timeline +## View deployment history -Open history to see chronological snapshots with author attribution. Each entry usually includes a timestamp, editor, and optional note if your team labels releases. +In your Mintlify dashboard, go to **[Project] → Deployments**. The list shows every deployment with: +- The commit message and Git SHA. +- The author and timestamp. +- The deployment status (success, failed, or building). -### Retention +Click any deployment to see its details, including the build log. -How long versions are kept depends on your plan and admin policy. Legal or regulated teams should confirm retention meets internal records rules before relying on history alone for compliance. +## What changed -### Naming and bookmarks +Each deployment links to a Git commit. Click **View commit** to see the full diff in GitHub or GitLab — every page change, navigation update, and configuration change. -If your product supports labels or tags on versions, use them for “before migration” or “approved by legal” so you can find needles in long timelines. +### For web editor changes -## Compare +Web editor publishes create commits with the message `Update [page title]` and your Mintlify account as the author. The commit contains the MDX file changes for pages you edited. -Diff view highlights additions and removals between versions. Use split view for prose and unified view for small edits. +## Redeploy a previous version -### Large pages +If a deploy introduced a problem and you need to roll back: -Very long pages may lazy-load diff segments. If something looks blank, scroll the full height or expand collapsed regions. +1. Go to **[Project] → Deployments**. +2. Find the last known-good deployment. +3. Click **Redeploy** to re-run that deployment. -### Binary and embeds +Alternatively, revert the commit in your Git repository — Mintlify will automatically deploy the reverted version. -Embedded media may show as changed when URLs rotate even if text is identical—compare surrounding paragraphs to confirm intent. - -## Restore - -Restore creates a new version based on the selected snapshot—nothing is silently overwritten. That means you keep a clear audit trail: the restore event itself is a new entry. - -### Communicate restores - -Tell collaborators when you roll back shared pages so they do not re-introduce outdated facts on top of your fix. Link to the restored version in your team chat or ticket. + + For critical docs sites (API references, onboarding guides), test significant changes in a preview deployment before merging to your default branch. Pull request previews give you a live URL to share for review. + diff --git a/help-center/product/index.mdx b/help-center/product/index.mdx index c156a33..7649f7b 100644 --- a/help-center/product/index.mdx +++ b/help-center/product/index.mdx @@ -1,9 +1,9 @@ --- title: "Product guides" sidebarTitle: "Overview" -description: "Learn the interface, projects, editor, and automation features." +description: "Learn the Mintlify dashboard, web editor, projects, and deployments." --- -This section is your field guide to everyday work: navigating the interface, structuring projects, writing content, and automating repeatable work. +This section covers everything you need to work effectively in Mintlify day-to-day: navigating the dashboard, writing content in the web editor, managing your docs projects, and understanding how deployments work. -Jump to any article from the sidebar—the structure mirrors how teams typically roll out from first login to advanced workflows. \ No newline at end of file +Start with the interface overview if you're new, or jump directly to the article that matches what you're trying to do. diff --git a/help-center/product/interface-overview.mdx b/help-center/product/interface-overview.mdx index 4159648..0d23fb0 100644 --- a/help-center/product/interface-overview.mdx +++ b/help-center/product/interface-overview.mdx @@ -1,33 +1,37 @@ --- -title: "Interface overview" +title: "Dashboard and editor overview" sidebarTitle: "Interface" -description: "Sidebar, command palette, and where to find settings." +description: "The Mintlify dashboard, web editor layout, and where to find key settings." --- -The product shell is designed to keep navigation predictable: primary work happens in the center, global navigation stays on the left, and contextual actions stay close to what you selected. Spend a few minutes learning the three regions below—you will move between them constantly. +Mintlify has two main interfaces: the **dashboard** (where you manage projects, deployments, and settings) and the **web editor** (where you write and publish content). -## Layout +## Dashboard -- **Sidebar** — Projects, automation, and account entry points. Pin favorites if your client supports it so daily spaces stay one click away. -- **Canvas** — The main surface for viewing and editing work. On smaller screens the sidebar may collapse; use the menu control to reopen it without losing context. -- **Inspector** — Metadata and contextual actions for the current selection. Empty states usually mean “nothing selected yet” rather than missing permissions. +The dashboard at [dashboard.mintlify.com](https://dashboard.mintlify.com) is the home for your organization and projects. -### Focus and panels +- **Projects** — Each docs site is a project. The project overview shows the latest deployment, the live URL, and access to settings. +- **Settings** — Organization-level settings for members, billing, security, and integrations. +- **Analytics** — Page views, search queries, and feedback (available on Growth and Enterprise plans). -Some workflows open transient panels (comments, history, AI). Closing a panel returns focus to the canvas; keyboard users can tab through interactive regions in DOM order. +### Project settings -## Command palette +Project settings control the Git connection, custom domain, authentication, and member access for a specific docs site. Access them from **[Project] → Settings**. + +## Web editor -Open the palette to jump anywhere quickly. It respects your permissions—destinations you cannot access simply do not appear or show as disabled with a reason. +The web editor provides a WYSIWYG interface for writing MDX pages without touching the command line. Open it by clicking **Edit** on a project or navigating directly to your docs site and clicking the edit button (requires editor or admin access). -### Search vs navigate +### Editor layout -Use the palette for fuzzy jumps when you know a name fragment. Use the global search entry when you need full-text results across bodies and attachments. +- **Sidebar** — Page tree showing all files in your docs. Create, rename, and organize pages here. +- **Canvas** — The main editing area. Supports rich text, MDX components, and code blocks. +- **Preview** — A live preview of how the page will look. Toggle between edit and preview mode. -## Settings +### Publish button -Workspace settings live under your avatar; project settings are scoped per project. When in doubt, check the breadcrumb or page title so you do not change org-wide SSO while meaning to tweak a single project’s webhook. +Changes in the web editor are saved as drafts automatically. Click **Publish** to deploy changes to your live site. The publish action triggers a new deployment, which typically takes about 30 seconds. -### Auditing changes +## Command palette -Admins should review who last changed workspace defaults after reorganizations. Project-level changes are easier to isolate in activity logs when each team owns its space. +Press `⌘K` (or `Ctrl+K`) to open the command palette. Use it to navigate between pages, run actions, and search your docs content. diff --git a/help-center/product/keyboard-shortcuts.mdx b/help-center/product/keyboard-shortcuts.mdx index a6a64ae..102ff56 100644 --- a/help-center/product/keyboard-shortcuts.mdx +++ b/help-center/product/keyboard-shortcuts.mdx @@ -1,39 +1,45 @@ --- title: "Keyboard shortcuts" sidebarTitle: "Shortcuts" -description: "Speed up navigation and editing with keyboard shortcuts." +description: "Speed up navigation and editing in the Mintlify web editor and dashboard." --- -Shortcuts reduce context switching: keep hands on the keyboard for formatting, navigation, and comments. The tables below cover common defaults; your organization may publish a one-page cheat sheet for onboarding. +Keyboard shortcuts make navigating and editing faster. Here are the most useful ones for the Mintlify web editor and dashboard. -## General +## Global | Action | Shortcut | |--------|----------| -| Command palette | ⌘K / Ctrl+K | -| Search | ⌘P / Ctrl+P | +| Open command palette | `⌘K` / `Ctrl+K` | +| Open search | `⌘K` / `Ctrl+K`, then type | +| Toggle dark mode | Available in the user menu | -On Windows and Linux, **Ctrl** replaces **⌘** where both are listed. If a shortcut conflicts with your browser or OS, disable the conflicting extension or remap inside the product when supported. +On Windows and Linux, `Ctrl` replaces `⌘` in all shortcuts. -## Editor +## Web editor | Action | Shortcut | |--------|----------| -| Bold | ⌘B / Ctrl+B | -| Comment | ⌘⌥M / Ctrl+Alt+M | +| Bold | `⌘B` / `Ctrl+B` | +| Italic | `⌘I` / `Ctrl+I` | +| Inline code | `⌘E` / `Ctrl+E` | +| Add link | `⌘K` / `Ctrl+K` (with text selected) | +| Heading 1 | `#` at the start of a line | +| Heading 2 | `##` at the start of a line | +| Heading 3 | `###` at the start of a line | +| Bulleted list | `-` at the start of a line | +| Numbered list | `1.` at the start of a line | -### Selection and blocks +## Component shortcuts -Many editors support **⌘D** / **Ctrl+D** for multi-cursor or duplicate-line behaviors—check in-app hints because they can vary by block type (paragraph vs code). +Type `/` at the beginning of a line to open the component picker. Start typing the component name to filter: -### Accessibility +- `/note` → Insert a Note callout +- `/warning` → Insert a Warning callout +- `/steps` → Insert a Steps component +- `/code` → Insert a code block +- `/card` → Insert a Card -If reduced-motion or sticky keys are enabled at the OS level, chord shortcuts may require slower presses. Screen reader users should verify focus lands in the expected region after palette commands. +## Markdown -## Customize - -Some shortcuts can be remapped in **Settings → Accessibility** on supported clients. Export your mapping before switching machines so you can import or recreate it on a new laptop. - -### Conflicts with input methods - -IME users composing CJK text may need to disable certain chords temporarily or use the command palette instead of direct shortcuts that steal modifier keys. +The Mintlify web editor understands standard Markdown shortcuts. Most formatting can be applied either through the toolbar or via keyboard. If you're more comfortable writing raw MDX, switch to the code view using the toggle in the top-right corner of the editor. diff --git a/help-center/product/projects/archive-restore.mdx b/help-center/product/projects/archive-restore.mdx index 0678f27..f75792f 100644 --- a/help-center/product/projects/archive-restore.mdx +++ b/help-center/product/projects/archive-restore.mdx @@ -1,31 +1,47 @@ --- -title: "Archive and restore projects" +title: "Archive and restore a project" sidebarTitle: "Archive & restore" -description: "Archive completed work and restore when needed." +description: "Pause a Mintlify project without deleting it, and restore it when needed." --- -Archiving is the gentle off-ramp for completed initiatives: out of default lists, but recoverable when a customer reopens a contract or an audit asks for historical context. Plan exports before archive if compliance requires cold storage. +Archiving a Mintlify project stops new deployments and makes the project inactive, but doesn't delete your repository or any content. You can restore an archived project at any time. -## Archive +## Archive a project -Archiving hides a project from default lists while preserving history. Automation pauses so you do not enqueue jobs against dormant data. +1. Open the project in your Mintlify dashboard. +2. Go to **Settings → Danger zone**. +3. Click **Archive project** and confirm. -### Communication +After archiving: +- The project no longer appears in your main project list (it moves to **Archived projects**). +- No new deployments will trigger from Git pushes. +- The live site URL continues to serve the last deployed version. -Tell stakeholders when you archive so they do not think content was deleted. Link to the new canonical project if work continued elsewhere. +### When to archive -### Partial archives +Archive a project when: +- A product or docs site is retired but you want to preserve access to the last live version. +- You're restructuring projects and want to consolidate docs into a new project. +- The project is on hold and you don't want accidental deploys from stale branches. -If only one stream is done, consider labels or subfolders instead of whole-project archive when other tracks remain active. +## Restore a project -## Restore +1. Go to your dashboard and click **Archived projects**. +2. Find the project and click **Restore**. -Workspace admins can restore within the retention window. Older archives may require support if your policy moved data to long-term storage. +Restoring reactivates the project — deployments will trigger again on the next Git push. -### Validation after restore +### After restoring -Spot-check permissions and integrations after restore—tokens may have rotated while the project was idle. +- Check that the GitHub App still has access to the repository (it may have been updated while the project was archived). +- Trigger a manual deploy if the repository has changed since archiving: go to **Project → Deployments → Redeploy**. -## Compliance +## Delete a project -Export before archive if your policy requires long-term cold storage outside the product. Keep checksums or manifest files so legal can prove what was frozen at a point in time. +Deleting a project is permanent and cannot be undone. It removes the project from Mintlify but does not delete your Git repository. + +To delete: **Settings → Danger zone → Delete project**. You must type the project name to confirm. + + + Deleting a project removes all Mintlify-side configuration, analytics history, and custom domain settings. Export any analytics data you want to keep before deleting. + diff --git a/help-center/product/projects/create-project.mdx b/help-center/product/projects/create-project.mdx index 6edc286..1cc0939 100644 --- a/help-center/product/projects/create-project.mdx +++ b/help-center/product/projects/create-project.mdx @@ -1,35 +1,39 @@ --- title: "Create a project" sidebarTitle: "Create a project" -description: "Name, visibility, and defaults when starting a new project." +description: "Set up a new Mintlify docs site from an existing repository or from scratch." --- -Projects are the boundary for permissions, notifications, and automation. Spending two minutes on naming and visibility up front prevents accidental exposure later—especially when customers or partners are invited. +Each Mintlify project corresponds to one docs site, backed by a Git repository. You can create a project from an existing repository or let Mintlify create a new one. -## Create flow +## From an existing repository -Click **New project**, choose a name, and pick visibility: workspace-only or invite-only. Invite-only is appropriate when content must not be discoverable by everyone in the org directory. + + + Go to [dashboard.mintlify.com](https://dashboard.mintlify.com) and click **New project**. + + + Select your Git provider (GitHub or GitLab) and choose the repository. If you don't see the repository, check that the Mintlify GitHub App is installed on the correct organization. + + + Set the **Docs root** if your documentation lives in a subdirectory (for example, `docs/`). Leave it empty if your docs are at the repository root. -### Naming + Give the project a name — this is how it appears in your dashboard. + + + Click **Create project**. Mintlify clones the repository and starts the first build. Your site will be live at a `*.mintlify.app` URL within a minute or two. + + -Use a name people will recognize in notifications and URLs. Avoid confidential codenames in titles if screenshots might leak; put codenames in an internal field instead. +## From a template -### Ownership +If you don't have an existing docs repository, Mintlify can create one for you from a starter template: -Assign an owner who can approve membership changes. Orphan projects without owners tend to accumulate stale access lists. +1. Click **New project → Start from template**. +2. Choose a template (blank, API reference, help center, etc.). +3. Choose or create a GitHub repository for the template to be pushed to. +4. Complete the setup — Mintlify creates the repo, installs the GitHub App, and deploys the starter site. -## Templates +## Project naming -Start from blank or apply a template with prebuilt sections for your team’s process. Templates accelerate rollout but still need a quick review—remove sample text that could confuse readers. - -### Forking templates - -When you customize a template heavily, save a new template version so other teams inherit your improvements instead of editing one-off copies. - -## Defaults - -Set default labels and owners so new items do not land unassigned. Defaults reduce “triage debt” on Monday mornings when many items are created at once. - -### Iteration - -Revisit defaults after major process changes (new severity model, new regions). Old defaults silently mis-route work if nobody updates them after a reorg. +Use a descriptive name that helps you identify the project in the dashboard — especially if you have multiple docs sites. Good names reference the product or audience: `API Reference`, `Developer Docs`, `Internal Runbooks`. diff --git a/help-center/product/projects/index.mdx b/help-center/product/projects/index.mdx index 0d0e557..1a17bcf 100644 --- a/help-center/product/projects/index.mdx +++ b/help-center/product/projects/index.mdx @@ -1,9 +1,9 @@ --- title: "Projects" sidebarTitle: "Overview" -description: "Create projects, organize work, and archive when you are done." +description: "Manage your Mintlify docs projects — create, configure, and archive them." --- -Projects are the primary container for collaborative work. Permissions, automation, and notifications can all be scoped to a project. +A project is a single docs site in Mintlify. Each project connects to a Git repository and deploys independently. -Use the articles here to create your first project and manage its lifecycle responsibly. \ No newline at end of file +Use the articles in this section to create a new project or manage the lifecycle of an existing one. diff --git a/help-center/product/search-navigation.mdx b/help-center/product/search-navigation.mdx index 359bb1f..4c6f77e 100644 --- a/help-center/product/search-navigation.mdx +++ b/help-center/product/search-navigation.mdx @@ -1,35 +1,41 @@ --- title: "Search and navigation" sidebarTitle: "Search" -description: "Find projects, pages, and automation using search." +description: "How search works on your Mintlify docs site and how to configure navigation." --- -Search is the fastest path from “where was that?” to the right page—especially as your workspace grows. Combine query syntax, filters, and recents to cut noise and land on canonical answers your team already wrote. +Mintlify includes built-in search on every docs site. No external search provider or index configuration required. -## Global search +## Reader search -Search spans titles, bodies, and selected metadata. Filters narrow results by owner, date, and type so you can answer “what changed last week?” without scanning every project. +Readers can search your docs by clicking the search bar or pressing `⌘K`. Search covers page titles, headings, and body content. -### Operators +### AI search -Use quoted phrases for exact matches and minus terms to exclude noise (for example, a term you know appears in boilerplate). Combine filters when you remember the author but not the title. +On Growth and Enterprise plans, enable AI search in **Project Settings → Search**. AI search understands natural language questions — readers can ask "how do I do X?" and get a direct answer drawn from your docs, rather than a list of links. -### Ranking +### Search analytics -Results usually favor recent edits and stronger title matches. If something ranks oddly, try a more specific phrase or open the containing project and browse by folder structure. +The **Analytics → Search** tab in your dashboard shows what readers are searching for, including queries that returned no results. Use the "no results" list to identify gaps in your documentation. -## Recent +## Site navigation -Recent items appear in the sidebar for fast return visits. Clear recents when demoing or handing off a laptop so you do not leak internal titles on a shared screen. +Your docs site's navigation is defined in `docs.json`. The sidebar structure supports: -### Pinning +- **Groups** — Collapsible sections containing pages. +- **Tabs** — A top-level nav bar for switching between major sections. +- **Anchors** — Persistent links to external URLs or specific pages, always visible in the sidebar. -If your client supports pins or favorites, use them for runbooks and onboarding hubs you open daily—faster than typing the same query repeatedly. +### Tips for good navigation -## Tips +- Keep group names short and action-oriented ("Get started", "Configure", "Reference"). +- Limit nesting to 2-3 levels — deeper hierarchies are hard to scan. +- Use anchors for frequently accessed external links like your API reference or changelog. -Use quoted phrases for exact matches and minus terms to exclude noise. When you find the canonical page, add a short internal link from related articles so the next person finds it in one click. +## Editor navigation -### When search is not enough +In the web editor, the sidebar on the left shows all pages in your docs site. You can drag pages to reorder them, create new pages with the `+` button, and rename pages by clicking on their name. -If content is missing, file a docs ticket or add a stub page—search cannot surface what does not exist yet. For automation IDs, search by stable slug or external key when titles drift. + + Navigation order in the web editor reflects the order in `docs.json`. If you reorder pages in `docs.json` directly via Git, the change will appear in the editor after the next sync. + diff --git a/help-center/support/account-data/delete-account.mdx b/help-center/support/account-data/delete-account.mdx index a62f8d9..19c29be 100644 --- a/help-center/support/account-data/delete-account.mdx +++ b/help-center/support/account-data/delete-account.mdx @@ -1,31 +1,40 @@ --- -title: "Delete your account" +title: "Delete your account or project" sidebarTitle: "Delete account" -description: "Understand deletion impact and required confirmations." +description: "Close your Mintlify account or delete a project." --- -Deletion is destructive. Treat it like a production change: announce, export, and verify integrations will not recreate data you meant to purge. +You can delete individual projects or close your entire Mintlify organization. Both actions are permanent after the confirmation step. -## Workspace deletion +## Delete a project -Deleting a workspace is irreversible after the cooling-off period. Notify members first. +Deleting a project removes it from Mintlify but does not delete your Git repository or the content in it. -### Dependencies +1. Open the project in your dashboard. +2. Go to **Settings → Danger zone**. +3. Click **Delete project** and type the project name to confirm. -Disconnect billing identities, SSO apps, and webhooks before deletion—orphaned automation can still fire against deleted IDs in some systems. +After deletion: +- The `*.mintlify.app` URL stops serving your site. +- Any custom domain configuration is removed. +- Analytics history for the project is deleted. +- Your Git repository and all content remain intact. -## Personal account + + Custom domain DNS records are not automatically removed from your DNS provider. Remove the CNAME or ALIAS record manually to avoid a dangling DNS entry. + -Personal deletion removes your profile from associated workspaces per policy. +## Close your organization -### Identity recovery +Closing your organization deletes all projects under it and cancels your subscription. -If you might return, understand whether email addresses can be reused later or remain locked to prevent impersonation. +1. Go to **Settings → Danger zone**. +2. Click **Close organization** and confirm. -## Backups +Contact [support@mintlify.com](mailto:support@mintlify.com) if you need help closing your account or if you have billing questions related to account closure. -Export before deletion if you need records for compliance. +## Before deleting -### Certificates - -Download or transfer domain verification records if your brand moves to another provider. +- Export any analytics data you want to keep (it won't be recoverable after deletion). +- Remove the Mintlify GitHub App from your GitHub organization if you don't plan to use Mintlify again — it's in **GitHub → Settings → Integrations → Installed GitHub Apps**. +- Cancel any active subscriptions to avoid being charged after deletion. diff --git a/help-center/support/account-data/export-data.mdx b/help-center/support/account-data/export-data.mdx index e73ba13..13513f5 100644 --- a/help-center/support/account-data/export-data.mdx +++ b/help-center/support/account-data/export-data.mdx @@ -1,31 +1,37 @@ --- -title: "Export your data" +title: "Export your content" sidebarTitle: "Export data" -description: "Request exports, formats, and retention notes for your data." +description: "How to export your Mintlify docs content and configuration." --- -Exports let you back up, migrate, or satisfy access requests. Plan format and scope before you click—large workspaces can queue for a while and may need multiple partial exports. +Because Mintlify is Git-backed, your docs content is always available in your repository — you already own it. There's no proprietary export step needed for your pages. -## Self-serve export +## What you own (in your repository) -Admins can export project bundles in standard formats from **Settings → Data**. +- All MDX page files. +- Your `docs.json` configuration. +- Images and other assets in your repository. -### Format choices +This content is in your Git repository and accessible regardless of your Mintlify account status. -Pick structured formats your downstream tools ingest—JSON for pipelines, PDF for human review. +## What Mintlify stores (accessible from the dashboard) -## Timing +- **Analytics data** — Page views, search queries, and feedback. Export analytics data before closing your account. +- **Deployment history** — A log of all deployments, including timestamps and commit messages. +- **Member and access logs** — Audit logs of membership changes (Enterprise plans). -Large exports queue asynchronously; you receive email when ready. +### Export analytics data -### Partial failures +Currently, analytics data can be viewed in the dashboard but doesn't have a one-click export. Connect a third-party analytics provider (PostHog, GA4, etc.) to retain your analytics data outside Mintlify. See [Connect an analytics provider](/getting-started/integrations/connect-crm) for setup. -If an export completes with warnings, read the manifest for skipped objects—permissions or corrupt attachments are common causes. +## Migrating away from Mintlify -## Scope +If you're migrating to a different docs platform: -Exports include content you have permission to read—respect confidentiality when sharing files. +1. Your MDX content can be used with any MDX-compatible platform. +2. Your `docs.json` navigation structure may need to be adapted to the target platform's configuration format. +3. Mintlify-specific components (``, ``, etc.) will need to be replaced with the target platform's equivalents or converted to standard Markdown. -### Legal holds - -Consult counsel before exporting if litigation holds apply—some systems block export or require approval. + + Keep your docs in plain Markdown and standard MDX components where possible — it makes future migrations much simpler. + diff --git a/help-center/support/account-data/index.mdx b/help-center/support/account-data/index.mdx index 9def6a3..9f73c61 100644 --- a/help-center/support/account-data/index.mdx +++ b/help-center/support/account-data/index.mdx @@ -1,9 +1,7 @@ --- title: "Account and data" sidebarTitle: "Overview" -description: "Export your data and understand account deletion." +description: "Export your docs content and manage your Mintlify account." --- -You should always know what you can take with you and what happens when an account ends. - -Use export for portability and follow deletion steps carefully when offboarding a workspace. \ No newline at end of file +Your content lives in your Git repository — not locked inside Mintlify. This section explains how to export your data and what happens when you close your account. diff --git a/help-center/support/contact-support.mdx b/help-center/support/contact-support.mdx index cfe0ce5..5f7f32e 100644 --- a/help-center/support/contact-support.mdx +++ b/help-center/support/contact-support.mdx @@ -1,36 +1,46 @@ --- -title: "Contact support" +title: "Contact Mintlify support" sidebarTitle: "Contact support" -description: "Channels, severity levels, and what to include in a support request." +description: "How to reach Mintlify support and what to include in your request." --- -Good support tickets get answers faster. Lead with impact, narrow the blast radius with IDs, and attach evidence your team already has—logs, HAR files, or screen recordings for UI issues. +Mintlify offers several support channels depending on your plan. -## Channels +## Support channels -- In-app chat on Team and Enterprise -- Email for billing and security questions + + + Available on Growth and Enterprise plans. Click the chat icon in the Mintlify dashboard to start a conversation with the support team. + + + Email [support@mintlify.com](mailto:support@mintlify.com) for billing questions, security concerns, and issues not covered by in-app chat. + + + Join the [Mintlify community](https://mintlify.com/community) to ask questions, share feedback, and get help from other Mintlify users. + + + File bug reports and feature requests on the [Mintlify GitHub repository](https://github.com/mintlify/mintlify). + + -### Routing +## What to include in a support request -Use the channel your contract lists for Sev1 incidents. Misrouted tickets lose time to handoffs. +The faster you can describe the problem, the faster support can help. Include: -## Severity +- **What you expected to happen** and **what actually happened**. +- **The project URL** and a link to the specific page or deployment if relevant. +- **Steps to reproduce** — the more specific, the better. +- **The build log URL** if your issue is a deployment failure (copy from **[Project] → Deployments → [Failed deploy] → Build log**). +- **Error messages** — paste the exact text rather than paraphrasing. -Mark production outages as highest severity with clear customer impact. +### Sensitive information -### Be specific +Remove API keys, passwords, and personal data before sharing logs or screenshots. If you need to share sensitive details, say so and support will provide a secure channel. -“Slow” is vague; “API p95 latency 8s since 14:05 UTC on `/v1/items`” is actionable. Include approximate user count affected. +## Response times -## Good requests - -Include timestamps, URLs, request IDs, and steps to reproduce. - -### Redaction - -Remove secrets from pasted logs—rotate anything that leaks accidentally. - -### Follow-ups - -If you discover new data after filing, reply on the same thread so context stays unified. +| Plan | Channel | Typical response | +|------|---------|-----------------| +| Starter | Community, email | 2–5 business days | +| Growth | In-app chat, email | 1 business day | +| Enterprise | In-app chat, email, dedicated Slack | SLA per contract | diff --git a/help-center/support/index.mdx b/help-center/support/index.mdx index 47f9d86..60168af 100644 --- a/help-center/support/index.mdx +++ b/help-center/support/index.mdx @@ -1,9 +1,9 @@ --- title: "Support and policies" sidebarTitle: "Overview" -description: "Get help, check status, troubleshoot, and review legal information." +description: "Get help from Mintlify, check service status, and review legal information." --- -This section covers how to reach us, what to do when something breaks, how to manage your data, and the legal agreements that govern use of the service in this demo. +This section covers how to reach Mintlify support, how to check whether there's an active incident, and the legal agreements that govern use of Mintlify. -Nothing here is legal advice—replace with your counsel-approved text in production. \ No newline at end of file +If something isn't working, start with the [troubleshooting guides](/support/troubleshooting) — most common issues have quick fixes. diff --git a/help-center/support/legal/index.mdx b/help-center/support/legal/index.mdx index 64ffc90..037195c 100644 --- a/help-center/support/legal/index.mdx +++ b/help-center/support/legal/index.mdx @@ -1,9 +1,9 @@ --- title: "Legal and compliance" sidebarTitle: "Overview" -description: "Terms, privacy, regions, and compliance topics in this demo." +description: "Mintlify's terms of service, privacy policy, and compliance information." --- -Legal documents define how you may use the service. This hub links to terms, privacy materials, and regional notes used for the demo help center. +This section contains Mintlify's legal documents and compliance information. If you have questions not answered here, contact [legal@mintlify.com](mailto:legal@mintlify.com). -Replace placeholder text with counsel-reviewed language before production use. \ No newline at end of file +For enterprise procurement, DPA review, or security questionnaires, contact [sales@mintlify.com](mailto:sales@mintlify.com). diff --git a/help-center/support/legal/privacy/dpa.mdx b/help-center/support/legal/privacy/dpa.mdx index 91042a3..32143ff 100644 --- a/help-center/support/legal/privacy/dpa.mdx +++ b/help-center/support/legal/privacy/dpa.mdx @@ -1,31 +1,34 @@ --- title: "Data processing addendum" sidebarTitle: "DPA" -description: "Demo DPA overview for controllers and processors." +description: "Mintlify's data processing addendum for GDPR and enterprise compliance." --- -A DPA formalizes GDPR-style obligations between controllers and processors: instructions, subprocessors, security measures, and breach notification. Use this outline as a starting point for legal review—not as executed terms. +Mintlify offers a Data Processing Addendum (DPA) for customers who need to formalize the data processing relationship under GDPR or other data protection regulations. -## Roles +## When you need a DPA -You may act as a controller and the provider as a processor for certain processing activities. +You may need a DPA if: +- Your organization is subject to GDPR (you're based in the EU or process data of EU residents). +- Your organization's security or legal team requires a signed data processing agreement with vendors. +- Your procurement process requires formal documentation of data processing relationships. -### Sub-processing +## Getting a signed DPA -Specify whether prior approval is required for new subprocessors and how objections are handled. +**Self-serve (Growth plans):** Download and sign Mintlify's standard DPA from **Settings → Legal → DPA**. The standard DPA covers the most common requirements for GDPR compliance. -## Instructions +**Custom DPA (Enterprise):** Enterprise customers can negotiate custom DPA terms. Contact [legal@mintlify.com](mailto:legal@mintlify.com) with your requirements. -Processing follows your documented instructions and applicable law. +## What the DPA covers -### Change control - -Define how processing instructions change over time—ticket references, email approvals, or signed addenda. +Mintlify's DPA addresses: +- Roles: Mintlify acts as a data processor; you act as the controller. +- Processing purposes and lawful basis. +- Technical and organizational security measures. +- Subprocessor obligations and change notification. +- Data subject rights and breach notification procedures. +- Cross-border data transfer mechanisms (SCCs for EU-US transfers). ## Subprocessors -Review the subprocessors page for infrastructure providers and their purposes. - -### Audits - -Enterprise agreements often include audit rights, questionnaires, and evidence timelines—negotiate frequency and scope explicitly. +Mintlify uses third-party subprocessors to deliver the service. See [Subprocessors](/support/legal/privacy/subprocessors) for the current list. Mintlify notifies customers of subprocessor changes with 30 days' notice. diff --git a/help-center/support/legal/privacy/index.mdx b/help-center/support/legal/privacy/index.mdx index 108d123..f896629 100644 --- a/help-center/support/legal/privacy/index.mdx +++ b/help-center/support/legal/privacy/index.mdx @@ -1,9 +1,9 @@ --- -title: "Privacy and GDPR" +title: "Privacy and data" sidebarTitle: "Overview" -description: "Privacy policy, DPA, and subprocessors for this demo." +description: "Mintlify's privacy practices, data processing, and GDPR compliance." --- -Privacy practices describe what we collect, why, and how long we keep it. In this template, content is representative. +Mintlify is committed to protecting your data and that of your readers. This section covers our privacy policy, data processing agreement, and subprocessor list. -Pair these articles with your actual privacy program and subprocessors list in production. \ No newline at end of file +For data privacy requests (access, deletion, correction), email [privacy@mintlify.com](mailto:privacy@mintlify.com). diff --git a/help-center/support/legal/privacy/privacy-policy.mdx b/help-center/support/legal/privacy/privacy-policy.mdx index ffc333c..fe3a099 100644 --- a/help-center/support/legal/privacy/privacy-policy.mdx +++ b/help-center/support/legal/privacy/privacy-policy.mdx @@ -1,31 +1,40 @@ --- title: "Privacy policy" sidebarTitle: "Privacy policy" -description: "Demo privacy policy for this help center." +description: "How Mintlify collects, uses, and protects your data." --- -Privacy policies describe what you collect, why, how long you keep it, and who you share it with. This template sketches sections only—your counsel should align it with your actual processing activities and jurisdictions. +This privacy policy describes how Mintlify collects and uses data from customers (organizations using Mintlify to build docs) and readers (people visiting docs sites hosted on Mintlify). -## Data we process +## Data we collect -Account data, usage telemetry, and content you store in the product for demonstration purposes. +**Account data** — Name, email address, and authentication credentials for Mintlify account holders. -### Sensitive categories +**Usage data** — Information about how you use the Mintlify dashboard and web editor, including pages visited, actions taken, and feature usage. -If you process health, financial, or children’s data, add explicit sections and lawful bases—generic text is insufficient. +**Docs content** — The MDX files and assets in your connected repository. Mintlify processes this data to build and serve your docs site. -## Purposes +**Reader analytics** — Page views, search queries, feedback votes, and AI assistant interactions on your docs site. This data is attributed to your organization and used to power the analytics dashboard. -Operate the service, secure accounts, and improve reliability. +## How we use data -### Analytics +- To operate and improve the Mintlify platform. +- To provide customer support. +- To send transactional notifications (deployment alerts, billing receipts). +- To power the analytics dashboard and AI search features. -Disclose whether you use analytics, session replay, or error tracking—and how users can opt out where required. +## Data sharing -## Rights +Mintlify does not sell your data. We share data with subprocessors as needed to operate the service (see [Subprocessors](/support/legal/privacy/subprocessors)). We may disclose data in response to valid legal requests. -Depending on region, you may have rights to access, correct, or delete personal data—see regional articles. +## Your rights -### Requests +Depending on your location, you may have rights to access, correct, delete, or export your personal data. Submit requests to [privacy@mintlify.com](mailto:privacy@mintlify.com). -Describe how individuals submit requests, expected response times, and appeal paths if you deny a request. +## Retention + +We retain account data for the duration of your account and a reasonable period after closure. Analytics data is retained for up to 24 months. You can request earlier deletion by contacting [privacy@mintlify.com](mailto:privacy@mintlify.com). + +--- + +*For the current, legally binding version of Mintlify's Privacy Policy, visit [mintlify.com/legal/privacy](https://mintlify.com/legal/privacy).* diff --git a/help-center/support/legal/privacy/subprocessors.mdx b/help-center/support/legal/privacy/subprocessors.mdx index e0853e4..99cad6d 100644 --- a/help-center/support/legal/privacy/subprocessors.mdx +++ b/help-center/support/legal/privacy/subprocessors.mdx @@ -1,31 +1,36 @@ --- title: "Subprocessors" sidebarTitle: "Subprocessors" -description: "Illustrative list of subprocessors for this demo." +description: "Third-party services Mintlify uses to process customer data." --- -Subprocessors extend your security perimeter—customers review them for data residency, certifications, and incident history. Keep this list current; stale entries erode trust during procurement. +Mintlify uses the following third-party subprocessors to deliver the platform. All subprocessors are contractually bound to protect data in accordance with Mintlify's DPA. ## Infrastructure -Hosting and networking vendors that operate regions you select. +| Subprocessor | Purpose | Data location | +|-------------|---------|--------------| +| Amazon Web Services (AWS) | Cloud infrastructure for hosting and compute | US, EU | +| Cloudflare | CDN, DDoS protection, and DNS | Global | -### Certifications +## Product and operations -Link SOC 2, ISO, or FedRAMP reports where applicable so enterprise teams can self-serve. +| Subprocessor | Purpose | Data processed | +|-------------|---------|----------------| +| Vercel | Edge compute for select features | Anonymous request data | +| GitHub | Source code hosting and CI/CD integration | Repository content | +| Stripe | Payment processing | Billing and payment data | +| Resend | Transactional email delivery | Name and email address | -## Communications +## Analytics and support -Transactional email and in-product messaging providers. +| Subprocessor | Purpose | Data processed | +|-------------|---------|----------------| +| PostHog | Internal product analytics | Anonymized usage data | +| Intercom | Customer support chat | Name, email, support conversations | -### Data minimization +## Changes to this list -Note which fields each vendor receives—full profile vs email-only. +Mintlify updates this list when adding or removing subprocessors. Customers with a signed DPA are notified at least 30 days before a new subprocessor is added, providing an opportunity to object. -## Updates - -We notify customers of substantive subprocessor changes as described in enterprise agreements. - -### Objection windows - -Define how customers object or terminate if they cannot accept a new subprocessor—timeline and migration assistance matter. +To subscribe to subprocessor change notifications, email [privacy@mintlify.com](mailto:privacy@mintlify.com). diff --git a/help-center/support/legal/regions/apac.mdx b/help-center/support/legal/regions/apac.mdx index 0b1ec5d..49b04ba 100644 --- a/help-center/support/legal/regions/apac.mdx +++ b/help-center/support/legal/regions/apac.mdx @@ -1,31 +1,31 @@ --- title: "APAC" sidebarTitle: "APAC" -description: "APAC considerations for this demo help center." +description: "Regional information for Mintlify customers in Asia-Pacific." --- -APAC spans many jurisdictions—Australia, Japan, Singapore, India, and others—with different data localization, breach notification, and consent rules. Treat this page as a prompt for counsel, not a legal survey. +Mintlify supports customers across the Asia-Pacific region. This page covers data location, local regulations, and support availability for APAC customers. -## Latency +## Data location -Pick APAC regions when most users are local to reduce round trips. +By default, APAC customer data is stored in Mintlify's US infrastructure. Enterprise customers in Australia, Singapore, and Japan can request data residency in AWS AP regions — contact [sales@mintlify.com](mailto:sales@mintlify.com) to discuss. -### Multi-region UX +## Regional regulations -Surface the user’s active region in support tooling so you do not misdiagnose “slow” issues as application bugs when they are physics. +Different APAC jurisdictions have specific data protection requirements: -## Regulations +**Australia** — The Australian Privacy Act and Australian Privacy Principles (APPs) apply. Mintlify's standard DPA covers the data handling requirements for most Australian customers. -Requirements vary widely—map your jurisdictions to product features with your counsel. +**Japan** — The Act on the Protection of Personal Information (APPI) requires specific data handling practices. Enterprise customers with APPI requirements should contact [legal@mintlify.com](mailto:legal@mintlify.com). -### Localization +**Singapore** — The Personal Data Protection Act (PDPA) applies. Mintlify's standard data handling practices are aligned with PDPA requirements. -Some locales require local language privacy notices or consent capture—plan content and UX accordingly. +**India** — The Digital Personal Data Protection Act (DPDPA) is in effect. Contact [legal@mintlify.com](mailto:legal@mintlify.com) for information on compliance for Indian customers. -## Support hours +## Performance -Coverage windows may differ; Enterprise plans offer expanded follow-the-sun options. +Mintlify uses Cloudflare's global CDN to serve docs sites. APAC readers experience fast page loads regardless of where your data is stored — CDN edge nodes in Sydney, Tokyo, Singapore, Mumbai, and other APAC cities serve cached content close to readers. -### Holidays +## Support hours -Regional holidays affect both your team and vendor staff—adjust SLAs for local observances. +Mintlify's support team is available during US business hours. Enterprise plans include expanded follow-the-sun coverage. For urgent issues outside US hours, check [status.mintlify.com](https://status.mintlify.com) for known incidents, then email [support@mintlify.com](mailto:support@mintlify.com). diff --git a/help-center/support/legal/regions/eu-residency.mdx b/help-center/support/legal/regions/eu-residency.mdx index 1534d84..62862a9 100644 --- a/help-center/support/legal/regions/eu-residency.mdx +++ b/help-center/support/legal/regions/eu-residency.mdx @@ -1,31 +1,33 @@ --- title: "EU data residency" sidebarTitle: "EU" -description: "EU data residency options in this demo help center." +description: "Data residency options and GDPR compliance for EU customers." --- -EU customers often ask where data lives and who can access it from abroad. Residency answers the first question; transfers and safeguards answer the second. +Mintlify supports EU data residency for Enterprise customers who need data to remain within the European Economic Area. -## Options +## Standard deployment -Select EU regions when provisioning if your contract includes regional deployment. +By default, Mintlify stores customer data on AWS infrastructure in the United States. Data may be processed by Mintlify staff globally. -### Multi-region +Mintlify uses Standard Contractual Clauses (SCCs) for cross-border data transfers from the EU to the US, as required by GDPR. -If you operate globally, document which data classes stay in-region vs replicate for disaster recovery. +## EU data residency (Enterprise) -## Transfers +Enterprise customers can request EU data residency, which stores customer account data and docs content on AWS EU infrastructure (Frankfurt region). -Cross-border transfers rely on approved mechanisms described in your DPA. +To request EU data residency: +- Contact [sales@mintlify.com](mailto:sales@mintlify.com) during onboarding. +- EU residency must be configured before your first deployment — it cannot be migrated retroactively. -### SCCs and IDTA +## GDPR compliance -Track which transfer tool you rely on for each flow and when standard contractual clauses update—legal teams run periodic refresh projects. +Mintlify supports GDPR compliance for customers through: +- A signed DPA (see [Data processing addendum](/support/legal/privacy/dpa)). +- Data subject rights support (access, deletion, portability). +- Breach notification within 72 hours of discovery. +- Subprocessor transparency (see [Subprocessors](/support/legal/privacy/subprocessors)). ## Support -EU customers may receive support from global teams with appropriate safeguards. - -### Access logging - -Some customers require EU-only support staff for certain tickets—confirm whether your plan supports that routing. +EU customers receive support from Mintlify's global support team. Enterprise customers can request EU-only support routing for sensitive tickets. diff --git a/help-center/support/legal/regions/index.mdx b/help-center/support/legal/regions/index.mdx index 37e0503..70f6365 100644 --- a/help-center/support/legal/regions/index.mdx +++ b/help-center/support/legal/regions/index.mdx @@ -1,9 +1,9 @@ --- -title: "Regional specifics" +title: "Regional data" sidebarTitle: "Overview" -description: "Data residency notes for EU, US, and APAC in this demo." +description: "Data residency options and regional compliance information for Mintlify." --- -Regional articles summarize how deployment choices affect storage and support. They are intentionally high level for the template. +Mintlify serves customers globally. This section covers data residency options and region-specific compliance considerations. -Validate residency requirements with your compliance team before go-live. \ No newline at end of file +For enterprise agreements with specific residency requirements, contact [sales@mintlify.com](mailto:sales@mintlify.com). diff --git a/help-center/support/legal/regions/us-residency.mdx b/help-center/support/legal/regions/us-residency.mdx index af4d4c6..4005533 100644 --- a/help-center/support/legal/regions/us-residency.mdx +++ b/help-center/support/legal/regions/us-residency.mdx @@ -1,31 +1,25 @@ --- title: "US data residency" sidebarTitle: "US" -description: "US data residency notes for this demo." +description: "Data storage and compliance information for US customers." --- -US customers may choose US regions for latency, contractual requirements, or comfort with domestic legal process. Pair residency choice with encryption and key management policies. +Mintlify's standard deployment stores data in the United States on AWS infrastructure. No additional configuration is needed for US customers who want their data to remain in the US. -## Regions +## Default data location -Choose US data centers for latency and regulatory alignment where required. +Customer data (account information, repository content, analytics) is stored on AWS US East (N. Virginia) by default. -### Multi-cloud +## Compliance frameworks -If you span multiple providers, document failover behavior—some failover paths cross regions unless explicitly constrained. +**SOC 2 Type II** — Mintlify's infrastructure and security controls are audited annually. Enterprise customers can request a copy of the SOC 2 report under NDA by contacting [security@mintlify.com](mailto:security@mintlify.com). -## Government requests - -We publish high-level transparency about requests as permitted by law. - -### Customer notice +**CCPA** — Mintlify supports California Consumer Privacy Act rights for California residents. Submit data rights requests to [privacy@mintlify.com](mailto:privacy@mintlify.com). -Your enterprise agreement may define when you receive notice of legal requests affecting your content—verify timelines and contact paths. +**HIPAA** — Mintlify does not currently offer a Business Associate Agreement (BAA) for HIPAA-covered entities. Do not store protected health information (PHI) in Mintlify. -## Education +**FedRAMP** — Mintlify is not FedRAMP authorized. For US federal government customers with FedRAMP requirements, contact [sales@mintlify.com](mailto:sales@mintlify.com) to discuss options. -FERPA and similar frameworks may impose additional obligations—consult specialists. - -### Student data +## Government requests -If you serve schools, map product features to FERPA roles and allowable disclosures before onboarding student populations. +Mintlify publishes an annual transparency report covering the number and type of government requests for customer data. We notify customers of requests affecting their data when legally permitted to do so. diff --git a/help-center/support/legal/terms-of-service.mdx b/help-center/support/legal/terms-of-service.mdx index 9e5a28a..978bc21 100644 --- a/help-center/support/legal/terms-of-service.mdx +++ b/help-center/support/legal/terms-of-service.mdx @@ -1,31 +1,40 @@ --- title: "Terms of service" sidebarTitle: "Terms of service" -description: "Demo terms of service for this help center template." +description: "Mintlify's terms of service governing use of the platform." --- -This page exists to show how legal content fits in navigation and layout. Replace every section with counsel-approved language before production use—placeholders are not enforceable contracts. +These terms govern your use of Mintlify's documentation platform. By creating an account or using Mintlify, you agree to these terms. ## Acceptance -By using this demo, you agree to illustrative terms meant for layout and navigation only. +By using Mintlify, you agree to be bound by these Terms of Service and our Privacy Policy. If you're using Mintlify on behalf of an organization, you represent that you have the authority to bind the organization to these terms. -### Age and authority +## Service -Real contracts specify eligible users, signing authority, and prohibited uses. Add those sections when you replace this text. +Mintlify provides a documentation hosting and editing platform. We reserve the right to modify, suspend, or discontinue any aspect of the service with reasonable notice. Material changes to pricing or features will be communicated at least 30 days in advance. -## Service changes +## Your content -Features described here may change without notice in a template environment. +You retain ownership of all content you publish through Mintlify. By using the service, you grant Mintlify a limited license to host and serve your content to your readers. -### Notice periods +You're responsible for ensuring your content doesn't violate applicable laws or third-party rights. -Production agreements typically define how material changes are communicated—email, in-product banner, or versioned PDF. +## Acceptable use -## Liability +You may not use Mintlify to: +- Publish content that violates applicable laws. +- Attempt to circumvent security measures or access other customers' data. +- Use the platform in ways that degrade performance for other users. -This text is not legal advice and is not a binding agreement—consult your legal team. +## Termination -### Caps and exclusions +Either party may terminate the agreement. You can close your account at any time. Mintlify may suspend or terminate accounts that violate these terms. -Negotiate liability caps, indirect damages, and carve-outs for gross negligence or IP infringement with your counterparty. +## Governing law + +These terms are governed by the laws of the State of Delaware, United States. + +--- + +*For the current, legally binding version of Mintlify's Terms of Service, visit [mintlify.com/legal/terms](https://mintlify.com/legal/terms).* diff --git a/help-center/support/status-incidents.mdx b/help-center/support/status-incidents.mdx index c7e8bd7..ab0887d 100644 --- a/help-center/support/status-incidents.mdx +++ b/help-center/support/status-incidents.mdx @@ -1,31 +1,41 @@ --- title: "Status and incidents" sidebarTitle: "Status & incidents" -description: "Where to find live status and how incidents are communicated." +description: "Check Mintlify service status and subscribe to incident notifications." --- -Transparency during incidents builds trust. Subscribe before you need it—during an outage you will not want to hunt for the status page URL. +Mintlify publishes real-time service status and incident updates at [status.mintlify.com](https://status.mintlify.com). ## Status page -Bookmark the status page for component health and historical incidents. +The status page shows the current health of each Mintlify component: -### Components +- **Dashboard** — The Mintlify web dashboard and web editor. +- **Deployments** — Build and deploy pipeline for all projects. +- **Hosting** — CDN and serving infrastructure for deployed docs sites. +- **API** — The Mintlify REST API. -Understand which component maps to your integration path (API vs auth vs attachments) so partial outages make sense. +When all components show "Operational," there are no known issues. -## Subscriptions +## Subscribe to updates -Subscribe to email or RSS updates for maintenance windows. +Click **Subscribe to updates** on the status page to receive notifications by email, RSS, Slack, or webhook when Mintlify creates, updates, or resolves an incident. -### On-call +Subscribe before you need it — you won't want to hunt for the status page during an outage. -Mirror status subscriptions into your incident channel so whoever is on-call sees updates without checking email. +### On-call teams -## Postmortems +If your team has an on-call rotation, route status page notifications to your incident channel in Slack or PagerDuty so on-call responders see Mintlify incidents alongside your own alerts. + +## During an incident -Major incidents include summaries with remediation steps for transparency. +When an incident is active: -### Your runbooks +1. Check the status page for the current status and timeline. +2. Look at the **Affected components** list to understand whether your use case is impacted. +3. Check for workarounds in the incident update — Mintlify posts workarounds when available. +4. Subscribe to the incident for updates rather than polling the status page manually. + +## Postmortems -After a vendor incident, update your internal runbook with workarounds you discovered—future you will thank past you. +After significant incidents, Mintlify publishes a postmortem on the status page explaining the root cause, timeline, and steps taken to prevent recurrence. Past incident history is available on the status page. diff --git a/help-center/support/troubleshooting/index.mdx b/help-center/support/troubleshooting/index.mdx index 178b424..7fd9b05 100644 --- a/help-center/support/troubleshooting/index.mdx +++ b/help-center/support/troubleshooting/index.mdx @@ -1,9 +1,9 @@ --- title: "Troubleshooting" sidebarTitle: "Overview" -description: "Fix common login and performance problems." +description: "Fix common Mintlify issues — login problems, build failures, and performance." --- -When something feels off, start with the basics: connectivity, browser health, and account state. +Most issues fall into a small set of categories. Start with the article that matches your symptom, or search for your specific error message. -These guides address the most frequent issues we see in customer conversations—your mileage may vary in real deployments. \ No newline at end of file +If you can't find a solution, [contact support](/support/contact-support) and include your error message and project URL. diff --git a/help-center/support/troubleshooting/login-issues.mdx b/help-center/support/troubleshooting/login-issues.mdx index 98ff64f..ebf396d 100644 --- a/help-center/support/troubleshooting/login-issues.mdx +++ b/help-center/support/troubleshooting/login-issues.mdx @@ -1,35 +1,40 @@ --- title: "Login issues" sidebarTitle: "Login issues" -description: "Resolve password resets, SSO failures, and session problems." +description: "Fix problems signing in to Mintlify — password resets, SSO errors, and session issues." --- -Login problems cluster around expired passwords, SSO misconfiguration, and browser state. Work through the sections below before opening a ticket—most resolutions take minutes. +If you can't sign in to Mintlify, work through these steps before contacting support. Most issues resolve within minutes. -## Password reset +## Can't sign in with email -Use the reset link once; repeated clicks invalidate older tokens. +1. Try the **Forgot password** link on the sign-in page. +2. Check your spam folder for the password reset email — Mintlify sends from `noreply@mintlify.com`. +3. If the reset email doesn't arrive within 5 minutes, check whether your email provider is blocking the sender domain, or contact your IT team. -### Inbox rules +## Can't sign in with GitHub -If resets never arrive, check quarantine and forwarding rules. Some enterprises strip links from unknown senders. +1. Make sure you're signing in with the same GitHub account that's connected to your Mintlify organization. +2. Try signing out of GitHub in your browser and signing back in, then retry the Mintlify login. +3. If your GitHub organization uses SSO, complete the GitHub SSO authorization first. -## SSO +## SSO errors -Confirm IdP certificates are valid and attribute mappings match service expectations. +| Error | Likely cause | Fix | +|-------|-------------|-----| +| "SAML configuration error" | Invalid IdP metadata or certificate | Re-upload the metadata from your IdP and verify the certificate hasn't expired. | +| "User not found" | Email claim doesn't match Mintlify | Confirm the email attribute in the SAML assertion matches the email on the Mintlify account. | +| "Clock skew detected" | Server time mismatch | Sync the clock on your IdP server with an NTP source. | -### SAML traces +## Session expired -Capture a SAML trace from your IdP when failures persist—support can compare assertion attributes to what the product expects. +If you're repeatedly logged out, check whether your browser is blocking cookies from `mintlify.com`. Mintlify uses first-party cookies for session management — blocking them causes immediate session expiry. -### Clock skew +In Chrome: **Settings → Privacy and security → Cookies → Allow `mintlify.com`**. -Large skew between IdP and SP can break assertions—sync NTP on servers. +## Can't access a specific project -## Sessions - -Clear site data for stale cookies and retry from a private window to isolate extensions. - -### Corporate proxies - -SSL inspection occasionally breaks OAuth flows—try off-network or a personal device to isolate the proxy as a variable. +If you can sign in but can't see a project: +- Confirm you've been invited to the project (or the organization containing it). +- Ask an Admin to verify your membership in **Settings → Members**. +- Check whether the project requires SSO — you may need to complete SSO enrollment first. diff --git a/help-center/support/troubleshooting/performance-issues.mdx b/help-center/support/troubleshooting/performance-issues.mdx index 063138b..d6dacde 100644 --- a/help-center/support/troubleshooting/performance-issues.mdx +++ b/help-center/support/troubleshooting/performance-issues.mdx @@ -1,31 +1,48 @@ --- title: "Performance issues" sidebarTitle: "Performance" -description: "Diagnose slowness, large pages, and network constraints." +description: "Diagnose slow builds, slow page loads, and other performance problems in Mintlify." --- -Performance issues feel like “the app is slow” but usually break down into network, rendering, or data volume. Gather one slow trace with timestamps before escalating—patterns matter more than one-off complaints. +Performance problems in Mintlify fall into two categories: slow build times and slow page loads. The fixes are different for each. -## Browser +## Slow builds -Disable heavy extensions and test with hardware acceleration toggled. +If your deployments are taking longer than expected, common causes include: -### Profiles +**Large images** — Unoptimized images dramatically slow builds. Compress images before adding them to your repository, or host them externally (Cloudinary, S3) and reference them by URL. -Try a fresh browser profile with only default extensions. Ad blockers and password managers sometimes inject scripts that delay paint. +**Many pages** — Sites with thousands of pages take longer to build. This is usually not a problem until you reach 2,000+ pages. -## Content +**External data fetching** — If your docs fetch data from external APIs at build time, slow API responses extend build times. Cache responses or use static data where possible. -Huge embedded media slows load—lazy load or host externally when possible. +### Check your build time trend -### Tables and charts +Go to **[Project] → Deployments** and look at the build duration column. If build times have increased gradually, it's likely due to content growth. A sudden jump suggests a recently added page or image is the culprit. -Large datasets should paginate or virtualize. If the editor feels fine but read mode lags, the DOM size is a likely culprit. +## Slow page loads -## Network +If your docs pages load slowly for readers, common causes include: -Corporate proxies sometimes buffer WebSockets—ask IT for allowlist guidance. +**Large images on the page** — Audit your pages for large embedded images. Use smaller images or reference external images so they load from a CDN rather than your repository. -### VPN +**Custom JavaScript** — Scripts added via Google Tag Manager or custom `