From 35cb131b7da066f2702c762a2ab52ea0213092b6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 7 Aug 2026 16:33:04 -0700 Subject: [PATCH 1/2] Redesign the docs introduction page in the new Mintlify design language Ports the landing site's design system (mintlify/landing public/design.md) to the docs home page: warm neutral surfaces, hairline rails framing the content column, a dot field in the page margins, 6px cards, and the brand green that shifts hue between light and dark. - Add home.css with the landing tokens, scoped to `.mint-home` so nothing reaches the rest of the site. - Replace the illustrated HeroCards with icon-led cards on the landing card spec (muted Lucide icon, whitespace, bottom-anchored title and description, hover reveals a trailing arrow and tints the icon brand green). - Swap the decorative hero SVGs for a CSS dot field, and add a copy-to-clipboard CLI install command to the hero, matching the landing hero's CTA row. - Keep headings in Inter at the landing display sizes and tracking; the serif display face is licensed and not available to the docs build. Copy is unchanged. --- home.css | 331 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ index.mdx | 192 +++++++++++++++++++++++-------- 2 files changed, 479 insertions(+), 44 deletions(-) create mode 100644 home.css diff --git a/home.css b/home.css new file mode 100644 index 0000000000..5f7500fc8d --- /dev/null +++ b/home.css @@ -0,0 +1,331 @@ +/* ========================================================================== + Docs home page + + Ports the Mintlify landing design system (mintlify/landing → public/design.md) + to the docs introduction page: warm neutral surfaces, hairline rails, 6px + cards, 4px buttons, and the brand green that shifts hue between themes. + + Every rule is scoped to `.mint-home`, so nothing here reaches the rest of the + site. Mintlify loads every `.css` file in the content directory on every page. + ========================================================================== */ + +.mint-home { + /* Surfaces */ + --home-surface: #faf8f5; + --home-surface-hover: #f3f0eb; + --home-border: rgba(0, 0, 0, 0.04); + --home-border-hover: rgba(0, 0, 0, 0.09); + --home-line: #f1f0ee; + + /* Foreground */ + --home-fg: #121715; + --home-fg-secondary: #485450; + --home-fg-tertiary: #717d79; + --home-fg-muted: #969e9b; + + /* Brand green shifts hue across themes — deep on light, vivid mint on dark. */ + --home-brand: #0c8c5e; + --home-brand-10: rgba(12, 140, 94, 0.1); + + --home-dot: rgba(18, 23, 21, 0.16); + + --home-ease: cubic-bezier(0.22, 1, 0.36, 1); + + color: var(--home-fg-secondary); +} + +html.dark .mint-home { + --home-surface: rgba(255, 255, 255, 0.03); + --home-surface-hover: rgba(255, 255, 255, 0.06); + --home-border: rgba(255, 255, 255, 0.08); + --home-border-hover: rgba(255, 255, 255, 0.16); + --home-line: #1e1f21; + + --home-fg: #faf8f5; + --home-fg-secondary: #d9d7d4; + --home-fg-tertiary: #cfcdca; + --home-fg-muted: #969e9b; + + --home-brand: #18e299; + --home-brand-10: rgba(24, 226, 153, 0.1); + + --home-dot: rgba(250, 248, 245, 0.16); +} + +/* -------------------------------------------------------------------------- + Structure + + Content sits inside a 1088px column framed by vertical hairlines — the + landing site's "rails". The rails only appear once there is margin to spare. + -------------------------------------------------------------------------- */ + +.mint-home-rail { + max-width: 1088px; + margin-inline: auto; +} + +@media (width >= 64rem) { + .mint-home-rail { + border-inline: 1px solid var(--home-line); + } +} + +.mint-home-divider { + border-top: 1px solid var(--home-line); +} + +/* Decorative dot field in the page margins. Two nested masks: the wrapper + fades the field out toward the bottom, the inner layer clears the center so + dots never sit behind the copy. */ +.mint-home-dots-fade { + -webkit-mask-image: linear-gradient(to bottom, #000 0%, #000 35%, transparent 92%); + mask-image: linear-gradient(to bottom, #000 0%, #000 35%, transparent 92%); +} + +.mint-home-dots { + background-image: radial-gradient(var(--home-dot) 1px, transparent 1.25px); + background-size: 16px 16px; + /* Narrow margins on small screens, so the field never creeps under the copy. */ + -webkit-mask-image: linear-gradient( + to right, + #000 0%, + transparent 14%, + transparent 86%, + #000 100% + ); + mask-image: linear-gradient(to right, #000 0%, transparent 14%, transparent 86%, #000 100%); +} + +@media (width >= 64rem) { + .mint-home-dots { + -webkit-mask-image: linear-gradient( + to right, + #000 0%, + transparent 26%, + transparent 74%, + #000 100% + ); + mask-image: linear-gradient(to right, #000 0%, transparent 26%, transparent 74%, #000 100%); + } +} + +/* -------------------------------------------------------------------------- + Typography + -------------------------------------------------------------------------- */ + +.mint-home-title { + margin: 0; + font-size: 2.25rem; + line-height: 2.375rem; + letter-spacing: -1.2px; + font-weight: 500; + text-wrap: balance; + color: var(--home-fg); +} + +@media (width >= 40rem) { + .mint-home-title { + font-size: 2.75rem; + line-height: 2.875rem; + letter-spacing: -1.6px; + } +} + +@media (width >= 64rem) { + .mint-home-title { + font-size: 3.5rem; + line-height: 3.5rem; + letter-spacing: -2.24px; + } +} + +.mint-home-lede { + margin: 0; + font-size: 1rem; + line-height: 1.5rem; + text-wrap: pretty; + color: var(--home-fg-secondary); +} + +/* Section heading, matching the landing site's section header spec. */ +.mint-home-heading { + margin: 0; + font-size: 1.75rem; + line-height: 2rem; + letter-spacing: -0.72px; + font-weight: 500; + text-wrap: balance; + color: var(--home-fg); +} + +@media (width >= 64rem) { + .mint-home-heading { + font-size: 2.25rem; + line-height: 2.5rem; + } +} + +.mint-home-eyebrow { + margin: 0; + font-size: 0.75rem; + line-height: 1rem; + font-weight: 500; + letter-spacing: 0.24px; + color: var(--home-brand); +} + +/* -------------------------------------------------------------------------- + Cards + -------------------------------------------------------------------------- */ + +.mint-home-card { + position: relative; + display: flex; + flex-direction: column; + min-height: 15rem; + padding: 1rem; + border: 1px solid var(--home-border); + border-radius: 6px; + background-color: var(--home-surface); + text-decoration: none; + transition: + background-color 150ms var(--home-ease), + border-color 150ms var(--home-ease); +} + +.mint-home-card:hover { + background-color: var(--home-surface-hover); + border-color: var(--home-border-hover); +} + +.mint-home-card-icon { + display: flex; + align-items: center; + justify-content: center; + width: 1.25rem; + height: 1.25rem; + flex-shrink: 0; + color: var(--home-fg-muted); + transition: color 150ms var(--home-ease); +} + +.mint-home-card:hover .mint-home-card-icon { + color: var(--home-brand); +} + +.mint-home-card-title { + margin: 0; + display: flex; + align-items: center; + gap: 0.375rem; + font-size: 1.125rem; + line-height: 1.5rem; + font-weight: 500; + color: var(--home-fg); +} + +.mint-home-card-body { + margin: 0; + font-size: 1rem; + line-height: 1.5rem; + text-wrap: pretty; + color: var(--home-fg-secondary); +} + +/* Cards in a row are equal height and bottom-align their text block, so a + one-line description would ride up and break the title baseline across the + row. Reserving two lines keeps the titles level. */ +@media (width >= 40rem) { + .mint-home-card-body { + min-height: 3rem; + } +} + +/* Trailing arrow that slides out on hover. */ +.mint-home-arrow { + flex-shrink: 0; + transform: translateX(-2px); + opacity: 0; + transition: + transform 150ms var(--home-ease), + opacity 150ms var(--home-ease); +} + +.mint-home-card:hover .mint-home-arrow { + transform: translateX(0); + opacity: 1; +} + +/* -------------------------------------------------------------------------- + Copy-command button + -------------------------------------------------------------------------- */ + +.mint-home-copy { + display: inline-flex; + align-items: center; + gap: 0.625rem; + padding: 0.625rem 0.625rem 0.625rem 0.75rem; + border: 1px solid var(--home-border-hover); + border-radius: 4px; + background-color: var(--home-surface); + cursor: pointer; + transition: background-color 150ms var(--home-ease); +} + +.mint-home-copy:hover { + background-color: var(--home-surface-hover); +} + +.mint-home-copy:focus-visible { + outline: 2px solid var(--home-brand); + outline-offset: 2px; +} + +.mint-home-copy-prompt { + color: var(--home-fg-muted); + font-size: 0.875rem; + line-height: 1rem; +} + +/* Strip the site's inline-code chrome so the command reads as terminal text + inside the button rather than a box within a box. */ +.mint-home-copy-command { + padding: 0; + border: 0; + background: none; + font-size: 0.875rem; + line-height: 1rem; + font-weight: 400; + color: var(--home-fg); +} + +.mint-home-copy-command::before, +.mint-home-copy-command::after { + content: none; +} + +.mint-home-copy-icon { + display: flex; + align-items: center; + justify-content: center; + width: 1.25rem; + height: 1.25rem; + color: var(--home-fg-muted); +} + +.mint-home-copy:hover .mint-home-copy-icon { + color: var(--home-fg-secondary); +} + +.mint-home-copy-icon--done { + color: var(--home-brand); +} + +@media (prefers-reduced-motion: reduce) { + .mint-home-card, + .mint-home-card-icon, + .mint-home-arrow, + .mint-home-copy { + transition: none; + } +} diff --git a/index.mdx b/index.mdx index a1efde0bac..072c040caa 100644 --- a/index.mdx +++ b/index.mdx @@ -6,75 +6,179 @@ keywords: ["overview", "platform", "getting started", "features"] boost: 3 --- +{/* Styles live in home.css, scoped to `.mint-home`. They port the tokens from + the Mintlify landing design system: warm neutral surfaces, hairline rails, + 6px cards, and a brand green that shifts hue between light and dark. */} + {/* vale Mintlify.Semicolons = NO */} -export const HeroCard = ({ filename, title, description, href }) => { +export const Icon = ({ children }) => { return ( - - - -

- {title} -

- {description} + + ); +}; + +export const ArrowIcon = () => { + return ( + + ); +}; + +export const HomeCard = ({ icon, title, description, href }) => { + return ( + + {icon} +
+

+ {title} + +

+

{description}

+
); }; +export const CopyCommand = ({ command }) => { + const [copied, setCopied] = useState(false); + + const copy = () => { + navigator.clipboard.writeText(command); + setCopied(true); + setTimeout(() => setCopied(false), 1600); + }; + + return ( + + ); +}; + {/* vale Mintlify.Semicolons = YES */} -
-
- Decorative background image. - Decorative background image. -
- -
-

- Documentation -

- -
- Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers and teams. +
+
+
+ +
+ +
+
+ + + + + + + } + title="Quickstart" + description="Deploy your first docs site in minutes with our step-by-step guide" + href="/quickstart" + /> - + + + + } title="CLI installation" description="Install the CLI to preview and develop your docs locally" href="/installation" /> - + + + + } title="Web editor" description="Make quick updates and manage content with our browser-based editor" href="/editor/index" /> - + + + + + + } title="Components" description="Build rich, interactive documentation with our ready-to-use components" href="/components/accordions" />
-
+
From 455ec265cd48c74103f65ff9bf17891a6766cffd Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 7 Aug 2026 16:50:31 -0700 Subject: [PATCH 2/2] Swap the hero install command for a collapsible agent setup prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The introduction hero now leads with the full "set up Mintlify with your agent" prompt from the quickstart instead of `npm i -g mint`. It lands collapsed to four lines behind a fade and expands in place, with Copy prompt and Open in Cursor reachable in both states — reading the prompt is optional, running it is the point. The prompt text now also exists as a string in snippets/setup-agent-prompt-text.mdx, because the built-in component serializes its children's source rather than evaluating them and so cannot be handed a variable. Both copies must be edited together; .github/workflows/check-prompt-sync.yml fails the build if they drift. The quickstart's card is unchanged, byte for byte. --- .github/scripts/check-prompt-sync.mjs | 64 +++++++++ .github/workflows/check-prompt-sync.yml | 24 ++++ home.css | 183 +++++++++++++++++++----- index.mdx | 97 +++++++++---- snippets/setup-agent-prompt-text.mdx | 30 ++++ snippets/setup-agent-prompt.mdx | 5 + 6 files changed, 341 insertions(+), 62 deletions(-) create mode 100644 .github/scripts/check-prompt-sync.mjs create mode 100644 .github/workflows/check-prompt-sync.yml create mode 100644 snippets/setup-agent-prompt-text.mdx diff --git a/.github/scripts/check-prompt-sync.mjs b/.github/scripts/check-prompt-sync.mjs new file mode 100644 index 0000000000..d9475d0420 --- /dev/null +++ b/.github/scripts/check-prompt-sync.mjs @@ -0,0 +1,64 @@ +/** + * The agent setup prompt lives in two files: + * + * snippets/setup-agent-prompt.mdx — card used on the quickstart + * snippets/setup-agent-prompt-text.mdx — the same text as a JS string, used by + * the introduction page's own prompt card + * + * They have to be separate because the component serializes its + * children's *source* rather than evaluating them, so it cannot be handed a + * variable. This script fails CI if the two ever drift apart. + */ + +import { readFileSync } from "node:fs"; + +const CARD = "snippets/setup-agent-prompt.mdx"; +const TEXT = "snippets/setup-agent-prompt-text.mdx"; + +function fromPromptCard(path) { + const lines = readFileSync(path, "utf8").split("\n"); + const open = lines.findIndex((l) => l.startsWith(" l.trim() === ""); + if (open === -1 || close === -1 || close < open) { + throw new Error(`${path}: could not find a ... block`); + } + return lines.slice(open + 1, close).join("\n").trim(); +} + +function fromConstant(path) { + const src = readFileSync(path, "utf8"); + const match = src.match(/export const SETUP_AGENT_PROMPT = `([\s\S]*)`;/); + if (!match) { + throw new Error(`${path}: could not find the SETUP_AGENT_PROMPT template literal`); + } + return match[1] + .replace(/\\`/g, "`") + .replace(/\\\$\{/g, "${") + .replace(/\\\\/g, "\\") + .trim(); +} + +const card = fromPromptCard(CARD); +const text = fromConstant(TEXT); + +if (card === text) { + console.log(`The setup prompt matches in ${CARD} and ${TEXT}.`); + process.exit(0); +} + +const cardLines = card.split("\n"); +const textLines = text.split("\n"); +const firstDiff = cardLines.findIndex((line, i) => line !== textLines[i]); + +console.error(`The setup prompt has drifted between ${CARD} and ${TEXT}.`); +console.error("Edit one, then copy the change into the other.\n"); + +if (firstDiff !== -1) { + console.error(`First difference at line ${firstDiff + 1}:`); + console.error(` ${CARD}:\n ${cardLines[firstDiff] ?? "(missing)"}`); + console.error(` ${TEXT}:\n ${textLines[firstDiff] ?? "(missing)"}`); +} else { + console.error(`${CARD} has ${cardLines.length} lines, ${TEXT} has ${textLines.length}.`); +} + +process.exit(1); diff --git a/.github/workflows/check-prompt-sync.yml b/.github/workflows/check-prompt-sync.yml new file mode 100644 index 0000000000..64f3ba2376 --- /dev/null +++ b/.github/workflows/check-prompt-sync.yml @@ -0,0 +1,24 @@ +name: Check setup prompt sync + +on: + pull_request: + paths: + - snippets/setup-agent-prompt.mdx + - snippets/setup-agent-prompt-text.mdx + - .github/scripts/check-prompt-sync.mjs + - .github/workflows/check-prompt-sync.yml + +permissions: + contents: read + +jobs: + check: + name: Check setup prompt sync + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: actions/setup-node@v6 + with: + node-version: 24 + package-manager-cache: false + - run: node .github/scripts/check-prompt-sync.mjs diff --git a/home.css b/home.css index 5f7500fc8d..e7168870ab 100644 --- a/home.css +++ b/home.css @@ -29,6 +29,10 @@ --home-dot: rgba(18, 23, 21, 0.16); + /* Theme-flipping absolutes, for the solid primary button. */ + --home-invert-bg: #0a0b0f; + --home-invert-fg: #faf8f5; + --home-ease: cubic-bezier(0.22, 1, 0.36, 1); color: var(--home-fg-secondary); @@ -50,6 +54,9 @@ html.dark .mint-home { --home-brand-10: rgba(24, 226, 153, 0.1); --home-dot: rgba(250, 248, 245, 0.16); + + --home-invert-bg: #faf8f5; + --home-invert-fg: #121715; } /* -------------------------------------------------------------------------- @@ -257,75 +264,181 @@ html.dark .mint-home { } /* -------------------------------------------------------------------------- - Copy-command button + Buttons -------------------------------------------------------------------------- */ -.mint-home-copy { +.mint-home-btn { display: inline-flex; align-items: center; - gap: 0.625rem; - padding: 0.625rem 0.625rem 0.625rem 0.75rem; - border: 1px solid var(--home-border-hover); + justify-content: center; + gap: 0.375rem; + padding: 0.5rem 0.75rem; + border: 1px solid transparent; border-radius: 4px; - background-color: var(--home-surface); + font-size: 0.8125rem; + line-height: 1rem; + font-weight: 500; + text-decoration: none; + white-space: nowrap; cursor: pointer; - transition: background-color 150ms var(--home-ease); + transition: + background-color 150ms var(--home-ease), + border-color 150ms var(--home-ease), + opacity 150ms var(--home-ease); +} + +.mint-home-btn:focus-visible { + outline: 2px solid var(--home-brand); + outline-offset: 2px; +} + +.mint-home-btn svg { + width: 1rem; + height: 1rem; + flex-shrink: 0; +} + +.mint-home-btn--primary { + background-color: var(--home-invert-bg); + color: var(--home-invert-fg); } -.mint-home-copy:hover { +.mint-home-btn--primary:hover { + opacity: 0.88; +} + +.mint-home-btn--secondary { + border-color: var(--home-border-hover); + background-color: var(--home-surface); + color: var(--home-fg); +} + +.mint-home-btn--secondary:hover { background-color: var(--home-surface-hover); } -.mint-home-copy:focus-visible { - outline: 2px solid var(--home-brand); - outline-offset: 2px; +/* -------------------------------------------------------------------------- + Setup prompt + + The full agent setup prompt is long, so it lands collapsed to a few lines + behind a fade and expands in place. Copy and Cursor stay reachable in both + states — reading the prompt is optional, running it is the point. + -------------------------------------------------------------------------- */ + +.mint-home-prompt { + width: 100%; + max-width: 40rem; + overflow: hidden; + border: 1px solid var(--home-border-hover); + border-radius: 6px; + background-color: var(--home-surface); + text-align: left; } -.mint-home-copy-prompt { - color: var(--home-fg-muted); - font-size: 0.875rem; - line-height: 1rem; +.mint-home-prompt-head { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: space-between; + gap: 0.75rem; + padding: 0.75rem; } -/* Strip the site's inline-code chrome so the command reads as terminal text - inside the button rather than a box within a box. */ -.mint-home-copy-command { - padding: 0; - border: 0; - background: none; +.mint-home-prompt-label { + display: flex; + align-items: center; + gap: 0.5rem; font-size: 0.875rem; - line-height: 1rem; - font-weight: 400; + line-height: 1.25rem; + font-weight: 500; color: var(--home-fg); } -.mint-home-copy-command::before, -.mint-home-copy-command::after { - content: none; +.mint-home-prompt-label svg { + flex-shrink: 0; + color: var(--home-brand); } -.mint-home-copy-icon { +.mint-home-prompt-actions { display: flex; align-items: center; - justify-content: center; - width: 1.25rem; - height: 1.25rem; - color: var(--home-fg-muted); + gap: 0.375rem; +} + +.mint-home-prompt-body { + position: relative; + max-height: 6.5rem; + overflow: hidden; + padding: 0 0.75rem; + border-top: 1px solid var(--home-border); + transition: max-height 250ms var(--home-ease); + /* Fades the last visible line so the clip reads as "there is more". */ + -webkit-mask-image: linear-gradient(to bottom, #000 55%, transparent 100%); + mask-image: linear-gradient(to bottom, #000 55%, transparent 100%); +} + +.mint-home-prompt[data-expanded] .mint-home-prompt-body { + max-height: 22rem; + overflow-y: auto; + -webkit-mask-image: none; + mask-image: none; } -.mint-home-copy:hover .mint-home-copy-icon { +.mint-home-prompt-text { + margin: 0; + padding: 0.75rem 0; + white-space: pre-wrap; + font-size: 0.8125rem; + line-height: 1.375rem; color: var(--home-fg-secondary); } -.mint-home-copy-icon--done { - color: var(--home-brand); +.mint-home-prompt-toggle { + display: flex; + align-items: center; + justify-content: center; + gap: 0.25rem; + width: 100%; + padding: 0.625rem; + border: 0; + border-top: 1px solid var(--home-border); + background: none; + font-size: 0.8125rem; + line-height: 1rem; + font-weight: 500; + color: var(--home-fg-tertiary); + cursor: pointer; + transition: color 150ms var(--home-ease); +} + +.mint-home-prompt-toggle:hover { + color: var(--home-fg); +} + +.mint-home-prompt-toggle:focus-visible { + outline: 2px solid var(--home-brand); + outline-offset: -2px; +} + +.mint-home-prompt-toggle svg { + width: 1rem; + height: 1rem; + flex-shrink: 0; + transition: transform 250ms var(--home-ease); +} + +.mint-home-prompt[data-expanded] .mint-home-prompt-toggle svg { + transform: rotate(180deg); } @media (prefers-reduced-motion: reduce) { .mint-home-card, .mint-home-card-icon, .mint-home-arrow, - .mint-home-copy { + .mint-home-btn, + .mint-home-prompt-body, + .mint-home-prompt-toggle, + .mint-home-prompt-toggle svg { transition: none; } } diff --git a/index.mdx b/index.mdx index 072c040caa..5cdee4a0a0 100644 --- a/index.mdx +++ b/index.mdx @@ -6,6 +6,8 @@ keywords: ["overview", "platform", "getting started", "features"] boost: 3 --- +import { SETUP_AGENT_PROMPT } from "/snippets/setup-agent-prompt-text.mdx"; + {/* Styles live in home.css, scoped to `.mint-home`. They port the tokens from the Mintlify landing design system: warm neutral surfaces, hairline rails, 6px cards, and a brand green that shifts hue between light and dark. */} @@ -67,39 +69,80 @@ export const HomeCard = ({ icon, title, description, href }) => { ); }; -export const CopyCommand = ({ command }) => { +export const SetupPrompt = ({ prompt }) => { const [copied, setCopied] = useState(false); + const [expanded, setExpanded] = useState(false); const copy = () => { - navigator.clipboard.writeText(command); + navigator.clipboard.writeText(prompt); setCopied(true); setTimeout(() => setCopied(false), 1600); }; return ( - +
+
+ + + Set up Mintlify with your agent + + +
+ + + + Open in Cursor + +
+
+ +
+
{prompt}
+
+ + +
); }; @@ -111,7 +154,7 @@ export const CopyCommand = ({ command }) => {
-
+

Documentation

@@ -120,7 +163,7 @@ export const CopyCommand = ({ command }) => {

- +
diff --git a/snippets/setup-agent-prompt-text.mdx b/snippets/setup-agent-prompt-text.mdx new file mode 100644 index 0000000000..02f4414197 --- /dev/null +++ b/snippets/setup-agent-prompt-text.mdx @@ -0,0 +1,30 @@ +{/* vale off */} + +{/* The agent setup prompt as a string, for the introduction page's collapsible + prompt card. It is a verbatim copy of the body in + /snippets/setup-agent-prompt.mdx — the component serializes its + children's source instead of evaluating them, so it cannot be handed this + variable. EDIT BOTH FILES TOGETHER; .github/workflows/check-prompt-sync.yml + fails the build if they drift. */} + +export const SETUP_AGENT_PROMPT = `Get my documentation live on a published Mintlify site. You are successfully done when you give me the live URL and confirm it loads. Tell me clearly whenever a step needs my input—do everything else yourself. If this prompt was pasted before (for example, after a restart), continue from where things left off instead of starting over. If you don't have terminal or command execution access, tell me to follow the manual steps at [mintlify.com/start](https://mintlify.com/start) instead. Everything below requires running commands and requires Node.js v20.17.0+ (LTS versions recommended). + +1. Ask for my existing content that will be used for my Mintlify site. This may be a local folder or a repo. Verify the source before building: echo back exactly what you're reading and list its top-level contents so I can confirm it's right. If you can't access something I named (private repos return 404, same as nonexistent), stop and ask. Never substitute a different source. +2. Check whether \`mint\` is installed with \`mint --version\`. If it's missing, install it with \`npm i -g mint\` (or \`pnpm add -g mint\`). If it's already installed, run \`mint update\` instead of reinstalling. +3. Run \`mint status\`. If it already shows an organization, skip to step 7. +4. Needs me: If \`mint status\` shows I'm not logged in, ask me directly whether I already have a Mintlify account. Don't guess. + - If I have one: run \`mint login\`. You need me for browser steps and to approve access. + - If I don't: ask me for my first name, last name, company, and email if I haven't given them already—never invent these. Run \`mint signup --firstName [firstName] --lastName [lastName] --company [company] --email [email]\` as a background task since it blocks until I click a verification link that can take several minutes. +5. Needs me: I'll check my email and click the verification link. That opens a browser tab that automatically finishes the rest of account creation/logging in. I must approve the CLI, then connect a GitHub repository or let Mintlify host one. Tell me clearly this step is mine, then wait for it before continuing. +6. Run \`mint status\` again to confirm an organization and subdomain now exist. The subdomain isn't provisioned until I select or connect a repository during the step 5 browser flow — so if \`mint status\` shows my organization but no subdomain yet, that almost always means I haven't finished the repo step, not that anything is broken. Don't treat it as an error or poll blindly: wait until I confirm I've completed onboarding, then re-run \`mint status\`. Provisioning can still lag a few seconds after that, so retry a few times before concluding something is wrong. +7. Needs me: ask for the URL of the repository connected to my Mintlify project — \`mint status\` doesn't expose it, so you can't look it up yourself. Clone it once I give it to you. +8. Check what's in that repo. If I connected my own existing docs repo, my content is already there — don't overwrite it. If Mintlify created the repo, it contains starter template content — replace that with my actual docs content from step 1. Only use \`mint new [directory]\` if I want a different theme or template than what's in the repo — scaffold it locally, then use its output in place of the seeded content. +9. Preview with \`mint dev\`, which generally starts on \`http://localhost:3000\` unless that port is in use. It blocks until stopped, so run it as a background task. Verify the preview loads, then stop it before continuing. +10. Commit and push your changes. Mintlify deploys automatically on push. +11. Needs me: If I want a custom domain, run \`mint add-domain \`. It prints the DNS records I need to add with my domain provider. Tell me the DNS records, since only I can configure them at my registrar. Make it clear that this is a step I must complete. +12. Confirm my site is live: fetch \`https://.mintlify.site\` (find the subdomain via \`mint status\`) and confirm it loads. If I added a custom domain in step 11, also fetch that domain and confirm it loads before calling this step done—DNS propagation can lag, so retry a few times before treating a failed fetch as an error. +13. Set yourself up to keep working here: install the [Mintlify skill](https://mintlify.com/docs/ai/skillmd.md) with \`npx skills add https://mintlify.com/docs\`, then register the [admin MCP server](https://mintlify.com/docs/ai/model-context-protocol.md) at \`https://mcp.mintlify.com\` for your specific tool. For example, \`claude mcp add --transport http mintlify https://mcp.mintlify.com\` for Claude Code or fetch https://mintlify.com/docs/ai/mintlify-mcp.md for instructions for Claude, Cursor, Codex, or ChatGPT. Do this step yourself—don't ask me to run these commands. +14. Needs me: the first admin MCP tool call opens a browser window for OAuth login. Approve it there. Most tools don't load newly added MCP servers mid-session — if the Mintlify tools don't show up, tell me to restart you and we'll pick up from here. +15. If any command fails in a way not covered above, stop and tell me the exact error rather than guessing or retrying blindly. If it looks like something's wrong on Mintlify's end rather than in what you're doing, check https://status.mintlify.com or point me to https://mintlify.com/docs/contact-support.`; + +{/* vale on */} diff --git a/snippets/setup-agent-prompt.mdx b/snippets/setup-agent-prompt.mdx index 6f0ab77c77..304760f280 100644 --- a/snippets/setup-agent-prompt.mdx +++ b/snippets/setup-agent-prompt.mdx @@ -1,3 +1,8 @@ +{/* The prompt below is duplicated as a string in + /snippets/setup-agent-prompt-text.mdx for the introduction page. + EDIT BOTH FILES TOGETHER; .github/workflows/check-prompt-sync.yml fails the + build if they drift. */} + {/* vale off */}