Skip to content

Redesign the docs home page around an agent setup prompt - #8239

Open
ethanpalm wants to merge 4 commits into
mainfrom
redesign-landing-mentha
Open

ethanpalm wants to merge 4 commits into
mainfrom
redesign-landing-mentha

Conversation

@ethanpalm

@ethanpalm ethanpalm commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

Replaces #6915.

What changed

  • index.mdx: The page now runs, top to bottom:

    1. A one-sentence overview of what Mintlify is.
    2. A search field.
    3. "New to Mintlify? Start with your agent," with the setup prompt.
    4. "Choose how you work" (agent, web editor, Git and the CLI).
    5. "What do you want to do?" task cards.
    6. A "What's new" link to the changelog.

    Agents get a plain-Markdown version through <Visibility for="agents">.

  • snippets/home-search.jsx: A search field that opens the site's own search dialog. It clicks the documented [data-search-item="trigger"] hook, so readers get the same results and the same handoff to the assistant as the navbar search. If no trigger is visible, it falls back to ?search=. The shortcut hint shows ⌘K on Mac and Ctrl K elsewhere.

  • snippets/home-setup-prompt.jsx: The prompt card, laid out like Mentha's Prompt primitive. The prompt is one line: "Set up Mintlify for me. Fetch https://www.mintlify.com/docs/quickstart.md and follow its agent setup workflow."

  • home.css (about 100 lines, scoped to .mentha-home): Light and dark tokens copied from Mentha's tokens.css and palette.css, plus the shadow-weak, shadow-base, and focus-ring shadows. Everything else is Tailwind.

Rationale

The layout follows research into docs landing pages:

  • No study has tested a docs home page by itself. The best evidence comes from other angles:
    • Readers mostly land on inner pages from search.
    • Agents often fetch the home page first.
    • In a SIGDOC 2020 study, adding an overview and a core example to the starting page raised task accuracy from 74% to 86% (22 developers).
  • The search field is for readers who land here looking for something specific. GitBook does the same.
  • The setup prompt is a single line. Vercel, Neon, Cloudflare, and Clerk all use a short prompt that points at a hosted Markdown guide. The setup steps stay in one place (the agent-only section of the quickstart), and the prompt fits in a Cursor deeplink. [wip] Redesign index page #6915 kept a second copy of the steps, and it had already drifted: it still told agents to run mint signup.
  • Cards are phrased as tasks ("Migrate your docs"), not product names, which matches the strongest competitor pages.
  • The page doesn't name specific agents. Those lists change quickly.
  • Mentha tokens are copied by hand. Docs MDX can't install @mintlify/mentha, and its unprefixed classes don't survive the mint- prefix. The multi-layer shadows have to live in CSS because Mintlify drops any class that contains a comma (see Use Tailwind in place of custom styles (DOC-426) #8222).

Alternatives considered

  • Port the marketing site's design.md. [wip] Redesign index page #6915 did this. Mentha is the newer, official system.
  • Use the built-in <Prompt> component. It doesn't match Mentha's look.
  • Add "Open in Claude" and "Open in ChatGPT." Their web chats can't run the CLI.
  • Build a custom search input that searches directly. It would duplicate the site's search. Opening the real dialog reuses search, filters, and the handoff to the assistant.

Areas of uncertainty

  • Section order: Search sits above the prompt, so the agent setup comes second. It's still above the fold on desktop.
  • Copy button: Not verified. Headless Chrome blocks clipboard writes ("Document is not focused"), so it needs a manual click.
  • Focus rings: They use Mentha's teal brand scale, not the site's #166E3F primary.
  • Mentha tokens: Copied as of v0.1.111, so they won't follow Mentha updates.
  • Translations: The es, fr, and zh home pages keep the old design until a translation PR lands.
  • Traffic data: I haven't checked our own data on home page traffic yet.

Checks

  • Search field: Clicking it in headless Chrome opens the search dialog.
  • mint broken-links: No broken links.
  • Vale: No errors or warnings on index.mdx.
  • mint a11y: Only the existing site-wide theme color warnings.
  • Rendering: Checked in mint dev in light, dark, and narrow viewports.

🤖 Generated with Claude Code


Note

Low Risk
Docs-only UI and copy changes with no backend, auth, or data handling impact.

Overview
Replaces the image-heavy intro hero with a Mentha-scoped landing page (mentha-home) built from new home.css tokens (light/dark surfaces, shadows, focus rings) plus Tailwind in index.mdx.

The human view now flows overview → search → agent setup prompt → “choose how you work” path cards → task-based explore cards → changelog. HomeSearch reuses the real site search by clicking the documented trigger (with ?search= fallback and ⌘K / Ctrl K hint). HomeSetupPrompt shows a one-line agent prompt with Copy and Open in Cursor, pointing agents at the quickstart workflow instead of duplicating steps on the page.

<Visibility for="agents"> adds a plain-Markdown equivalent of the same links and setup guidance. Front matter description/keywords are updated to match the new positioning.

Reviewed by Cursor Bugbot for commit 1623dab. Bugbot is set up for automated code reviews on this repo. Configure here.

Replace the hero cards with a prompt that sends coding agents to the
quickstart's agent setup workflow, followed by three ways to work and an
explore grid. Styling ports tokens and shadows from the Mentha design
system into a scoped home.css; layout uses Tailwind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
Mintlify Docs 🟢 Ready View Preview Nov 3, 2026, 12:47 AM

ethanpalm and others added 2 commits November 2, 2026 16:27
Based on docs landing page research: lead with what Mintlify is, add a
prominent search field that opens the site's search dialog, shorten the
agent prompt to a pointer at the quickstart workflow, phrase the explore
cards as tasks, drop agent brand names, and link the changelog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keeps JavaScript out of index.mdx so Vale lints only prose. Vale was
flagging variable names and string literals in the inline export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
staging — 1623dab6 Deployed Nov 3, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant