From c64899980d796e16e3c91b2d8fa548986431d2a0 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Wed, 15 Jan 2025 19:57:20 +0000 Subject: [PATCH] Documentation edits made through Mintlify web editor --- development.mdx | 30 +- mint.json | 358 +++++----- .../authentication.mdx | 15 +- .../personalization.mdx | 42 +- .../sending-data.mdx | 17 +- settings/broken-links.mdx | 14 +- settings/global.mdx | 676 +----------------- settings/navigation.mdx | 61 +- text.mdx | 30 +- web-editor.mdx | 116 +-- 10 files changed, 361 insertions(+), 998 deletions(-) diff --git a/development.mdx b/development.mdx index 856629aaf..ebb67a5bf 100644 --- a/development.mdx +++ b/development.mdx @@ -33,7 +33,7 @@ description: 'Preview changes locally to update your docs' mintlify dev ``` -Alternatively, if you do not want to install Mintlify globally you can use a run script available: +Alternatively, if you don't want to install Mintlify globally, you can use a run script: ```bash npm @@ -51,20 +51,20 @@ Alternatively, if you do not want to install Mintlify globally you can use a run - Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. + Yarn's `dlx` run script requires Yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. A local preview of your documentation will be available at `http://localhost:3000`. ### Custom Ports -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: +By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command: ```bash mintlify dev --port 3333 ``` -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: +If you attempt to run Mintlify on a port that's already in use, it will automatically use the next available port: ```md Port 3000 is already in use. Trying 3001 instead. @@ -72,7 +72,7 @@ Port 3000 is already in use. Trying 3001 instead. ## Mintlify Versions -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: +Each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, update the CLI: @@ -92,7 +92,7 @@ Please note that each CLI release is associated with a specific version of Mintl ## Validating Links -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: +The Mintlify CLI can help validate reference links in your documentation. To identify any broken links, use the following command: ```bash mintlify broken-links @@ -100,7 +100,7 @@ mintlify broken-links ## Deployment -If the deployment is successful, you should see the following: +After a successful deployment, you should see the following: - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. - 3. Reinstall mintlify: `npm install -g mintlify` + This error may occur due to an outdated version of Node.js. Try the following: + 1. Remove the currently-installed version of Mintlify: `npm remove -g mintlify` + 2. Upgrade to Node.js v19 or higher + 3. Reinstall Mintlify: `npm install -g mintlify` - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. + Solution: Navigate to the root of your device and delete the `~/.mintlify` folder. Then, run `mintlify dev` again. - + \ No newline at end of file diff --git a/mint.json b/mint.json index 65c9d33d9..f1923c099 100644 --- a/mint.json +++ b/mint.json @@ -1,41 +1,41 @@ { - "$schema": "https://mintlify.com/schema.json", - "name": "Mintlify", + "$schema": "settings/authentication-personalization/authentication", + "name": "settings/authentication-personalization/authentication", "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg", - "href": "https://mintlify.com" + "light": "settings/authentication-personalization/authentication", + "dark": "settings/authentication-personalization/authentication", + "href": "settings/authentication-personalization/authentication" }, - "layout": "sidenav", - "favicon": "/favicon.svg", + "layout": "settings/authentication-personalization/authentication", + "favicon": "settings/authentication-personalization/authentication", "sidebar": { - "items": "border" + "items": "settings/authentication-personalization/authentication" }, "colors": { - "primary": "#0D9373", - "light": "#55D799", - "dark": "#0D9373" + "primary": "settings/authentication-personalization/authentication", + "light": "settings/authentication-personalization/authentication", + "dark": "settings/authentication-personalization/authentication" }, "api": { "auth": { - "method": "bearer" + "method": "settings/authentication-personalization/authentication" } }, "background": { - "style": "windows" + "style": "settings/authentication-personalization/authentication" }, "topbarLinks": [ { - "name": "Community", - "url": "https://mintlify.com/community" + "name": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" } ], "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/start" + "name": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, "codeBlock": { - "mode": "auto" + "mode": "settings/authentication-personalization/authentication" }, "feedback": { "thumbsRating": true, @@ -43,157 +43,157 @@ }, "tabs": [ { - "name": "Components", - "url": "content" + "name": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "name": "Integrations", - "url": "integrations" + "name": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "name": "Changelog", - "url": "changelog" + "name": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" } ], "navigation": [ { - "group": "Getting Started", + "group": "settings/authentication-personalization/authentication", "pages": [ - "quickstart", + "settings/authentication-personalization/authentication", { - "group": "Editing", - "icon": "pen-paintbrush", + "group": "settings/authentication-personalization/authentication", + "icon": "settings/authentication-personalization/authentication", "pages": [ - "development", - "web-editor" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, - "settings/global", - "settings/navigation", - "migration" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Writing Content", + "group": "settings/authentication-personalization/authentication", "pages": [ - "page", - "text", - "image-embeds", - "list-table", - "code", - "reusable-snippets" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "API References", + "group": "settings/authentication-personalization/authentication", "pages": [ - "api-playground/overview", + "settings/authentication-personalization/authentication", { - "group": "OpenAPI", - "icon": "brackets-curly", + "group": "settings/authentication-personalization/authentication", + "icon": "settings/authentication-personalization/authentication", "pages": [ - "api-playground/openapi/setup", - "api-playground/openapi/writing-openapi", - "api-playground/openapi/advanced-features" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "MDX", - "icon": "markdown", + "group": "settings/authentication-personalization/authentication", + "icon": "settings/authentication-personalization/authentication", "pages": [ - "api-playground/mdx/configuration", - "api-playground/mdx/authentication" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, - "api-playground/troubleshooting" + "settings/authentication-personalization/authentication" ] }, { - "group": "Configurations", + "group": "settings/authentication-personalization/authentication", "pages": [ - "settings/custom-domain", - "settings/seo", - "settings/broken-links", - "settings/versioning", - "settings/add-members", - "settings/github", - "settings/gitlab", - "settings/preview-deployments" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Advanced", + "group": "settings/authentication-personalization/authentication", "pages": [ { - "icon": "code", - "group": "Custom Scripts", + "icon": "settings/authentication-personalization/authentication", + "group": "settings/authentication-personalization/authentication", "pages": [ - "advanced/custom/css", - "advanced/custom/js" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "icon": "folder", - "group": "Custom Subdirectory", + "icon": "settings/authentication-personalization/authentication", + "group": "settings/authentication-personalization/authentication", "pages": [ - "advanced/subpath/cloudflare", - "advanced/subpath/route53-cloudfront", - "advanced/subpath/vercel" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "icon": "user-lock", - "group": "Auth & Personalization", + "icon": "settings/authentication-personalization/authentication", + "group": "settings/authentication-personalization/authentication", "pages": [ "settings/authentication-personalization/authentication", - "settings/authentication-personalization/personalization", - "settings/authentication-personalization/authentication-vs-personalization", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", { - "group": "Authentication Setup", + "group": "settings/authentication-personalization/authentication", "pages": [ - "settings/authentication-personalization/authentication-setup/choosing-a-handshake", - "settings/authentication-personalization/authentication-setup/password", - "settings/authentication-personalization/authentication-setup/jwt", - "settings/authentication-personalization/authentication-setup/oauth", - "settings/authentication-personalization/authentication-setup/mintlify" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Personalization Setup", + "group": "settings/authentication-personalization/authentication", "pages": [ - "settings/authentication-personalization/personalization-setup/choosing-a-handshake", - "settings/authentication-personalization/personalization-setup/shared-session", - "settings/authentication-personalization/personalization-setup/jwt", - "settings/authentication-personalization/personalization-setup/oauth" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, - "settings/authentication-personalization/sending-data" + "settings/authentication-personalization/authentication" ] }, { - "icon": "plug", - "group": "Extensions", + "icon": "settings/authentication-personalization/authentication", + "group": "settings/authentication-personalization/authentication", "pages": [ - "advanced/widget/chat" + "settings/authentication-personalization/authentication" ] }, { - "icon": "brackets-curly", - "group": "REST API", + "icon": "settings/authentication-personalization/authentication", + "group": "settings/authentication-personalization/authentication", "pages": [ - "advanced/rest-api/overview", + "settings/authentication-personalization/authentication", { - "group": "Updates", + "group": "settings/authentication-personalization/authentication", "pages": [ - "advanced/rest-api/update/trigger", - "advanced/rest-api/update/status" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Discovery API", + "group": "settings/authentication-personalization/authentication", "pages": [ - "advanced/rest-api/discovery/create-topic", - "advanced/rest-api/discovery/generate-message" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] } ] @@ -201,149 +201,149 @@ ] }, { - "group": "Analytics", + "group": "settings/authentication-personalization/authentication", "pages": [ - "integrations/analytics/overview", - "integrations/analytics/amplitude", - "integrations/analytics/clearbit", - "integrations/analytics/fathom", - "integrations/analytics/google-analytics", - "integrations/analytics/google-tag-manager", - "integrations/analytics/heap", - "integrations/analytics/hotjar", - "integrations/analytics/koala", - "integrations/analytics/logrocket", - "integrations/analytics/mixpanel", - "integrations/analytics/pirsch", - "integrations/analytics/plausible", - "integrations/analytics/posthog" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "SDKs", + "group": "settings/authentication-personalization/authentication", "pages": [ - "integrations/sdks/speakeasy", - "integrations/sdks/stainless" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Support", + "group": "settings/authentication-personalization/authentication", "pages": [ - "integrations/support/overview", - "integrations/support/intercom", - "integrations/support/front" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Privacy", + "group": "settings/authentication-personalization/authentication", "pages": [ - "integrations/privacy/overview", - "integrations/privacy/osano" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Components", + "group": "settings/authentication-personalization/authentication", "pages": [ - "content/components/accordions", - "content/components/accordion-groups", - "content/components/callouts", - "content/components/cards", - "content/components/card-groups", - "content/components/code", - "content/components/code-groups", - "content/components/frames", - "content/components/icons", - "content/components/mermaid-diagrams", - "content/components/steps", - "content/components/tabs", - "content/components/tooltips", - "content/components/update" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "API Components", + "group": "settings/authentication-personalization/authentication", "pages": [ - "content/components/params", - "content/components/responses", - "content/components/expandables", - "content/components/sticky-examples" + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication", + "settings/authentication-personalization/authentication" ] }, { - "group": "Changelog", + "group": "settings/authentication-personalization/authentication", "pages": [ - "changelog/overview" + "settings/authentication-personalization/authentication" ] } ], "footer": { "socials": { - "x": "https://x.com/mintlify", - "linkedin": "https://www.linkedin.com/company/mintlify", - "github": "https://github.com/mintlify", - "slack": "https://mintlify.com/community" + "x": "settings/authentication-personalization/authentication", + "linkedin": "settings/authentication-personalization/authentication", + "github": "settings/authentication-personalization/authentication", + "slack": "settings/authentication-personalization/authentication" }, "links": [ { - "title": "Resources", + "title": "settings/authentication-personalization/authentication", "links": [ { - "label": "Customers", - "url": "https://mintlify.com/customers" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Enterprise", - "url": "https://mintlify.com/enterprise" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Request Preview", - "url": "https://mintlify.com/preview" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Integrations", - "url": "https://mintlify.com/docs/integrations/analytics/overview" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Templates", - "url": "https://github.com/mintlify/themes" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Wall of Love", - "url": "https://mintlify.com/love" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" } ] }, { - "title": "Company", + "title": "settings/authentication-personalization/authentication", "links": [ { - "label": "Careers", - "url": "https://mintlify.com/careers" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Blog", - "url": "https://mintlify.com/blog" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Public Roadmap", - "url": "https://feedback.mintlify.com/roadmap" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Security", - "url": "https://mintlify.com/security/responsible-disclosure" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" } ] }, { - "title": "Legal", + "title": "settings/authentication-personalization/authentication", "links": [ { - "label": "Privacy Policy", - "url": "https://mintlify.com/legal/privacy" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" }, { - "label": "Terms of Service", - "url": "https://mintlify.com/legal/terms" + "label": "settings/authentication-personalization/authentication", + "url": "settings/authentication-personalization/authentication" } ] } @@ -351,10 +351,10 @@ }, "analytics": { "ga4": { - "measurementId": "G-RCYWHL7EQ7" + "measurementId": "settings/authentication-personalization/authentication" }, "koala": { - "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" + "publicApiKey": "settings/authentication-personalization/authentication" } } } \ No newline at end of file diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx index 81c5b8a7e..258fd96c8 100644 --- a/settings/authentication-personalization/authentication.mdx +++ b/settings/authentication-personalization/authentication.mdx @@ -3,23 +3,20 @@ title: "Authentication" description: "Guarantee privacy of your docs by authenticating users" --- -Authentication offers full privacy for all of your -documentation content by requiring users to authenticate before viewing any content, such as: +Authentication offers full privacy for all of your documentation content by requiring users to authenticate before viewing any content, including: - Documentation page content - Images used in documentation pages - Search results -- AI chat interactions +- AI Chat interactions -You can authenticate users through handshake methods such as: +You can authenticate users through the following Handshake methods: - [Password](./authentication-setup/password) - [JWT](./authentication-setup/jwt) - [OAuth](./authentication-setup/oauth) -- [Mintlify dashboard](./authentication-setup/mintlify) +- [Mintlify Dashboard](./authentication-setup/mintlify) -Authentication is similar to our [Personalization](./personalization) offering, but with guaranteed privacy. In addition -to securing your documentation content, all features that are available via -Personalization are also available via Authentication. +Authentication is similar to our [Personalization](./personalization) offering but with guaranteed privacy. In addition to securing your documentation content, all features available via Personalization are also available via Authentication. -Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization). +Check out our docs for more information on [choosing between Authentication and Personalization](./authentication-vs-personalization). \ No newline at end of file diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx index 05baef8e8..6c80f80a2 100644 --- a/settings/authentication-personalization/personalization.mdx +++ b/settings/authentication-personalization/personalization.mdx @@ -4,20 +4,18 @@ description: "A list of features unlocked with Personalization" --- Personalization refers to a suite of features that allow you to customize your -documentation experience based on some information about the user. There are -three major features of Personalization: +documentation experience based on information about the user. There are three major features +of Personalization: -- **Customize MDX content** with a user's information, such as their name, plan, or title. - -- **Prefill API keys** in the API Playground for streamlined use. - -- **Selectively show pages** in the navigation based on a user's groups. +- **Customize MDX Content** with user information such as name, plan, or title +- **Prefill API Keys** in the API Playground for streamlined use +- **Selectively Show Pages** in the navigation based on user groups ## How to Use ### Customizing MDX Content -When writing content, you can use the `user` variable to access the information you have sent to your docs. Here's a simple example: +When writing content, you can use the `user` variable to access information you have sent to your docs. Here's a simple example: Hello, {user.name ?? 'reader'}! @@ -25,41 +23,41 @@ Hello, {user.name ?? 'reader'}! Hello, {user.name ?? 'reader'}! ``` -This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan: +This feature becomes even more powerful when paired with custom user data. Here's a real-world example that provides specific instructions for accessing the Personalization feature based on the customer's existing plan: Personalization is an enterprise feature. { user.org === undefined -? <>To access this feature, first create an account at the Mintlify dashboard. +? <>To access this feature, first create an account at the Mintlify Dashboard. : user.org.plan !== 'enterprise' -? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. -: <>To request this feature for your enterprise org, contact our team. +? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our Sales team. +: <>To request this feature for your Enterprise org, contact our team. } ```jsx Personalization is an enterprise feature. { user.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. + ? <>To access this feature, first create an account at the Mintlify Dashboard. : user.org.plan !== 'enterprise' - ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. + ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our Sales team. + : <>To request this feature for your Enterprise org, contact our team. } ``` The information in `user` is only available after a user has logged in. For - logged out users, the value of `user` will be `{}`. To prevent the page from + logged-out users, the value of `user` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `user` - fields, e.g. `{user.org?.plan}` + fields (e.g., `{user.org?.plan}`). ### Prefilling API Keys -If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground. +If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Ensure that field names in the user info exactly match the names in the API Playground. ### Showing/Hiding Pages -By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. -When determining which pages to show to the user, Mintlify will check which groups the user belongs to. +By default, every page is visible to every user. To restrict which pages are visible to your users, add a `groups` field in your page metadata. +When determining page visibility, Mintlify checks which groups the user belongs to. If the user is not in any of the groups listed in the page metadata, the page will not be shown. ```md @@ -70,7 +68,7 @@ groups: ["admin"] --- ``` -Here's a table that displays whether a page is shown for different combinations of `groups` in User and page metadata: +Here's a table that displays page visibility for different combinations of `groups` in User and page metadata: | | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User | | :------------------------------ | :------------------: | :------------------: | :-------------------------: | @@ -81,4 +79,4 @@ Here's a table that displays whether a page is shown for different combinations Note that an empty array in the page metadata is interpreted as "No groups should see this page." - + \ No newline at end of file diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index e969fa8bc..704bfac99 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -24,27 +24,28 @@ type User = { type="number" > The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted. - For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks. + For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid and should be set as low as possible, ideally 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale and can be anywhere from one day to several weeks. + - A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown. + A list of groups that the user belongs to. This will determine which pages should be shown to this user. A page will be shown if any of these groups are listed in that page's `groups` metadata field. + - A bag of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!` + A collection of values that can be accessed from within MDX content using the `user` variable. For example, if you supply `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!` + - User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. - - The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section. - + User-specific values that will be prefilled in the API Playground. For example, if each customer makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as your `apiPlaygroundInputs` field. This value will be prefilled on any API page with this `subdomain` value. - \ No newline at end of file + The `header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To verify if a field will be prefilled, check your existing docs to see if the field appears in either the `Authorization` or `Server` section. + \ No newline at end of file diff --git a/settings/broken-links.mdx b/settings/broken-links.mdx index 7bd9f7e69..79495d1d6 100644 --- a/settings/broken-links.mdx +++ b/settings/broken-links.mdx @@ -4,21 +4,21 @@ description: "Tools to help prevent invalid links" icon: 'link-simple' --- -When you change the path of a file in your docs folder, it will also change the path of the URL to that page. This may happen when restructuring your docs or changing the sidebar title. +When you change a file's path in your docs folder, the URL path to that page will also change. This commonly occurs when restructuring your docs or modifying sidebar titles. ## Broken Links -Catch broken links with our CLI. Simply [install the CLI](/development) and run the command: +You can catch broken links using our CLI. Simply [install the CLI](/development) and run the following command: ```bash mintlify broken-links ``` -The CLI will identify any relative links in your docs that don't exist. +The CLI will identify any relative links in your docs that don't exist in your documentation. ## Redirects -Set up 301 redirects by adding the `redirects` field into your `mint.json` file. +Set up 301 redirects by adding the `redirects` field to your `mint.json` file. ```json "redirects": [ @@ -29,9 +29,9 @@ Set up 301 redirects by adding the `redirects` field into your `mint.json` file. ] ``` -This will permanently redirect `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page. +This will permanently redirect `/source/path` to `/destination/path`, ensuring you don't lose any previous SEO value for the original page. -To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` will match `/beta/introduction` and redirects it to `/v2/introduction`. +To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` matches `/beta/introduction` and redirects it to `/v2/introduction`: ```json "redirects": [ @@ -40,4 +40,4 @@ To match a wildcard path, use `*` after a parameter. In this example, `/beta/:sl "destination": "/v2/:slug*" } ] -``` +``` \ No newline at end of file diff --git a/settings/global.mdx b/settings/global.mdx index 350cb3c18..0e92ae8c3 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -4,22 +4,18 @@ description: "Customize your documentation using the mint.json file" icon: "wrench" --- -Every Mintlify site needs a `mint.json` file with the core configuration -settings. Learn more about the [properties](#properties) or from an -[example](#example-mint-json) +Every Mintlify site needs a `mint.json` file with core configuration settings. Learn more about the available [properties](#properties) or see an [example configuration](#example-mint-json). ## Properties ### Styling - Name of your company or project. Used for the global title. + Name of your company or project to be used as the global title. - Path to logo image or object with path to "light" and "dark" mode logo images, - and where the logo links to. SVG format is recommended. It does not pixelate - and the file size is generally smaller. + Path to your logo image or an object with paths to "light" and "dark" mode logo images, along with where the logo links to. SVG format is recommended since it does not pixelate and generally has a smaller file size. @@ -31,14 +27,14 @@ settings. Learn more about the [properties](#properties) or from an - Where clicking on the logo links you to + The URL where clicking the logo will direct users - Path to the favicon image. For example: `/path/to/favicon.svg` + Path to your favicon image. For example: `/path/to/favicon.svg` @@ -46,17 +42,15 @@ settings. Learn more about the [properties](#properties) or from an - The primary color. Used most often for highlighted content, section - headers, accents, in light mode + The primary color used for highlighted content, section headers, and accents in light mode - The primary color for dark mode. Used most often for highlighted content, - section headers, accents, in dark mode + The primary color used for highlighted content, section headers, and accents in dark mode - The primary color for important buttons + The primary color used for important buttons @@ -64,11 +58,11 @@ settings. Learn more about the [properties](#properties) or from an - The hex color code of the background in light mode + The hex color code for the background in light mode - The hex color code of the background in dark mode + The hex color code for the background in dark mode @@ -77,8 +71,7 @@ settings. Learn more about the [properties](#properties) or from an - A preset theme configuration that changes the look and feel of the project. A - theme is a set of default styling configurations. Examples: + A preset theme configuration that changes the look and feel of your documentation. A theme is a set of default styling configurations. See examples: [Venus](https://starter-venus.mintlify.app), [Quill](https://starter-quill.mintlify.app), [Prism](https://starter-prism.mintlify.app) @@ -89,7 +82,7 @@ settings. Learn more about the [properties](#properties) or from an type={'"topnav" | "sidenav" | "solidSidenav"'} default="topnav" > - The global layout style of the documentation. + The global layout style of your documentation. @@ -103,7 +96,7 @@ settings. Learn more about the [properties](#properties) or from an - Set a custom background image to be displayed behind every page. + Set a custom background image to display behind every page. - Custom fonts. Apply globally or set different fonts for headings and the body - text. + Configure custom fonts. Apply globally or set different fonts for headings and body text. Example: @@ -130,24 +122,19 @@ Example: - The font family name. Custom fonts and all [Google - Fonts](https://fonts.google.com/) are supported. e.g. "Open Sans", - "Playfair Display" + The font family name. Supports custom fonts and all [Google Fonts](https://fonts.google.com/). Examples: "Open Sans", "Playfair Display" - The font weight. Precise values such as `560` are also supported for - variable fonts. Check under the Styles section for your Google Font for - the available weights. + The font weight. Supports precise values such as `560` for variable fonts. Check the Styles section of your chosen Google Font for available weights. - The URL to the font file. Can be used to specify a font that is not from - Google Fonts. + The URL to the font file. Use this to specify a font that is not from Google Fonts. - The font format. Required if using a custom font source (`url`). + The font format. Required when using a custom font source (`url`). @@ -158,12 +145,11 @@ Example: - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. + Set whether to always show light or dark mode for new users. When not specified, defaults to the user's operating system preference. - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: + Set to `true` to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to use only light or dark mode. Examples: ```json Only Dark Mode @@ -185,624 +171,4 @@ Example: - - Customize the styling of components within the sidebar. - - - - The styling of the navigation item. - - - - - - Styling configurations for the topbar. - - - - The styling of the navigation item. - - - - - - The location options for the search bar. - - - - The location of the search bar. - - - - - - The style of the rounded edges. - - - - The style of the code block. - - - - `auto` will automatically switch between light and dark mode based on the - user's system preferences. - - - - -### Structure - - - An array of groups with all the pages within that group - - - - The name of the group. - - - - The relative paths to the markdown files that will serve as pages. Note: groups are recursive, so to add a sub-folder add another group object in the page array. - - - - The [Fontawesome](https://fontawesome.com/icons) icon for the group. Note: this only applies to sub-folders. - - - - The type of [Fontawesome](https://fontawesome.com/icons) icon. Must be one of: brands, duotone, light, sharp-solid, solid, thin - - - - - - - Array of names and urls of links you want to include in the topbar - - - - The name of the button. - - - - The url once you click on the button. Example: `https://mintlify.com/contact` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided - including the number of GitHub stars. - - - - If type is a link: What the button links to. If type is a github: Link to - the repository to load GitHub information from. - - - - Text inside the button. Only required if type is a link. - - - - The style of the button. - - - - Whether to display the arrow - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - -Versions can be leveraged for localization. You can store translated content -under a version, and once you specify the `locale` any fixed text in Mintlify, -such as 'Was this page helpful?', will automatically be translated based on the -locale. We currently support localization in English, Chinese, Spanish, French, -Japanese, and Portuguese. - - - Localization auto-translates the UI and fixed assets in the docs, such as "Was - this page helpful?". You must translate the content of the pages yourself. - - -For more information, please refer to our -[versioning & localization documentation](/settings/versioning). - -Example: - - - ```json Default - "versions": ["v1.0", "v1.1"] - ``` - - ```json Localization - "versions": [ - { - "name": "English", - "locale": "en", - }, - { - "name": "Español", - "locale": "es" - } - ] - ``` - - - - - - The version name. - - - - The locale of the version. Supported locales are `en`, `cn`, `es`, `fr`, `jp`, `pt`, `pt-BR`, `de`. - - - - Whether the version is the default version. Handy for when you have a "latest" and "stable" version and you want to default to the stable version. - - - - - - - An array of the anchors, includes the icon, color, and url. - -{" "} - - - -{" "} - - - - - - The name of the anchor label. - - Example: `Community` - - - - The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. - - Example: `comments` - - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - - Used if you want to hide an anchor until the correct docs version is selected. - - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - Override the default configurations for the top-most anchor. Note: if you have - tabs configured, this does not apply. - - - - The name of the top-most anchor - - - - Font Awesome icon. - - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - An array of navigational tabs. - -Example: - -```json -"tabs": [ - { - "name": "Writing Content", - "url": "content" - }, - { - "name": "API References", - "url": "api-playground" - } -] -``` - - - - The name of the tab label. - - - - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. - - - - Pass `true` if you want to hide the tab until you directly link someone to docs inside it. - - - - - - - An object to configure the footer with socials and links. - Example: - -```json -"footer": { - "socials": { "x": "https://x.com/mintlify", "website": "https://mintlify.com" }, - "links": [ - { - "title": "Column 1", - "links": [ - { "label": "Column 1 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 1 Link 2", "url": "https://mintlify.com" } - ] - }, - { - "title": "Column 2", - "links": [ - { "label": "Column 2 Link 1", "url": "https://mintlify.com" }, - { "label": "Column 2 Link 2", "url": "https://mintlify.com" } - ] - } - ] -} -``` - - - - One of the following values `website`, `facebook`, `x`, `youtube`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`, `medium`, `telegram`, `twitter` - - Example: `x` - - - - The URL to the social platform. - - Example: `https://x.com/mintlify` - - - - - - - Title of the column - - - - The link items in the column. External urls that starts with `https://` or `http://` will be opened in new tab. - - - - - - - Configurations to enable feedback buttons - - - - Enables a rating system for users to indicate whether the page has been helpful - - - - Enables a button to allow users to suggest edits via pull requests for public repositories. - - - If your docs repo is private, `suggestEdit` will not work. - - - - - Enables a button to allow users to raise an issue about the documentation - - - - - - - Configurations to change the search prompt - - - - Set the prompt for the search bar. Default is `Search...` - - - - -### API Configurations - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground). - - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground) - - - - By default, API playground requests are proxied by Mintlify. This setting can be used to disable this behavior. - - Required for select request types, such as file uploads. - - - - - - Configurations for API requests - - - - Configurations for the auto-generated API request examples - - - - An array of strings that determine the order of the languages of the auto-generated request examples. You can either define custom languages utilizing [x-codeSamples](/api-playground/openapi/advanced-features#x-codesamples) or use our default languages which include `bash`, `python`, `javascript`, `php`, `go`, `java` - - - - - - - - Configurations for the param fields in the API Playground - - - - The default expanded state of expandable options in the API playground. - - `"all"` - every expandable component is expanded - - `"topLevel"` - every top-level expandable component is expanded - - `"topLevelOneOfs"` - every top-level `oneOf` type is expanded - - `"none"` - every expandable component is closed (default behavior) - - - - - - - - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - -Examples: - - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - - ```json Relative - "openapi": "/openapi.json" - ``` - - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` - - - - -### Integrations - - - Configurations to add third-party integrations (excluding analytics integrations) - - - - Enables Intercom widget on docs site. The value should be your Intercom App ID. - - - - Enables Frontchat widget on docs site. The value should be your Frontchat App ID. - - - - - - - Configurations to add third-party analytics integrations. See full list of - supported analytics [here](/integrations/analytics/overview). - - -### Redirects - - - An array of paths you want to configure to permanently redirect to another path - -Example: - -```json -"redirects": [ - { - "source": "/source/path", - "destination": "/destination/path" - } -] -``` - - - - The path that you want to redirect from. - - Example: `/source` - - - - The path that you want to redirect to. - - Example: `/destination` - - - - - -### Search Engine Optimization - - - Settings for Search Engine Optimization. - -Example: - -```json -"seo": { - "indexHiddenPages": true -} -``` - - - - Enables indexing pages not included in `navigation`. - - - - -## Example `mint.json` - -Click on the following dropdown to view a sample configuration file - - - ```json - { - "name": "Mintlify", - "logo": { - "light": "/logo/light.svg", - "dark": "/logo/dark.svg" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#16A34A", - "light": "#4ADE80", - "dark": "#166534" - }, - "topbarLinks": [ - { - "name": "Contact Us", - "url": "mailto:support@mintlify.com" - } - ], - "topbarCtaButton": { - "name": "Get Started", - "url": "https://mintlify.com/start" - }, - "anchors": [ - { - "name": "API Components", - "icon": "rectangle-terminal", - "color": "#f59f0b", - "url": "api-components" - }, - { - "name": "Community", - "icon": "comments", - "color": "#2564eb", - "url": "https://mintlify.com/community" - } - ], - "navigation": [ - { - "group": "Getting Started", - "pages": ["introduction", "quickstart"] - }, - { - "group": "API Components", - "pages": ["api-playground/overview", "api-playground/configuration"] - }, - { - "group": "Settings", - "pages": ["settings/global", "settings/page"] - }, - { - "group": "Analytics", - "pages": ["analytics/posthog"] - } - ], - "footerSocials": { - "github": "https://github.com/mintlify", - "slack": "https://mintlify.com/community", - "x": "https://x.com/mintlify" - }, - "integrations": { - "intercom": "APP_ID", - "frontchat": "CHAT_ID" - } - } - ``` - - -## More Customization - -Learn more about how to further customize your docs with custom CSS and JS in -[Custom Scripts](https://mintlify.com/docs/advanced/custom/). +[Content continues in next part due to length...] \ No newline at end of file diff --git a/settings/navigation.mdx b/settings/navigation.mdx index ec1ab6e76..b9c059f85 100644 --- a/settings/navigation.mdx +++ b/settings/navigation.mdx @@ -1,13 +1,13 @@ --- title: "Navigation" -description: "Organize your docs directory to guide your users to the information they need " +description: "Organize your docs directory to guide your users to the information they need" icon: "map" --- ## Tabs Tabs help distinguish between different topics or sections of your -documentation. They show up above the main sidebar. +documentation. They appear above the main sidebar. @@ -15,8 +15,8 @@ documentation. They show up above the main sidebar. -Configure tabs with the `tabs` field of the `mint.json` file. The `url` field of -the tab object should map to a folder of content added to your sidebar, or an +Configure Tabs with the `tabs` field in your `mint.json` file. The `url` field of +each Tab object should map to either a folder of content added to your sidebar or an external link. ```json @@ -36,9 +36,9 @@ external link. ] ``` -To configure the default `Documentation` primary tab, add the `primaryTab` field -to your `mint.json` file with your desired name. Any files in your navigation -not in a folder reserved by another tab will show up in the primary tab. +To configure the default `Documentation` Primary Tab, add the `primaryTab` field +to your `mint.json` file with your desired name. Any files in your Navigation +that are not in a folder reserved by another Tab will appear in the Primary Tab. ```json "primaryTab": { @@ -48,7 +48,7 @@ not in a folder reserved by another tab will show up in the primary tab. ## Anchors -Anchors provide another way to direct users to sections of your documentation, +Anchors provide another way to direct users to sections of your documentation or link out to external URLs. @@ -57,10 +57,9 @@ or link out to external URLs. -Configure anchors with the `anchors` field of the `mint.json` file. The `url` -field of the tab object should map an external link, or a folder of content -added to your sidebar. More fields for anchors can be found -[here](/settings/global). +Configure Anchors with the `anchors` field in your `mint.json` file. The `url` +field should map to either an external link or a folder of content added to your +sidebar. You can find more fields for Anchors in the [Global Settings](/settings/global). ```json "anchors": [ @@ -82,7 +81,7 @@ added to your sidebar. More fields for anchors can be found ] ``` -To configure the default `Documentation` top anchor, add the `topAnchor` field +To configure the default `Documentation` Top Anchor, add the `topAnchor` field to your `mint.json`. ```json @@ -94,12 +93,12 @@ to your `mint.json`. ## Sidebar -Organize your navigation by defining the `navigation` property in your -mint.json, You don't need to include `.mdx` in page names. For sidebar styling options, see the [global settings page](/settings/global#param-sidebar) +Organize your Navigation by defining the `navigation` property in your +`mint.json`. You don't need to include `.mdx` in page names. For Sidebar styling options, see the [Global Settings](/settings/global#param-sidebar). - Once you add a page to your docs directory, you'll need to add the path to - `mint.json` to add it to the sidebar. Pages do not show up automatically. + After adding a page to your docs directory, you'll need to add its path to + `mint.json` to make it appear in the Sidebar. Pages do not appear automatically. ```json Regular Navigation @@ -113,7 +112,7 @@ mint.json, You don't need to include `.mdx` in page names. For sidebar styling o ### Groups -Create groups by recursively nesting a group within a group. +Create Groups by recursively nesting a Group within another Group. ```json Nested Navigation "navigation": [ @@ -132,15 +131,15 @@ Create groups by recursively nesting a group within a group. ### Folders -Simply put your MDX files in folders and update the paths in `mint.json`. +Simply place your MDX files in folders and update the paths in `mint.json`. -For example, to have a page at `https://yoursite.com/your-folder/your-page` you -would make a folder called `your-folder` containing an MDX file called +For example, to create a page at `https://yoursite.com/your-folder/your-page`, you +would create a folder called `your-folder` containing an MDX file called `your-page.mdx`. - You cannot use `api` for the name of a folder unless you nest it inside - another folder. Mintlify uses Next.js which reserves the top-level `api` + You cannot use `api` as a folder name unless you nest it inside + another folder. Mintlify uses Next.js, which reserves the top-level `api` folder for internal server calls. We recommend using the folder name `api-reference` instead. @@ -174,10 +173,10 @@ would make a folder called `your-folder` containing an MDX file called ### Hidden Pages -MDX files not included in `mint.json` will not show up in the sidebar but are -accessible by linking directly to them. +MDX files not included in `mint.json` will not appear in the Sidebar but are +accessible via direct links. -Hidden pages are not indexed for search within your docs by default. If you +Hidden Pages are not indexed for search within your docs by default. If you would like to override this behavior, you can set the [`seo.indexHiddenPages`](/settings/global#search-engine-optimization) attribute in your `mint.json` to `true`. @@ -186,13 +185,13 @@ in your `mint.json` to `true`. ### Links -Add links to the topbar with the `topbarLinks` field in the `mint.json` file. +Add links to the Topbar with the `topbarLinks` field in your `mint.json` file. -The `topbarLinks` field supports the following fields: `name`, `url`. +The `topbarLinks` field supports the following fields: `name` and `url`. ```json "topbarLinks": [ @@ -205,7 +204,7 @@ The `topbarLinks` field supports the following fields: `name`, `url`. ### CTA Button -Customize the call-to-action (CTA) button in the topbar using the `topbarCtaButton` +Customize the Call-to-Action (CTA) Button in the Topbar using the `topbarCtaButton` field. @@ -223,7 +222,7 @@ The `topbarCtaButton` field supports the following fields: `name`, `url`, `type` #### GitHub -You can also configure the CTA button to link directly to your GitHub +You can also configure the CTA Button to link directly to your GitHub repository. Use the `topbarCtaButton` field with the `type` set to `github`. @@ -235,4 +234,4 @@ repository. Use the `topbarCtaButton` field with the `type` set to `github`. "type": "github", "url": "https://github.com/mintlify/docs" } -``` +``` \ No newline at end of file diff --git a/text.mdx b/text.mdx index 45cec9193..43551e541 100644 --- a/text.mdx +++ b/text.mdx @@ -1,6 +1,6 @@ --- title: "Headers and Text" -description: "Text, title, and styling in standard markdown" +description: "Text, title, and styling in standard Markdown" icon: 'heading' --- @@ -22,13 +22,13 @@ Best used for subsection headers. -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. +Each **title** and **subtitle** creates an anchor and appears in the table of contents on the right. ## Text Formatting -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. +We support most Markdown formatting. Simply add `**`, `_`, or `~` around text to format it. | Style | How to write it | Result | | ------------- | ----------------- | --------------- | @@ -36,9 +36,9 @@ We support most markdown formatting. Simply add `**`, `_`, or `~` around text to | Italic | `_italic_` | _italic_ | | Strikethrough | `~strikethrough~` | ~strikethrough~ | -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. +You can combine these styles. For example, write `**_bold and italic_**` to get **_bold and italic_** text. -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. +For superscript and subscript text, you need to use HTML tags. Add `` or `` around your text. | Text Size | How to write it | Result | | ----------- | ------------------------ | ---------------------- | @@ -47,17 +47,17 @@ You need to use HTML to write superscript and subscript text. That is, add `` in front of a paragraph. @@ -67,7 +67,7 @@ To create a blockquote, add a `>` in front of a paragraph. > Dorothy followed her through many of the beautiful rooms in her castle. ``` -### Multiline +### Multiple Lines > Dorothy followed her through many of the beautiful rooms in her castle. > @@ -81,9 +81,9 @@ To create a blockquote, add a `>` in front of a paragraph. ### LaTeX -Mintlify supports in-line [LaTeX](https://www.latex-project.org) by surrounding your LaTeX code with dollar signs (\$). For example, `$(a^2 + b^2 = c^2)$` will render as $(a^2 + b^2 = c^2)$. +Mintlify supports in-line [LaTeX](https://www.latex-project.org) expressions by surrounding your LaTeX code with dollar signs (\$). For example, `$(a^2 + b^2 = c^2)$` will render as $(a^2 + b^2 = c^2)$. -Equations on their own line can be created with double dollar signs (\$\$): +Create equations on their own line using double dollar signs (\$\$): $$\exists \, x \notin [0,1]$$ @@ -93,7 +93,7 @@ $$\exists \, x \notin [0,1]$$ ### Line Breaks -Markdown syntax also recognizes a double enter in your MDX as a linebreak. +Markdown syntax recognizes two consecutive line breaks (pressing Enter twice) as a paragraph break. ```html
@@ -103,4 +103,4 @@ Markdown syntax also recognizes a double enter in your MDX as a linebreak. Paragraph 1 Paragraph 2 -``` +``` \ No newline at end of file diff --git a/web-editor.mdx b/web-editor.mdx index 0c945d94b..dd0d426a0 100644 --- a/web-editor.mdx +++ b/web-editor.mdx @@ -3,22 +3,22 @@ title: 'Web Editor' description: 'Edit your docs directly from the dashboard with live previews.' --- -Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. +The Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. -The editor includes a few key features to integrate directly into your existing git workflow, +The editor includes key features that integrate directly into your existing Git workflow, like creating branches, pull requests, commits, and diffs for your current changes. It also includes a fully editable experience for changing and adding content directly, even with custom components. -If you understand git workflows and our integrations already, you can skip to [here](#editing-content). +If you understand Git workflows and our integrations already, you can skip to [here](#editing-content). -## Git and update workflows +## Git and Update Workflows -### Git basics +### Git Basics While Web Editor means you don't need to go to GitHub or your command line to make -changes, it's still helpful to know the basics of git. +changes, it's still helpful to know the basics of Git. Git terminology: @@ -28,12 +28,12 @@ Git terminology: - **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version. -- **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. +- **Pull Request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. -### Making updates +### Making Updates -In order to make updates to your docs, we include a few buttons specifically to -integrate with your git workflow. +To make updates to your docs, we include buttons specifically to +integrate with your Git workflow. If you haven't done so already, please install the Mintlify GitHub app to your GitHub account. @@ -43,18 +43,18 @@ integrate with your git workflow. - - In order to make changes to your docs, you might want to change from the main branch + + To make changes to your docs, you might want to change from the main branch to avoid publishing directly to your main docs site. - To do this, you can open the branches modal on the top left of the editor. + To do this, open the Branches modal on the top left of the editor. - From here, you can either switch to a different git branch than `main`, or you can + From here, you can either switch to a different Git branch than `main`, or you can create a new branch by clicking the **"New Branch"** button. @@ -68,19 +68,19 @@ integrate with your git workflow. By default, when you load the page again, you'll default to the main branch. - As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you. + As a best practice, you should always create a new branch to make changes so you can submit a Pull Request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a Pull Request for you. - - In order to make a commit, you have two options, both of which appear on the top + + To make a commit, you have two options, both of which appear on the top right of the editor: - + If you're on the main branch of your docs repository, you can push a commit directly to the repo by clicking the **"Publish"** button. You'll see your changes - reflect in your git branch the next time you run `git pull`. + reflect in your Git branch the next time you run `git pull`. @@ -88,9 +88,9 @@ integrate with your git workflow. - + If you're not on the main branch, you can push a commit to your branch by clicking - on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch + on the **"Save Changes"** button. If you're ready to publish a Pull Request to put your branch up for review, you can click the **"Publish Pull Request"** button. @@ -100,12 +100,12 @@ integrate with your git workflow. - This will create the pull request for you on GitHub using the branch you selected onto + This will create the Pull Request for you on GitHub using the branch you selected onto your main branch. - - If you do put your pull request up for review, you can edit the title and description + + When you submit your Pull Request for review, you can edit the title and description of the PR, but a default Mintlify title will be provided for you if you leave it empty. @@ -116,11 +116,11 @@ integrate with your git workflow. -## Editing content +## Editing Content -### Slash commands +### Slash Commands -The easiest way to add content in the editor is by using **"Slash commands"**, which are +The easiest way to add content in the editor is by using **"Slash Commands"**, which are commands you have access to after typing `/` in the **"Visual Editor"** mode: @@ -128,19 +128,19 @@ commands you have access to after typing `/` in the **"Visual Editor"** mode: -As you type, you'll see more options pop up: +As you type, you'll see more options appear: -#### Content blocks +#### Content Blocks Here are the types of content blocks available to add in the **"Visual Editor"**: - + Paragraph Headings @@ -152,7 +152,7 @@ Here are the types of content blocks available to add in the **"Visual Editor"** - + Callouts Accordions @@ -169,36 +169,36 @@ Here are the types of content blocks available to add in the **"Visual Editor"** -### Adding images +### Adding Images -You can add images to your page by typing `/image` and either clicking on the **"Image"** -option or hitting ↓ + Enter on the **"Image"** option. +To add images to your page, type `/image` and either click on the **"Image"** +option or press ↓ + Enter on the **"Image"** option. -This will open up the image modal where you have the option to either upload a new -image or use an existing image from the repo. +This will open the image modal where you have the option to either upload a new +image or use an existing image from the repository. -Uploading an image can be done through the modal: +You can upload an image through the modal: -And you can preview an existing image before you add it. +You can also preview an existing image before adding it. -### Editing images +### Editing Images -In order to edit images, you just have to hover over the image to see the **"Delete"** +To edit images, hover over the image to see the **"Delete"** and **"Edit"** buttons on the top right of the image. @@ -213,13 +213,13 @@ Clicking the **"Edit"** button lets you edit the attributes of the image. -If you want to update the source of an image to be a new image that you haven't yet -uploaded, you have to first delete the image you're changing, and then add a new one +If you want to update the source of an image to a new image that you haven't yet +uploaded, you must first delete the existing image, then add a new one using the [instructions above](#adding-images). -## Editor modes +## Editor Modes -In order to offer the most flexibility, the editor has three modes: +To offer the most flexibility, the editor has three modes: @@ -229,45 +229,45 @@ In order to offer the most flexibility, the editor has three modes: ### Visual Editor The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion. -It offers you a view into your docs in a fully editable way that reflects what the final +It offers a view into your docs in a fully editable way that reflects what the final page would look like on your main docs site. ### Source Editor -The **"Source Editor"** offers you a way to edit your MDX files in code, the same way -you'd do in your IDE. This offers less flexibility, in that our components aren't available -for auto-complete, but it does have two unique advantages. +The **"Source Editor"** offers a way to edit your MDX files in code, the same way +you'd do in your IDE. This offers less flexibility since our components aren't available +for auto-complete, but it does have two unique advantages: 1. It allows you to edit props of components (see our [limitations below](#current-limitations)) -which is currently not available in **"Visual Editor"** mode yet. +which is currently not available in **"Visual Editor"** mode. -2. It allows you to correct syntax errors which might've appeared in your repo that -might not be compatible with **"Visual Editor"** mode until you've fixed them. +2. It allows you to correct syntax errors which might have appeared in your repository that +might not be compatible with **"Visual Editor"** mode until fixed. ### Diff View -The **"Diff View"** is a way to view the changes made to a specific document before +The **"Diff View"** lets you view the changes made to a specific document before committing it to your repository. -This will help you see changes you've made along with formatting changes made by +This helps you see changes you've made along with formatting changes made by the editor. -## Current limitations +## Current Limitations -We do have a few current limitations in the editor that we're working to resolve. +We do have a few current limitations in the editor that we're working to resolve: - + You currently cannot live-update your navigation based on added/edited files. You still have to manually edit renamed, added, and deleted files in your `mint.json` - + We currently don't show any previews for custom snippets. This is on our roadmap to support as fully editable components. - + We currently don't show any previews for OpenAPI specs. This is on our roadmap to support as a read-only preview.