diff --git a/agent-context/context/skills/mintlify/SKILL.md b/agent-context/context/skills/mintlify/SKILL.md index c61418297..03fdf8512 100644 --- a/agent-context/context/skills/mintlify/SKILL.md +++ b/agent-context/context/skills/mintlify/SKILL.md @@ -33,7 +33,7 @@ Read these files **only when your task requires them**. They are in the `referen If the user wants a new docs site, wants to publish docs, or has no `docs.json` yet, run this workflow yourself. Ask the user only for information or approvals you cannot supply. Recommend CLI onboarding. If the user prefers to onboard in the browser, or you cannot run terminal commands, send them to [mintlify.com/start](https://mintlify.com/start). 1. Check `node --version` (v20.17.0 or newer). Run `mint --version`; if missing, install with `npm i -g mint`. If it's installed, run `mint update`. Then run `mint instructions new-site` for current setup guidance. -2. Run `mint status`. If it shows an organization, use that account and follow **Existing account**. If the user has an account but isn't logged in, run `mint login`. If the user has no account, follow **No account**. Don't run `mint signup` yourself: from an agent or any non-interactive shell, it only prints https://mintlify.com/auth.md and creates no account. +2. Run `mint status`. If it shows an organization, use that account and follow **Existing account**. If the user has an account but isn't logged in, run `mint login` in the background and ask the user to approve the sign-in in the browser it opens. In a cloud or remote session, the browser sign-in can't return to your machine, so ask the user to run `mint login` in their own terminal. If the user has no account, follow **No account**. Don't run `mint signup` yourself: from an agent or any non-interactive shell, it only prints https://mintlify.com/auth.md and creates no account. **Existing account:** diff --git a/agent-context/context/skills/mintlify/reference/configuration.md b/agent-context/context/skills/mintlify/reference/configuration.md index df033c9e5..596802e66 100644 --- a/agent-context/context/skills/mintlify/reference/configuration.md +++ b/agent-context/context/skills/mintlify/reference/configuration.md @@ -362,12 +362,14 @@ Global content variables substituted at build time using `{{variableName}}` synt } ``` -Keys can contain letters, digits, `_`, `-`, and `.`. Values are plain strings; HTML tags in values are stripped. Use in any `.mdx` file: +Keys can contain letters, digits, `_`, `-`, and `.`. Keys are case-sensitive: a placeholder must match a key exactly. Values are plain strings; HTML tags in values are stripped. Use in any `.mdx` file: ```mdx The current API version is {{apiVersion}}. ``` +An undefined placeholder does not fail the build: it renders as literal text on the published site. Run `mint validate` to find undefined variables before publishing. + ## Redirects ```json diff --git a/mint-instructions/new-site.mdx b/mint-instructions/new-site.mdx index 4f21927f8..01efd17cd 100644 --- a/mint-instructions/new-site.mdx +++ b/mint-instructions/new-site.mdx @@ -38,9 +38,9 @@ Copy this into your plan and check items off: - **No account, or the user wants it live now: `mint deploy`.** From the directory with `docs.json`, run `mint deploy --subdomain `. It provisions `https://.mintlify.site` and a hosted Git repository with a short-lived write token, and prints the Git commands. Clone that repository into a separate directory, copy the docs in (never `.env`, `.git` or `node_modules`), commit, and push to `main` with the token as a Bearer header for that Git command only. The push starts the build. - To keep the token out of your transcript, save the output to a file outside the repository and read the repository URL and token into shell variables from it. If you lose the token or it expires (see `Write token expires` in the output), run `mint deploy` again from the same directory: it reuses the site and prints a fresh token. - The site expires 24 hours after creation unless a person claims it (see `Expires` in the output), and then Mintlify deletes it. Ask the user which email address should own it (never invent one), then run `mint claim --email ` from the same directory (or pass `--directory`) and give them the claim link. They open it, sign in or create an account, and read you a code. Run `mint claim --code ` to finish. Do not sign in for them, and do not read or print the credentials the CLI stores; it reads them itself. - - To create a second site instead of reusing this one, run `mint deploy --new --subdomain `. + - For a second site, run `mint deploy --new --subdomain `. - If `mint deploy` fails with `HTTP 429` (`rate_limit_exceeded`), nothing was created. Tell the user, and retry once a few minutes later. Do not loop: repeated attempts keep the limit in place. - - **The user has a Mintlify account:** run `mint login` and use their repository (step 5). + - **The user has a Mintlify account:** run `mint login` in the background, have them approve it in the browser (in a cloud session, they run it themselves), and use their repository (step 5). - **The docs live in the user's GitHub repository and they want every push to deploy:** from the repository root, with a GitHub `origin` remote and the GitHub CLI signed in, run `mint deploy --github --subdomain ` (add `--directory docs` if the docs are in a subfolder). It writes `.github/workflows/mintlify.yml`; commit and push it. This works only for unclaimed sites; after the user claims the site, they connect the repository from the dashboard instead. Pass `--force` only if the user agrees to overwrite an existing workflow file. - **The user wants their own account now:** you cannot create it for them. Publish with `mint deploy` and let them claim the site (claiming creates the account), or send them to web onboarding at https://mintlify.com/start. 5. **Own repository (login path).** Mintlify deploys from the Git repository connected during onboarding. diff --git a/skill.md b/skill.md index 3ec8824ab..c12612633 100644 --- a/skill.md +++ b/skill.md @@ -35,7 +35,7 @@ Read these **only when your task requires them**. Each links to a Mintlify docum If the user wants a new docs site, wants to publish docs, or has no `docs.json` yet, run this workflow yourself. Ask the user only for information or approvals you cannot supply. Recommend CLI onboarding. If the user prefers to onboard in the browser, or you cannot run terminal commands, send them to [mintlify.com/start](https://mintlify.com/start). 1. Check `node --version` (v20.17.0 or newer). Run `mint --version`; if missing, install with `npm i -g mint`. If it's installed, run `mint update`. Then run `mint instructions new-site` for current setup guidance. -2. Run `mint status`. If it shows an organization, use that account and follow **Existing account**. If the user has an account but isn't logged in, run `mint login`. If the user has no account, follow **No account**. Don't run `mint signup` yourself: from an agent or any non-interactive shell, it only prints https://mintlify.com/auth.md and creates no account. +2. Run `mint status`. If it shows an organization, use that account and follow **Existing account**. If the user has an account but isn't logged in, run `mint login` in the background and ask the user to approve the sign-in in the browser it opens. In a cloud or remote session, the browser sign-in can't return to your machine, so ask the user to run `mint login` in their own terminal. If the user has no account, follow **No account**. Don't run `mint signup` yourself: from an agent or any non-interactive shell, it only prints https://mintlify.com/auth.md and creates no account. **Existing account:**