From 7f15c060ae0c8c473e5bcbbf0b592063e89709c4 Mon Sep 17 00:00:00 2001 From: DeweyMarco Date: Mon, 24 Aug 2026 12:24:28 -0700 Subject: [PATCH 1/2] Add hidden POC onboarding page Adds poc-onboarding.mdx, a self-serve setup guide for enterprise customers running a Mintlify proof of concept. Covers account and repository setup, inviting the team, migrating sample content, publishing a first change, branding, the AI assistant, SSO and security, and a results review. Written for non-technical readers, with each step naming who from their team is needed and for how long. The page is not listed in docs.json and carries noindex: true, so it is reachable by direct URL only. This matches enterprise-contracting and migration-services/go-live-checklist. Co-Authored-By: Claude Opus 5 (1M context) --- poc-onboarding.mdx | 328 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 poc-onboarding.mdx diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx new file mode 100644 index 000000000..274492c2a --- /dev/null +++ b/poc-onboarding.mdx @@ -0,0 +1,328 @@ +--- +title: "Proof of concept onboarding" +description: "Set up a Mintlify proof of concept step by step: create your account, connect your repository, migrate sample content, enable the AI assistant, and evaluate the results." +keywords: ["POC", "proof of concept", "trial", "evaluation", "enterprise onboarding", "pilot"] +noindex: true +--- + +This guide takes you from nothing to a working Mintlify documentation site that your team can evaluate. Follow the steps in order. Each one tells you what to do, who you need from your team, and how long it takes. + +You do not need to be a developer to finish this guide. Two steps need someone with GitHub or IT access for a short time. You can do everything else yourself in a browser. + + + You have a dedicated Mintlify contact for the duration of your proof of concept (POC). If a step doesn't match what you see on screen, or you get stuck for more than a few minutes, message your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com) instead of working around it. + + +## What you'll have at the end + + + + A real site at your own URL, running a representative sample of your content. + + + + Your team editing and publishing pages, with review before anything goes live. + + + + An assistant answering questions from your documentation, with analytics on what people asked. + + + + Single sign-on, access controls, and audit logging configured or confirmed. + + + +## Before you begin + +### People you'll need + +Line these people up before you start. Nothing here needs full-time involvement, but a missing GitHub administrator can stall the POC for days. + +| Who | What they do | When | Time needed | +|---|---|---|---| +| Documentation owner | Runs the POC and completes most steps. This is probably you. | Throughout | A few hours total | +| GitHub administrator | Approves the Mintlify GitHub App on your repository. | Step 1 | 15 minutes, once | +| Designer or brand owner | Supplies logo files, color codes, and fonts. | Step 5 | 30 minutes, once | +| Identity or IT administrator | Configures single sign-on and DNS records. | Step 7 | 1 to 2 hours, optional | +| Decision maker | Reviews the finished POC against your success criteria. | Step 8 | 1 hour | + +### What to gather + +Collect these before step 3 so you aren't waiting on other teams mid-setup: + +- Logo files for light and dark backgrounds, in SVG or PNG. +- A favicon, in SVG or PNG. +- Your brand color codes, as hex values. +- Font files, or the names of the Google Fonts you use. +- A link to your current documentation site, or an export of its content. +- Your OpenAPI specification file or URL, if you document an API. +- A list of the pages you want in the POC. See [Choose your sample content](#choose-your-sample-content) for how to pick them. + +### Decide what success looks like + +Write down three to five criteria before you start, and share them with your Mintlify contact. Without them, the review in step 8 turns into an opinion contest. + +Criteria that work well: + +- A writer with no Git experience publishes a page change without help. +- Our most complex API reference page renders correctly. +- The assistant answers 8 of our 10 most common support questions correctly. +- Our identity provider handles dashboard login. +- A documentation update goes from draft to live in under an hour. + +## Step 1: Create your account and connect your repository + +Mintlify stores every page as a file in a Git repository, and publishes your site whenever that repository changes. You connect the repository once, at the start, and then mostly forget it exists. + + + Your GitHub administrator needs organization ownership or administrator permissions on the repository to approve the Mintlify GitHub App. Ask them to be available before you begin this step. Without the app installed, your site will not deploy. + + + + + Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the email address you'd use for your real documentation, not a personal one, so that it maps to your identity provider later. + + + + During onboarding, connect your GitHub account, then create a new repository or select an existing empty one. A repository named `docs` inside your company's GitHub organization is a good default. A private repository is fine. + + Do not select a repository that already contains an application or other files. + + + + Your GitHub administrator installs the Mintlify GitHub App and grants it access to that one repository. Select **Only select repositories** rather than granting access to everything. + + See [Install the GitHub App](/deploy/github#install-the-github-app) for the exact permissions the app requests. Send that link to your administrator ahead of time if they want to review the permissions first. + + + Install the app anyway. GitHub sends an approval request to your organization owners, and the installation completes when they approve it. + + If that approval will take days, you can skip connecting a Git provider during onboarding. Mintlify creates a private repository for you so you can start immediately, and you can move the content to your own repository later from the [Git settings](https://app.mintlify.com/settings/deployment/git-settings) page. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository). + + + + + Mintlify deploys starter content to your repository and publishes it. Your site is live at `https://.mintlify.site`. + + Find the exact URL on the **Overview** page of your [dashboard](https://app.mintlify.com/). Open it to confirm the site loads. + + + + + Use the `.mintlify.site` URL for the whole POC. It is a real, working site that you can share internally. Adding your own domain is step 7, and it is not required to evaluate anything. + + +## Step 2: Invite your team + +Add everyone who needs to see or touch the POC from the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. + +Mintlify has three roles. Assign the narrowest one that lets each person do their job: + +- **Admin**: Changes organization settings, billing, and integrations. Give this to yourself and one backup. +- **Editor**: Creates and publishes content. Give this to your writers. +- **Viewer**: Reads the dashboard and analytics without editing. Give this to reviewers and stakeholders. + +See [Roles](/dashboard/roles) for what each role can do in detail. + +Invite people using their work email addresses. If you plan to test single sign-on in step 7, mismatched addresses mean their accounts will not link to your identity provider. + +For a useful POC, invite at least one writer who has never used Git, one engineer, and the person who will make the buying decision. The first two tell you whether the tool fits your team. The third needs to have seen it work. + +## Step 3: Get your content in + +### Choose your sample content + +Pick 20 to 50 pages. More than that slows the POC down without teaching you anything new. + +Choose the pages that are hardest to move, not the easiest: + +- Your most complex API reference page. +- A page with a large table or a deeply nested list. +- A page with images, video, or diagrams. +- A page using custom components or embedded widgets, if you have any. +- Two or three ordinary guides, so you can judge everyday quality. + +A POC built on your simplest pages tells you nothing about the migration you'd actually run. + +### Move the content + + + + Ask your Mintlify contact whether a migration is included in your POC, and what the turnaround time is. + + If it is, send them: + + - A link to your current documentation site, or an export of its content. + - The list of pages you chose. + - Your OpenAPI specification file or URL, if you have an API reference. + - Your brand assets from [What to gather](#what-to-gather). + + Mintlify ports the content, checks it, and shares a preview link so you can watch progress. See [Enterprise migrations](/migration-services/enterprise) for how the full migration process works after the POC. + + + + Mintlify has tooling for common platforms, and manual instructions for everything else: + + - [Docusaurus](/migration/docusaurus) + - [ReadMe](/migration/readme) + - [GitBook](/migration/gitbook) + - [Fern](/migration/fern) + - [Document360](/migration/document360) + - [Any other platform](/migration/manual) + + Start at [Migrate to Mintlify](/migration) to pick your path. This route needs someone comfortable running commands in a terminal. + + + +### Check the result + +Open your site and compare each sample page against the same page on your current documentation. Look for missing images, broken tables, code samples that lost their formatting, and links that go nowhere. + +Send anything wrong to your Mintlify contact in one batch rather than one message at a time. Include the page URL and what you expected to see. + +## Step 4: Publish a change yourself + +This is the step that decides most POCs. If your writers can update documentation without filing a ticket with engineering, the tool works for you. Have someone non-technical do this step, not the most technical person on your team. + + + + Go to the [web editor](https://app.mintlify.com/editor). It looks like a normal document editor and does not require any knowledge of Git. + + + + Open any page and change a sentence. See the [editor tutorial](/editor/tutorial) for a walkthrough of the interface. + + + + Select **Publish** in the top-right of the toolbar. Your change deploys automatically. + + To send changes through review instead of publishing directly, work on a branch and open a pull request. See [Branching and publishing](/editor/branching-and-publishing). + + + + Watch the deployment status on the **Overview** page of your dashboard, then refresh your site. + + + +Two things worth testing in the same step, because they change how your team works day to day: + +- **Review before publishing.** Every pull request gets its own preview URL that reviewers can open without installing anything. See [Preview deployments](/deploy/preview-deployments). +- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). + +If your team writes locally in a code editor instead, they can install the [CLI](/cli/install) and preview the site on their own machine with [`mint dev`](/cli/preview). + +## Step 5: Apply your branding + +Stakeholders judge the POC partly on whether it looks like your product. This takes about 30 minutes and is worth doing before the review in step 8. + +Your site's appearance comes from a single configuration file, `docs.json`, in your repository. Set: + +- **Colors**: Your primary, light, and dark brand colors, as hex values. +- **Logo**: Separate files for light and dark mode. +- **Favicon**: The icon in the browser tab. +- **Fonts**: Google Fonts by name, or your own font files. +- **Theme**: The overall layout and style of the site. + +See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. + +If editing a configuration file isn't something you want to do, send your brand assets to your Mintlify contact and ask them to apply it. + +## Step 6: Turn on the AI features + +### Enable the assistant + +Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard: + +1. Toggle the assistant on. +2. Set your support and sales [deflection emails](/assistant/configure#set-deflection-emails), so that questions the assistant can't answer route to a real person. +3. Add [sample questions](/assistant/configure#add-sample-questions) that show people what to ask. +4. Add [search domains](/assistant/configure#search-domains) if you want the assistant to draw on content outside your documentation site. + +To change the assistant's tone or teach it product-specific behavior, see [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills). + +### Put the assistant where your users are + +The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it is the fastest way to show your support team what deflection looks like in practice. + +### Confirm your content is ready for AI agents + +Mintlify generates these automatically. Check them, but you don't need to configure anything: + +- [`llms.txt`](/ai/llmstxt), a machine-readable index of your site. +- [`skill.md`](/ai/skillmd), a description of what agents can do with your product. This can take up to 24 hours to generate. +- An [MCP server](/ai/model-context-protocol) that lets tools like Claude and Cursor search your documentation. +- [Markdown export](/ai/markdown-export), so any page can be copied as clean text into an AI tool. + +### Test the assistant properly + +Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: + +1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. +2. Ask the assistant each one. +3. Record whether the answer was correct, partly correct, or wrong. +4. For the wrong answers, check whether your documentation actually contains the answer. Usually it doesn't, and that is a content gap you now know about. + +Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page. + +## Step 7: Loop in IT and security + +Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Not all of these are needed to evaluate Mintlify, so start with whichever ones appear in your success criteria. + +**Who can access your dashboard** + +- [Single sign-on](/dashboard/sso) with SAML or OIDC, including Okta, Microsoft Entra, and Google Workspace. +- [SCIM provisioning](/dashboard/scim) to create and remove accounts automatically from your identity provider. +- [Network access policies](/dashboard/network-access) to restrict dashboard access to your IP ranges. +- [Audit logs](/dashboard/audit-logs) and [session security](/dashboard/session-security). + +**Who can access your documentation site** + +If your documentation must not be public, set up [authentication](/deploy/authentication-setup). Mintlify supports password protection, OAuth, JWT, and Mintlify-managed private access. You can also [restrict individual pages to specific groups](/deploy/authentication-setup#control-access-with-groups) while leaving the rest of the site public. + +**Your domain** + +Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. Mintlify provisions the TLS certificate automatically. + +**Analytics, checks, and compliance** + +- Connect your existing [analytics platform](/integrations/analytics/overview) so documentation traffic lands in the tools you already use. +- Enable [CI checks](/deploy/ci) to catch broken links and accessibility problems before they publish. +- For security questionnaires, certifications, and contract review, see [Enterprise contracting](/enterprise-contracting). + +## Step 8: Review the results + +Book an hour with your decision maker and walk through your criteria from [Decide what success looks like](#decide-what-success-looks-like). Use the evidence you collected rather than impressions. + +| What you're checking | Where to check it | +|---|---| +| A non-developer can publish independently | Whether step 4 worked without help, and how long it took | +| Your hardest content survived the move | Your sample pages, compared side by side with your current site | +| The assistant answers accurately | Your scored question list, plus [Assistant analytics](/analytics/assistant) | +| Readers find what they need | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) analytics | +| Readers say it's better | [Page feedback](/optimize/feedback) | +| It meets security requirements | Your IT team's sign-off from step 7 | + +Bring open questions to your Mintlify contact before the review, not during it. + +## A workable timeline + +Most POCs run two to three weeks. Compressing this into a few days is possible, but only if your GitHub administrator and brand assets are ready on day one. + +| Week | What happens | +|---|---| +| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree on success criteria. | +| Week 2 | Steps 3 to 6: review the migrated content, publish changes yourself, apply branding, and turn on the assistant. Start collecting your assistant test questions. | +| Week 3 | Steps 7 and 8: IT and security review, then the results review with your decision maker. | + +## Getting help + +- **Your shared Slack channel**, for anything time-sensitive during the POC. +- **[support@mintlify.com](mailto:support@mintlify.com)**, for everything else. +- **[Advanced support](/advanced-support)**, if you want to know what support looks like after the POC. + +## After the POC + + + Everything to configure and verify before your documentation goes live for real. + From f524fc7ea9e7b96deb6d595f07a771fff499a92d Mon Sep 17 00:00:00 2001 From: DeweyMarco Date: Mon, 24 Aug 2026 13:24:09 -0700 Subject: [PATCH 2/2] Rework POC steps against the SE working session guides Pulls the mechanics, prerequisites, and objection-handling from the internal SE working sessions into the customer-facing steps. Corrections: - Authentication requires a custom domain or *.mintlify.app subdomain and does not work on .mintlify.site or a custom basepath. The page previously treated the custom domain as skippable during a POC and auth as independent of it. Now flagged in step 1 and step 7. - Separates dashboard SSO (who logs in) from site authentication (who reads), with the real method taxonomy and the two-account test. Additions: - The repo/dashboard/live-site model up front. - Step 4 rewritten with the actual editor flow, plus the point that publishing writes a Git commit so CODEOWNERS and branch protection still apply. - Step 5 gets the docs.json theme keys, the light/dark check, and OG. - Step 6 gets the three-way answer check (answered, correct, which page cited), the description-quality lever, both MCP servers, the contextual menu, and automations. - Sample content chosen from top pages by traffic; two navigation tests; Notion and Confluence sync as a third migration route. - Success criteria reframed as one lever and one metric with a recorded baseline. Co-Authored-By: Claude Opus 5 (1M context) --- poc-onboarding.mdx | 285 +++++++++++++++++++++++++++++++++------------ 1 file changed, 210 insertions(+), 75 deletions(-) diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx index 274492c2a..45326d258 100644 --- a/poc-onboarding.mdx +++ b/poc-onboarding.mdx @@ -1,6 +1,6 @@ --- title: "Proof of concept onboarding" -description: "Set up a Mintlify proof of concept step by step: create your account, connect your repository, migrate sample content, enable the AI assistant, and evaluate the results." +description: "Set up a Mintlify proof of concept step by step: connect your repository, migrate sample content, publish a change, turn on the assistant, and measure the result." keywords: ["POC", "proof of concept", "trial", "evaluation", "enterprise onboarding", "pilot"] noindex: true --- @@ -13,6 +13,16 @@ You do not need to be a developer to finish this guide. Two steps need someone w You have a dedicated Mintlify contact for the duration of your proof of concept (POC). If a step doesn't match what you see on screen, or you get stuck for more than a few minutes, message your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com) instead of working around it. +## How Mintlify fits together + +Three things, and knowing which is which makes every step below easier to follow: + +1. **Your repository** is the source of truth. Your documentation is `.mdx` files and one `docs.json` configuration file in Git. Nothing is stored in a proprietary format. +2. **The dashboard** at [app.mintlify.com](https://app.mintlify.com) is the control plane, where you write, configure, and publish. +3. **Your live site** is what readers see. + +The web editor sits between them. When you publish, it writes to your repository for you, so nobody has to run a Git command who doesn't want to. + ## What you'll have at the end @@ -25,7 +35,7 @@ You do not need to be a developer to finish this guide. Two steps need someone w - An assistant answering questions from your documentation, with analytics on what people asked. + An assistant answering questions from your documentation, with analytics showing what people asked and where your content gaps are. @@ -44,44 +54,61 @@ Line these people up before you start. Nothing here needs full-time involvement, | Documentation owner | Runs the POC and completes most steps. This is probably you. | Throughout | A few hours total | | GitHub administrator | Approves the Mintlify GitHub App on your repository. | Step 1 | 15 minutes, once | | Designer or brand owner | Supplies logo files, color codes, and fonts. | Step 5 | 30 minutes, once | -| Identity or IT administrator | Configures single sign-on and DNS records. | Step 7 | 1 to 2 hours, optional | +| Identity or IT administrator | Configures single sign-on, authentication, and DNS records. | Step 7 | 1 to 2 hours, optional | | Decision maker | Reviews the finished POC against your success criteria. | Step 8 | 1 hour | ### What to gather Collect these before step 3 so you aren't waiting on other teams mid-setup: -- Logo files for light and dark backgrounds, in SVG or PNG. -- A favicon, in SVG or PNG. +- Logo files for light and dark backgrounds, in SVG or PNG. You need both variants, or your logo disappears when a reader switches themes. +- A favicon. SVG works well. - Your brand color codes, as hex values. -- Font files, or the names of the Google Fonts you use. +- Font files, or the names of the Google Fonts your marketing site uses. - A link to your current documentation site, or an export of its content. - Your OpenAPI specification file or URL, if you document an API. -- A list of the pages you want in the POC. See [Choose your sample content](#choose-your-sample-content) for how to pick them. +- Your top 20 to 30 pages by traffic, from your current analytics. See [Choose your sample content](#choose-your-sample-content). -### Decide what success looks like +### Pick one thing to prove -Write down three to five criteria before you start, and share them with your Mintlify contact. Without them, the review in step 8 turns into an opinion contest. +Most POCs fail their own review because nobody agreed in advance what a good result looks like. Avoid that by picking a single lever and a single metric under it. -Criteria that work well: + + + Docs shorten time-to-first-success. Metric: activation rate, or time-to-first-integration. + + + + Docs answer the questions your support team gets asked repeatedly. Metric: ticket volume in your top category. + + + + Findable docs unblock the next thing a customer wants to do. Metric: feature adoption after launch. + + + +Write down what "good" would look like for that one metric in 90 days, and share it with your Mintlify contact at kickoff. + + + Record your baseline before you start. If your metric is support tickets, pull the current monthly volume for your top category now. A POC with nothing to compare against produces opinions instead of a decision. + + +Then add two or three practical criteria that the POC itself can settle: - A writer with no Git experience publishes a page change without help. - Our most complex API reference page renders correctly. -- The assistant answers 8 of our 10 most common support questions correctly. +- The assistant answers 8 of our 10 most common support questions correctly, citing the right page. - Our identity provider handles dashboard login. -- A documentation update goes from draft to live in under an hour. ## Step 1: Create your account and connect your repository -Mintlify stores every page as a file in a Git repository, and publishes your site whenever that repository changes. You connect the repository once, at the start, and then mostly forget it exists. - Your GitHub administrator needs organization ownership or administrator permissions on the repository to approve the Mintlify GitHub App. Ask them to be available before you begin this step. Without the app installed, your site will not deploy. - Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the email address you'd use for your real documentation, not a personal one, so that it maps to your identity provider later. + Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the address you'd use for your real documentation, not a personal one, so it maps to your identity provider later. @@ -110,7 +137,9 @@ Mintlify stores every page as a file in a Git repository, and publishes your sit - Use the `.mintlify.site` URL for the whole POC. It is a real, working site that you can share internally. Adding your own domain is step 7, and it is not required to evaluate anything. + Use the `.mintlify.site` URL for most of the POC. It is a real, working site you can share internally. + + One exception: if testing authentication is part of your criteria, you need a custom domain or a `*.mintlify.app` subdomain first, because authentication does not work on the default URL or on a custom basepath. Set that up early rather than in the final week. See [step 7](#step-7-loop-in-it-and-security). ## Step 2: Invite your team @@ -133,9 +162,9 @@ For a useful POC, invite at least one writer who has never used Git, one enginee ### Choose your sample content -Pick 20 to 50 pages. More than that slows the POC down without teaching you anything new. +Pull your top 20 to 30 pages by traffic from your current analytics, then pick your sample from that list. Starting from real traffic rather than intuition means you evaluate Mintlify on the pages your readers actually use. -Choose the pages that are hardest to move, not the easiest: +From that list, deliberately include the pages that are hardest to move: - Your most complex API reference page. - A page with a large table or a deeply nested list. @@ -143,7 +172,7 @@ Choose the pages that are hardest to move, not the easiest: - A page using custom components or embedded widgets, if you have any. - Two or three ordinary guides, so you can judge everyday quality. -A POC built on your simplest pages tells you nothing about the migration you'd actually run. +A POC built on your simplest pages tells you nothing about the migration you'd actually run. More than 50 pages slows the POC down without teaching you anything new. ### Move the content @@ -162,16 +191,19 @@ A POC built on your simplest pages tells you nothing about the migration you'd a - Mintlify has tooling for common platforms, and manual instructions for everything else: + Three routes, roughly in order of how clean the result is: - - [Docusaurus](/migration/docusaurus) - - [ReadMe](/migration/readme) - - [GitBook](/migration/gitbook) - - [Fern](/migration/fern) - - [Document360](/migration/document360) - - [Any other platform](/migration/manual) + 1. **Export as Markdown** from your current platform, when it supports that. Mintlify has tooling for [Docusaurus](/migration/docusaurus), [ReadMe](/migration/readme), [GitBook](/migration/gitbook), [Fern](/migration/fern), and [Document360](/migration/document360), plus [manual instructions](/migration/manual) for anything else. + 2. **Paste and clean up in the web editor.** Fastest for a handful of ad-hoc pages. + 3. **Let an AI tool convert it**, using the Mintlify [skill](/ai/skillmd) and [admin MCP server](/ai/mintlify-mcp) in Claude Code or Cursor. - Start at [Migrate to Mintlify](/migration) to pick your path. This route needs someone comfortable running commands in a terminal. + Start at [Migrate to Mintlify](/migration) to pick your path. + + + + If your content lives in Notion, Confluence, Jira, or a similar tool, connect it rather than copying out of it. Connected apps give the Mintlify agent live context and can trigger automations that keep pages aligned with their source. + + See [Integrations for the agent and automations](/automations/integrations) for the full list and setup. @@ -179,6 +211,13 @@ A POC built on your simplest pages tells you nothing about the migration you'd a Open your site and compare each sample page against the same page on your current documentation. Look for missing images, broken tables, code samples that lost their formatting, and links that go nowhere. +While you're there, run two quick tests on your navigation: + +- Can a brand-new user reach their first useful page in two clicks? +- Do your navigation labels match the words someone would type into a search box? "How to configure auth" gets found. "Authentication configuration" often doesn't. + +A no on either one is worth raising now, because your navigation structure lives in `docs.json` and is cheap to change during a POC. + Send anything wrong to your Mintlify contact in one batch rather than one message at a time. Include the page URL and what you expected to see. ## Step 4: Publish a change yourself @@ -186,45 +225,86 @@ Send anything wrong to your Mintlify contact in one batch rather than one messag This is the step that decides most POCs. If your writers can update documentation without filing a ticket with engineering, the tool works for you. Have someone non-technical do this step, not the most technical person on your team. - - Go to the [web editor](https://app.mintlify.com/editor). It looks like a normal document editor and does not require any knowledge of Git. + + Go to the [web editor](https://app.mintlify.com/editor). It has three regions: the **Files** panel on the left with your folders and pages, the editing canvas in the middle, and the toolbar across the top. + + Check the branch selector at the top left before you type anything. When it reads **Live site**, you are editing the deployed site directly and anything you publish goes straight to your readers. - - Open any page and change a sentence. See the [editor tutorial](/editor/tutorial) for a walkthrough of the interface. + + Open the **Live site** dropdown, switch to the **Branches** tab, and select **New branch**. You're now editing a copy, so nothing you do affects readers until you publish. + + Do this for your first edit even if you plan to publish directly later. It's how you'll work day to day, and it means a practice edit can't embarrass you. - - Select **Publish** in the top-right of the toolbar. Your change deploys automatically. + + Click anywhere and start typing, the same way you would in a document. Type `/` to insert a component such as a callout, steps block, or card. Drag an image file onto the canvas and the editor uploads it and writes the reference for you. + + Now use the two toggles at the top right of the canvas: the eye icon shows the rendered page, and the `` icon shows the Markdown source. Your edit is sitting there in the raw `.mdx`, frontmatter and all. + + This matters more than it looks. There's no hidden layer and nothing proprietary, so a writer in the visual view and an engineer in the repository are editing the same file. + - To send changes through review instead of publishing directly, work on a branch and open a pull request. See [Branching and publishing](/editor/branching-and-publishing). + + Copy the branch's preview link and send it to a teammate. They see your change rendered at a live URL, in context, with nothing to install. This is how review works: draft, send the preview, publish once it's approved. - - Watch the deployment status on the **Overview** page of your dashboard, then refresh your site. + + Select **Publish** in the top right. On a branch, publishing opens or updates a pull request. On the live site, it deploys right away. + + Either way, publishing writes a real Git commit. Watch it appear on the **Overview** page of your dashboard, then refresh your site. -Two things worth testing in the same step, because they change how your team works day to day: + + + No. Publishing creates a Git commit, so CODEOWNERS, required reviews, and branch protection all still apply exactly as they do today. Your engineers review documentation changes the same way they review code. Writers just don't need Git to propose one. + -- **Review before publishing.** Every pull request gets its own preview URL that reviewers can open without installing anything. See [Preview deployments](/deploy/preview-deployments). -- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). + + They can toggle to the Markdown view with the `` icon and stay there. Same content, same file. People on the same team can work in different views without stepping on each other. + + + + They install the [CLI](/cli/install), clone the repository, and run [`mint dev`](/cli/preview) for a local server with hot reload. They can also run `mint broken-links` before pushing, and you can [wire the same checks into CI](/deploy/ci) so a broken link fails the build like a failing test. + + -If your team writes locally in a code editor instead, they can install the [CLI](/cli/install) and preview the site on their own machine with [`mint dev`](/cli/preview). +Two things worth testing in the same sitting, because they change how your team works day to day: + +- **Per-branch previews.** Every pull request gets its own live URL. Reviewers open a link instead of pasting screenshots into chat. See [Preview deployments](/deploy/preview-deployments). +- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace). ## Step 5: Apply your branding -Stakeholders judge the POC partly on whether it looks like your product. This takes about 30 minutes and is worth doing before the review in step 8. +Stakeholders judge a POC partly on whether it looks like your product, and a font mismatch is the first thing anyone notices. This takes about 30 minutes and is worth doing before the review in step 8. + +Almost all of your branding lives in a handful of keys in `docs.json`, so a full brand change is a configuration edit rather than a stylesheet: + +```json docs.json +{ + "theme": "luma", + "colors": { + "primary": "#16A34A", + "light": "#07C983", + "dark": "#15803D" + }, + "logo": { + "light": "/logo/light-logo.svg", + "dark": "/logo/dark-logo.svg" + }, + "favicon": "/favicon.svg" +} +``` + +Set `primary` to your main brand color. `light` and `dark` are the accent shades used in dark and light mode, so tune them until links and buttons stay legible against both backgrounds. Add a `fonts` key to load your marketing font. See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. -Your site's appearance comes from a single configuration file, `docs.json`, in your repository. Set: +Then check both modes, because readers pick their own with the switcher in the top bar: -- **Colors**: Your primary, light, and dark brand colors, as hex values. -- **Logo**: Separate files for light and dark mode. -- **Favicon**: The icon in the browser tab. -- **Fonts**: Google Fonts by name, or your own font files. -- **Theme**: The overall layout and style of the site. +- Your logo needs a light and a dark variant, which is why `logo.light` and `logo.dark` are separate keys. +- Diagrams drawn as SVGs that use `currentColor` recolor themselves. Raster screenshots don't, so keep paired light and dark versions. -See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces. +Finally, set a default Open Graph image so links to your docs render a branded card in Slack. Test it in a real Slack message before you share the site widely. See [SEO](/optimize/seo) for the meta tag reference. If editing a configuration file isn't something you want to do, send your brand assets to your Mintlify contact and ask them to apply it. @@ -234,55 +314,107 @@ If editing a configuration file isn't something you want to do, send your brand Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard: -1. Toggle the assistant on. -2. Set your support and sales [deflection emails](/assistant/configure#set-deflection-emails), so that questions the assistant can't answer route to a real person. -3. Add [sample questions](/assistant/configure#add-sample-questions) that show people what to ask. -4. Add [search domains](/assistant/configure#search-domains) if you want the assistant to draw on content outside your documentation site. +1. Turn on the assistant status toggle. +2. Set your support and sales [deflection addresses](/assistant/configure#set-deflection-emails). Do this before you go live. The handoff is what turns a question the assistant can't answer into a clean escalation instead of a dead end. +3. Add up to three [starter questions](/assistant/configure#add-sample-questions) to steer people toward what the assistant answers well. +4. Add [search domains](/assistant/configure#search-domains) if your product spans more than one site. +5. Leave [bot protection](/assistant/configure#bot-protection) on. It's invisible to nearly all real visitors. To change the assistant's tone or teach it product-specific behavior, see [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills). +### Test it against real questions + +Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: + +1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. +2. Ask each one on your live site using **Ask Assistant** in the top bar. +3. Check every answer three ways: did it answer, was the answer right, and **which page did it cite?** +4. Sort the failures. A wrong answer points at a specific page you should fix. A missing answer points at a page you should write. + +That third check is the one people skip, and it's the one that turns a vague impression into a specific fix. Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page, where unanswered and downvoted questions become your content backlog. + + + The frontmatter `description` is the single biggest lever on whether a page gets retrieved at all, because the assistant reads it first to decide whether a page is relevant. Aim for 130 to 160 characters of plain language, unique on every page. If a page you know is correct never gets cited, its description is usually why. + + ### Put the assistant where your users are -The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it is the fastest way to show your support team what deflection looks like in practice. +The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it's the fastest way to show your support team what deflection looks like in practice. -### Confirm your content is ready for AI agents +### Connect your docs to AI tools -Mintlify generates these automatically. Check them, but you don't need to configure anything: +Mintlify runs two MCP servers, and they serve opposite audiences: -- [`llms.txt`](/ai/llmstxt), a machine-readable index of your site. -- [`skill.md`](/ai/skillmd), a description of what agents can do with your product. This can take up to 24 hours to generate. -- An [MCP server](/ai/model-context-protocol) that lets tools like Claude and Cursor search your documentation. -- [Markdown export](/ai/markdown-export), so any page can be copied as clean text into an AI tool. +- The **[search MCP server](/ai/model-context-protocol)** serves your published content to readers inside Claude, Cursor, and ChatGPT. On an authenticated site it respects auth and groups, so each person only retrieves pages their group can see. +- The **[admin MCP server](/ai/mintlify-mcp)** lets your own docs team draft pages, run checks, and edit content from their AI editor. -### Test the assistant properly +For readers who don't use an AI editor, the [contextual menu](/ai/contextual-menu) gives every page a one-click path into ChatGPT, Claude, or Perplexity: -Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead: +```json docs.json +{ + "contextual": { + "options": ["copy", "view", "chatgpt", "claude", "perplexity"] + } +} +``` -1. Pull 20 to 30 real questions from your support tickets or community channels over the last month. -2. Ask the assistant each one. -3. Record whether the answer was correct, partly correct, or wrong. -4. For the wrong answers, check whether your documentation actually contains the answer. Usually it doesn't, and that is a content gap you now know about. +Mintlify also generates [`llms.txt`](/ai/llmstxt) (a map of your pages), [`skill.md`](/ai/skillmd) (what agents can do with your product, which can take up to 24 hours to appear), and a [Markdown version of every page](/ai/markdown-export). Add `.md` to any page URL to see exactly what an AI consumer receives. + +### Automate a maintenance task -Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page. +Documentation drifts the moment your product moves. [Automations](/automations) run the agent on a schedule, on a push to a repository, or when something happens in a connected tool, and propose the update as a pull request. + +Enable one that maps to something you do by hand today. Drafting a changelog and updating docs from code changes are the clearest starting points. Two settings matter: + +- **How updates are applied.** Start with **Require review** so the automation opens a change and waits for a human. Move low-risk jobs to automatic once you trust them. +- **When it runs.** On content updates, on a schedule, or from pushes in a connected repository. + +Then read the run history and open a run to see the exact change it proposed. That log is how you tell your team the automation is doing the right thing. See [Manage automations](/automations/manage). ## Step 7: Loop in IT and security -Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Not all of these are needed to evaluate Mintlify, so start with whichever ones appear in your success criteria. +Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Start with whichever of these appear in your success criteria. + + + Authentication requires a custom domain or a `*.mintlify.app` subdomain. It does **not** work on the default `.mintlify.site` URL or on a custom basepath such as `yourcompany.com/docs`. If gating your documentation is part of the POC, sort the domain out first rather than discovering this in the final week. + -**Who can access your dashboard** +**Who can log into your dashboard** + +This is your team, not your readers. - [Single sign-on](/dashboard/sso) with SAML or OIDC, including Okta, Microsoft Entra, and Google Workspace. - [SCIM provisioning](/dashboard/scim) to create and remove accounts automatically from your identity provider. - [Network access policies](/dashboard/network-access) to restrict dashboard access to your IP ranges. - [Audit logs](/dashboard/audit-logs) and [session security](/dashboard/session-security). -**Who can access your documentation site** +**Who can read your documentation** + +This is your readers. Set the [authentication](/deploy/authentication-setup) method to private, then pick how people sign in: -If your documentation must not be public, set up [authentication](/deploy/authentication-setup). Mintlify supports password protection, OAuth, JWT, and Mintlify-managed private access. You can also [restrict individual pages to specific groups](/deploy/authentication-setup#control-access-with-groups) while leaving the rest of the site public. +- **Password** is the quickest gate to stand up, and fine for a POC. +- **Mintlify-managed access** makes your dashboard organization the user list, with no extra configuration. +- **OAuth 2.0** plugs into the identity provider you already run, and is what most teams end up using. +- **JWT** gives you full programmatic control when your access model is complex. + +Authentication controls who gets in the door. [Groups](/deploy/authentication-setup#control-access-with-groups) control who sees what, set per page in frontmatter: + +```yaml +--- +title: "Production runbook" +groups: ["engineering"] +--- +``` + +Test it with two accounts, not one: sign in as someone in the group and confirm the page appears, then as someone who isn't and confirm it doesn't. That's the difference between access control being enforced and being assumed. + + + A page marked `hidden: true` is only missing from the navigation. Anyone with the URL can still open it, and this page you're reading is a working example of that. Treat hidden as an organization tool. Authentication and groups are the actual gate. See [Hidden pages](/organize/hidden-pages). + **Your domain** -Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. Mintlify provisions the TLS certificate automatically. +Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain, and Mintlify provisions the TLS certificate automatically. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain. **Analytics, checks, and compliance** @@ -292,15 +424,18 @@ Adding a [custom domain](/customize/custom-domain) needs one DNS record from who ## Step 8: Review the results -Book an hour with your decision maker and walk through your criteria from [Decide what success looks like](#decide-what-success-looks-like). Use the evidence you collected rather than impressions. +Book an hour with your decision maker. Open with the one metric you picked in [Pick one thing to prove](#pick-one-thing-to-prove) and the baseline you recorded, then walk the evidence you collected. | What you're checking | Where to check it | |---|---| | A non-developer can publish independently | Whether step 4 worked without help, and how long it took | +| Engineers keep their review process | The pull request your editor change opened, with your existing checks on it | | Your hardest content survived the move | Your sample pages, compared side by side with your current site | -| The assistant answers accurately | Your scored question list, plus [Assistant analytics](/analytics/assistant) | +| The assistant answers accurately | Your scored question list, including which page each answer cited | +| Where your content gaps are | Unanswered and downvoted questions in [Assistant analytics](/analytics/assistant) | | Readers find what they need | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) analytics | | Readers say it's better | [Page feedback](/optimize/feedback) | +| Docs stay current without manual work | The run history of the automation you enabled in step 6 | | It meets security requirements | Your IT team's sign-off from step 7 | Bring open questions to your Mintlify contact before the review, not during it. @@ -311,8 +446,8 @@ Most POCs run two to three weeks. Compressing this into a few days is possible, | Week | What happens | |---|---| -| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree on success criteria. | -| Week 2 | Steps 3 to 6: review the migrated content, publish changes yourself, apply branding, and turn on the assistant. Start collecting your assistant test questions. | +| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree the one metric and record its baseline. If authentication is in scope, start the custom domain now. | +| Week 2 | Steps 3 to 6: review the migrated content, publish a change yourself, apply branding, turn on the assistant, and enable one automation. Start scoring your assistant test questions. | | Week 3 | Steps 7 and 8: IT and security review, then the results review with your decision maker. | ## Getting help