diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 7c4d2a896..c30137ea0 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -1,11 +1,76 @@ --- -title: 'Playground' -description: 'Enable users to interact with your API' +title: 'API Playground' +description: 'Try out API endpoints directly in the documentation' openapi: 'POST /project/update/{projectId}' hideApiMarker: true icon: 'play' --- -The API playground is an interactive environment to make requests and preview an API endpoint. +The API playground lets you test API endpoints right from the documentation without writing any code. Think of it as a built-in Postman that's always ready to go. -This page is automatically generated from the OpenAPI specification. \ No newline at end of file +## How It Works + + + + Browse through the documentation to find the API endpoint you want to test. Each endpoint will have an interactive playground section. + + + + The playground automatically shows all the required fields you need to fill in: + - Path parameters (like IDs in the URL) + - Query parameters + - Request body fields + + + Required fields are marked with a red asterisk (*) + + + + + Click the "Try It" button to make a real API call. You'll see: + - The complete request that was sent + - The response you got back + - Response status code + - Response headers + + + +## Example Usage + +Here's what you'll typically see in the playground: + + + API Playground Example + + + + You can switch between different authentication methods and add custom headers if needed. + + +## Features + + + + Your API key is automatically included when you're logged in. + + + + Get instant responses from the API to verify your parameters. + + + + See example code snippets in multiple programming languages. + + + + Clear error messages help you troubleshoot failed requests. + + + +## Automatic Generation + +The playground is automatically generated from our OpenAPI specification, ensuring it's always up to date with the latest API changes. + + + Can't see the playground for an endpoint? Make sure the endpoint is properly defined in the OpenAPI specification. + \ No newline at end of file diff --git a/core-concepts/navigation.mdx b/core-concepts/navigation.mdx index 7f1518746..6fc10d142 100644 --- a/core-concepts/navigation.mdx +++ b/core-concepts/navigation.mdx @@ -1,6 +1,6 @@ --- title: "Navigation" -description: "Structure and customize your documentation's navigation hierarchy" +description: "Learn how to structure your documentation's navigation" icon: "map" --- @@ -10,224 +10,93 @@ export const LayoutFrame = ({ children }) => ( ) -The [navigation](/core-concepts/settings#param-navigation) property in [docs.json](/core-concepts/settings) defines how users will browse through your documentation. Think of it as the blueprint for your documentation's menu structure. - -With proper navigation configuration, you can organize your content into a logical hierarchy that makes it easy for users to find exactly what they're looking for. + + Navigation is configured in the `navigation` property of your `docs.json` file. Think of it as the table of contents for your documentation. + + +## Navigation Basics + +Your documentation can use any combination of these navigation elements: + + + + Individual documentation pages + + + Collections of related pages + + + Separate sections of documentation + + + Top-level navigation sections + + -## Pages +## Pages - The Building Blocks -Pages are the most fundamental navigation component. +Pages are your individual documentation files. They're the simplest form of navigation. -Pages is an array where each entry must be a reference to the path of a [page file](/core-concepts/pages). - -```json +```json Simple Pages Example { "navigation": { "pages": [ "overview", "quickstart", - "advanced/components", - "advanced/integrations" + "advanced/components" ] } } ``` ---- + + The paths in the `pages` array should match your file structure. For example, `"advanced/components"` points to `advanced/components.mdx`. + -## Groups +## Groups - Organize Related Content -Groups allow you to group your pages. Groups can also be nested within each other. +Groups help you organize related pages together. You can even nest groups within groups. -```json + + +```json Simple Groups { "navigation": { "groups": [ { "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Editing", - "pages": ["installation", "editor"] - } - ] + "pages": ["overview", "quickstart"] }, { - "group": "Writing Content", - "pages": ["writing-content/page", "writing-content/text"] + "group": "Features", + "pages": ["features/auth", "features/api"] } ] } } ``` ---- - -## Tabs - -Tabs help distinguish between different topics or sections of your -documentation. - - - - - - -```json -"navigation": { - "tabs": [ - { - "tab": "API References", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - }, - { - "tab": "SDKs", - "pages": [ - "sdk/fetch", - "sdk/create", - "sdk/delete", - ] - }, - { - "tab": "Blog", - "href": "https://external-link.com/blog" - } - ] -} -``` - ---- - -## Anchors - -Anchors are another way to section your content. They show up on top of your side navigation. - - - - - - -The configuration is very similar to tabs. - -While not required, we highly recommend that you set an `icon` field as well. - -```json -"navigation": { - "anchors": [ - { - "anchor": "Documentation", - "icon": "book-open", - "pages": [ - "quickstart", - "development", - "navigation" - ] - }, - { - "anchor": "API References", - "icon": "sqaure-terminal", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - }, - { - "anchor": "Blog", - "href": "https://external-link.com/blog" - } - ] -} -``` - ---- - -## Dropdowns - -Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown. - - - - - - -While not required, we also recommend that you set an icon for each dropdown item. - -```json -"navigation": { - "dropdowns": [ - { - "dropdown": "Documentation", - "icon": "book-open", - "pages": [ - "quickstart", - "development", - "navigation" - ] - } - { - "dropdown": "API References", - "icon": "sqaure-terminal", - "pages": [ - "api-reference/get", - "api-reference/post", - "api-reference/delete" - ] - } - { - "dropdown": "Blog", - "href": "https://external-link.com/blog" - } - ] -} -``` - ---- - - -## Versions - -Versions can be leveraged to partition your navigation into different versions. - - - - - - -```json +```json Nested Groups { "navigation": { - "versions": [ - { - "version": "1.0.0", - "groups": [ - { - "group": "Getting Started", - "pages": ["v1/overview", "v1/quickstart", "v1/development"] - } - ] - }, + "groups": [ { - "version": "2.0.0", - "groups": [ + "group": "Getting Started", + "pages": [ + "quickstart", { - "group": "Getting Started", - "pages": ["v2/overview", "v2/quickstart", "v2/development"] + "group": "Setup", + "pages": ["installation", "configuration"] } ] } @@ -236,187 +105,155 @@ Versions can be leveraged to partition your navigation into different versions. } ``` ---- + -## Languages +## Tabs - Section Your Content -Languages can be leveraged to partition your navigation into different languages. +Tabs help separate different types of content, like API documentation from guides. - - + + -We currently support the following languages: - - -} horizontal /> -} horizontal/> -} horizontal/> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> -} horizontal /> - - ```json { "navigation": { - "languages": [ + "tabs": [ { - "language": "en", - "groups": [ - { - "group": "Getting Started", - "pages": ["en/overview", "en/quickstart", "en/development"] - } - ] + "tab": "Guides", + "pages": ["getting-started", "tutorials"] }, { - "language": "es", - "groups": [ - { - "group": "Getting Started", - "pages": ["es/overview", "es/quickstart", "es/development"] - } - ] + "tab": "API Reference", + "pages": ["api/authentication", "api/endpoints"] } ] } } ``` ---- - -## Nesting + + You can link to external content using `href` instead of `pages`: + ```json + { + "tab": "Blog", + "href": "https://your-blog.com" + } + ``` + -It's important to note that you can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably. +## Anchors - Top-Level Navigation -This way, you can create a very complex navigation structure that is easy to manage. +Anchors appear at the top of your sidebar and help organize broad categories of content. - + + + + -```json Anchors +```json { "navigation": { "anchors": [ { - "anchor": "Anchor 1", - "groups": [ - { - "group": "Group 1", - "pages": [ - "some-folder/file-1", - "another-folder/file-2" - "just-a-file" - ] - } - ] - } + "anchor": "Documentation", + "icon": "book-open", + "pages": ["quickstart", "guides"] + }, { - "anchor": "Anchor 2", - "groups": [ - { - "group": "Group 2", - "pages": [ - "some-other-folder/file-1", - "various-different-folders/file-2", - "another-file" - ] - } - ] + "anchor": "API", + "icon": "code", + "pages": ["api/overview", "api/endpoints"] } ] } } ``` -```json Tabs -{ - "navigation": { - "tabs": [ - { - "tab": "Tab 1", - "groups": [ + + Adding icons to your anchors helps users quickly identify different sections. Use any [Font Awesome](https://fontawesome.com/icons) icon name in the `icon` field. + + +## Advanced Features + + + + Dropdowns consolidate multiple anchors into a single menu: + ```json + { + "navigation": { + "dropdowns": [ { - "group": "Group 1", - "pages": [ - "some-folder/file-1", - "another-folder/file-2" - "just-a-file" - ] + "dropdown": "Resources", + "icon": "book", + "pages": ["guides", "tutorials", "examples"] } ] } - { - "tab": "Tab 2", - "groups": [ + } + ``` + + + + Support multiple versions of your documentation: + ```json + { + "navigation": { + "versions": [ + { + "version": "v2.0", + "pages": ["v2/overview", "v2/features"] + }, { - "group": "Group 2", - "pages": [ - "some-other-folder/file-1", - "various-different-folders/file-2", - "another-file" - ] + "version": "v1.0", + "pages": ["v1/overview", "v1/features"] } ] } - ] - } -} -``` - + } + ``` + -```json Tabs with external anchors -{ - "navigation": { - "tabs": [ - { - "tab": "Tab 1", - "global": { - "anchors": [ - { - "anchor": "Anchor 1", - "href": "https://mintlify.com/docs" - } - ] - }, - "groups": [ + + Organize content by language: + ```json + { + "navigation": { + "languages": [ { - "group": "Group 1", - "pages": [ - "some-folder/file-1", - "another-folder/file-2" - "just-a-file" - ] - } - ] - } - { - "tab": "Tab 2", - "groups": [ + "language": "en", + "pages": ["en/start", "en/guide"] + }, { - "group": "Group 2", - "pages": [ - "some-other-folder/file-1", - "various-different-folders/file-2", - "another-file" - ] + "language": "es", + "pages": ["es/start", "es/guide"] } ] } - ] - } -} -``` - + } + ``` + + + + + Remember: You can combine any of these navigation elements to create the perfect structure for your documentation. Start simple and add complexity as needed. + + +## Supported Languages + +We support the following languages for internationalization: + + + } >en + } >es + } >fr + } >de + } >cn, zh-Hant + } >jp + } >ko + } >pt, pt-BR + } >ru + - \ No newline at end of file +Additional languages include Arabic (ar), Indonesian (id), Italian (it), and Turkish (tr). \ No newline at end of file diff --git a/core-concepts/pages.mdx b/core-concepts/pages.mdx index e659581e3..e2be41058 100644 --- a/core-concepts/pages.mdx +++ b/core-concepts/pages.mdx @@ -4,162 +4,142 @@ description: "Pages are the building blocks of your documentation" icon: 'letter-text' --- -## Basics - -Each page is an MDX file that should begin with `---` at the start and end. This is used to define the page's metadata, such as the title and description. - -For example, you can define the title for this page as follows. - -```jsx ---- -title: "Your title goes here" ---- -``` - -## Descriptions - -You can add a description that shows the summary of the page under the title with the `description` metadata. - -```jsx ---- -description: "Your description goes here" ---- -``` - -## Sidebar Title - -If you want to show a different title in the navigation, you can set the `sidebarTitle` metadata. This is useful if your title is long and you want something shorter in the navigation links. - -```jsx ---- -title: "Your very long page title you want to shorten" -sidebarTitle: "Short title" ---- -``` - -## Icons - -You can set an icon for your sidebar item like the one for this page. You can set icons by using the `icon` metadata. - -```jsx ---- -title: "Code Block" -icon: "code" ---- -``` - -You can set icons from [Font Awesome](https://fontawesome.com/icons) and [Lucide](https://lucide.dev/icons), depending on the [icon library setting](http://localhost:3000/core-concepts/settings#param-icons). - -You can also set the icon type for Font Awesome icons (optional). If not set, the icon type will be regular. - -```jsx ---- -iconType: "solid" ---- -``` - -## API Pages - -API pages let you build interactive API playgrounds. To create an API page, you -must set an `api` or `openapi` property in the page metadata. - -Learn more about API pages by visiting the [API page guides](/api-playground/overview). - -```jsx ---- -openapi: "GET /endpoint" ---- -``` - -## Page Mode - -The Page Mode setting allows you to customize the appearance of your page. You can choose from -different modes to adjust the layout according to your needs. If no mode is specified, the page -will use the default settings. - -### Default - -If no specific mode is given, the page will default to standard settings. This means the page -will display the default table of contents and other standard elements. - -```jsx ---- -title: "Default page title" ---- -``` - -### Wide Mode - -In Wide Mode, you can hide the table of contents (ToC) on the right side of the page. This is -particularly useful if your page doesn’t have any headings or if you prefer to utilize the -extra horizontal space for more content. - -```jsx ---- -mode: "wide" ---- -``` - -### Custom Mode - -Custom Mode provides a minimalist layout by removing all elements except for the top bar. -This mode offers a blank canvas, which is ideal for creating a "landing page" or any page where -you want a clean, distraction-free environment. - - -```jsx ---- -mode: "custom" + + Every page in your documentation is an MDX file. MDX lets you use React components alongside Markdown, giving you the best of both worlds! + + +## Page Metadata + +Every page starts with metadata between `---` markers. This tells Mintlify how to display your page. + + + ```mdx Basic Example + --- + title: "Getting Started" + description: "Learn how to use our platform in 5 minutes" + --- + ``` + + ```mdx With Icon + --- + title: "API Reference" + description: "Detailed API documentation" + icon: "code" + --- + ``` + + +### Essential Metadata Fields + + + The main title of your page - appears at the top and in navigation + + + + A brief summary that appears under the title and helps with SEO + + + + Add a visual element from [Font Awesome](https://fontawesome.com/icons) or [Lucide](https://lucide.dev/icons) + + + + Use `sidebarTitle` to show a shorter title in the navigation while keeping your full title on the page. + + +## Page Layouts + +Choose from different layout modes to best present your content. + + + + Standard layout with table of contents + ```mdx + --- + title: "Your Page" + --- + ``` + + + + Hides table of contents for more content space + ```mdx + --- + mode: "wide" + --- + ``` + + + + Minimal layout with just the top bar + ```mdx + --- + mode: "custom" + --- + ``` + + + + Centered content without sidebars + ```mdx + --- + mode: "center" + --- + ``` + + + +## API Documentation + + + Create interactive API documentation by adding the `openapi` or `api` property to your page metadata. + + +```mdx +--- +title: "Create User" +openapi: "POST /users" --- ``` -### Center Mode +Learn more about building API documentation in our [API Playground Guide](/api-playground/overview). -Center Mode removes the sidebar and the table of contents, and centers the page content. This mode is great for changelogs -or any page where you want to focus on the content. +## Improving Discoverability +### External Links -```jsx ---- -mode: "center" ---- -``` - -## External Links +Link to external resources directly from your sidebar: -If you want the sidebar to open an external URL, you can set the `url` metadata -in any page. - -```jsx +```mdx --- -title: "Page that goes to external link" +title: "npm Package" url: "https://www.npmjs.com/package/mintlify" --- ``` -## Search Engine Optimization - -You can set meta tags like the image set when shared on social media by passing -them into your page's metadata. +### Search Optimization -Note that meta tags with colons need to be wrapped in quotes. +Help users find your content by adding keywords: -```jsx +```mdx --- -"twitter:image": "/images/your-photo.jpg" +title: "Authentication" +keywords: ['login', 'signup', 'security', 'auth'] --- ``` -See [SEO](/settings/seo) to learn more about SEO metadata. +### Social Sharing -## Internal Search Optimization +Customize how your page appears when shared on social media: -You can also enhance a specific page's discoverability in the built-in search by -providing `keywords` in your metadata. These keywords won't appear as part of the page -content or in search results, but users that search for them will be shown the page as a result. - -```jsx +```mdx --- -keywords: ['search', 'indexing'] +title: "Product Features" +"twitter:image": "/images/features-preview.jpg" +"og:description": "Discover our powerful features" --- ``` + + + Remember to wrap metadata values containing colons (like social media tags) in quotes! + \ No newline at end of file diff --git a/docs.json b/docs.json index 9953d0fd1..5026a79c1 100644 --- a/docs.json +++ b/docs.json @@ -24,7 +24,9 @@ "index", "quickstart", "installation", - "editor" + "editor", + "text", + "quickstart" ] }, { @@ -35,7 +37,9 @@ "core-concepts/navigation", "core-concepts/themes", "core-concepts/react-components", - "core-concepts/ai-ingestion" + "core-concepts/ai-ingestion", + "core-concepts/pages", + "core-concepts/navigation" ] }, { @@ -92,7 +96,8 @@ "api-playground/mdx/authentication" ] }, - "api-playground/troubleshooting" + "api-playground/troubleshooting", + "api-playground/overview" ] }, { diff --git a/quickstart.mdx b/quickstart.mdx index f7f2a5f53..aa18c0f20 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,241 +1,182 @@ --- title: "Quickstart" -description: "Deploy your documentation in minutes" +description: "Start your documentation site in 5 minutes" icon: "rocket" --- -This quickstart guide will walk you through the process of setting up and deploying your documentation site in just a few minutes. - -By the end of this guide, you'll have a live documentation site that's ready to customize and expand. - - - -**Prerequisites**: Before you begin, make sure to [create an account](https://mintlify.com/start) and complete onboarding. - - - -## Getting Started - -Once you've completed the onboarding process, your documentation site will be automatically deployed to a unique URL with the following format. - -``` -https://.mintlify.app -``` - -You can find your URL from the Overview page of the dashboard. - - - Mintlify Domain - Mintlify Domain - - -This URL is instantly available and will update whenever you make changes to your documentation. It's perfect for testing and sharing with your team during development. - -## Development Workflows - -Mintlify offers two different workflows for creating and maintaining your documentation. - - - For developers who prefer working with their existing tools. Click to jump to section. - - - - For those who prefer a visual interface. Click to jump to section. - - -## Code-Based Workflow - -The code-based workflow integrates with your existing development environment and Git repositories, making it ideal for technical teams who want to manage documentation alongside their code. - -### Install the CLI - -To work locally with your documentation, install the Mintlify Command Line Interface (CLI) by running the following command in your terminal: - - - -```bash npm -npm install -g mintlify -``` - - -```bash yarn -yarn global add mintlify -``` - - -```bash pnpm -pnpm add -g mintlify -``` - - - - - You need Node.js version 19 or higher installed on your machine. If you encounter installation issues, check the troubleshooting guide. - - -### Install the GitHub App - -Mintlify provides a GitHub App that automates the deployment process when you push changes to your repository. - -You can install the GitHub App by following the instructions from the onboarding checklist or by navigating to `Settings` > `Organization` > `GitHub`. - -Click `Install GitHub App`. Select the repositories you want to connect. - - - GitHub App Installation - GitHub App Installation - - - - Remember to update the GitHub App permissions if you move the documentation to a different repository. - - -### Edit the Documentation - -Now that your environment is set up, you can start editing your documentation files. As an example, let's update the title of the introduction page: - -Open your repository created during onboarding, find the `introduction.mdx` file, and find the top of the file, that should look like this: - -```jsx introduction.mdx ---- -title: "Introduction" -description: "This is the introduction to the documentation" ---- -``` - -Update the `title` field to `"Hello World"`. - -```jsx introduction.mdx {2} ---- -title: "Hello World" -description: "This is the introduction to the documentation" ---- -``` - -### Preview the Changes - -To preview the changes locally, run the following command. - -```bash -mintlify dev -``` - -Your preview will be available at `localhost:3000`. - - - Mintlify Dev - Mintlify Dev - - -### Push the Changes - -When you're ready to publish your changes, simply push the changes to your repository. - -Mintlify will automatically detect the changes, build your documentation, and deploy the updates to your site. You can monitor the deployment status in your GitHub repository's commit history or the [dashboard](https://dashboard.mintlify.com). - -Once the deployment is complete, your last update will be available at `.mintlify.app`. - - - Optionally skip the web editor workflow and jump to adding a custom domain. - - -## Web Editor Workflow - -The web editor workflow provides a WYSIWYG interface for creating and editing documentation without requiring local development tools. It's ideal for non-technical team members or for making quick updates. - -### Access the Web Editor - -Log in to your Mintlify Dashboard and select your project. Navigate to `Editor` on the left sidebar to open the web editor. - - - If you haven't installed the GitHub App, you will be prompted to do so upon opening the web editor. - - - - Web Editor - Web Editor - - -### Edit the Documentation - -In the web editor, you can navigate your documentation files in the sidebar. Let's update the introduction page. - -Find and click on `introduction.mdx` in the file explorer. - -Then, in the visual editor, update the title field to "Hello World". - - - Editing in Web Editor - Editing in Web Editor - - - - The editor provides a rich set of formatting tools and components. Access them by typing "/" in the editor to open the command menu. - - -### Publish Your Changes - -When you're satisfied with your edits, click the `Publish` button in the top-right corner. - -Your changes will be deployed immediately to your documentation site. - -For more details about using the web editor, including advanced features like slash commands and image uploads, see our [Web Editor documentation](/editor). - -## Adding a Custom Domain - -While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation. - -To add a custom domain, go to `Settings` > `Custom Domain` from the dashboard. - - - Custom Domain - Custom Domain - - -Enter your domain (e.g., docs.yourcompany.com) and follow the provided instructions to configure DNS settings with your domain provider. +Welcome! This guide will help you create and deploy your documentation site in just a few simple steps. + + + + First, [create a Mintlify account](https://mintlify.com/start) and complete the onboarding process. + + Once finished, you'll get a preview URL that looks like this: + ``` + https://.mintlify.app + ``` + + + + Mintlify offers two ways to manage your documentation: + + + + Perfect for developers who want to work in their local environment + + + Great for teams who prefer a visual interface + + + + + +## Option 1: Code Editor + + + + Open your terminal and run: + + + ```bash npm + npm i -g mintlify + ``` + + ```bash yarn + yarn global add mintlify + ``` + + ```bash pnpm + pnpm add -g mintlify + ``` + + + + Need Node.js version 19 or higher? [Download it here](https://nodejs.org/en). + + + + + Install our GitHub App to enable automatic deployments: + + 1. Go to `Settings` > `Organization` > `GitHub` in your dashboard + 2. Click `Install GitHub App` + 3. Select the repository you want to connect + + + GitHub App Installation + GitHub App Installation + + + + + Let's update your introduction page: + + 1. Find `introduction.mdx` in your repository + 2. Change the title at the top: + + ```mdx + --- + title: "Hello World" + description: "Welcome to my docs!" + --- + ``` + + + + Run this command to see your changes: + + ```bash + mintlify dev + ``` + + Visit `localhost:3000` in your browser. + + + + Simply push your changes to GitHub. That's it! Your site will automatically update. + + + +## Option 2: Web Editor + + + + 1. Log in to your [Mintlify Dashboard](https://dashboard.mintlify.com) + 2. Select your project + 3. Click `Editor` in the sidebar + + + Web Editor + Web Editor + + + + + 1. Find your file in the sidebar + 2. Make your edits in the visual editor + 3. Click `Publish` when ready + + + Type `/` in the editor to see all available components and formatting options! + + + + +## Add Your Domain (Optional) + +Want to use your own domain like `docs.yourcompany.com`? + +1. Go to `Settings` > `Custom Domain` +2. Enter your domain +3. Add this DNS record with your provider: -| Record Type | Name | Value | TTL | -|-------------|------|-------|-----| -| CNAME | docs (or subdomain) | cname.mintlify.app | 3600 | + | Record Type | Name | Value | TTL | + |-------------|------|-------|-----| + | CNAME | docs | cname.mintlify.app | 3600 |
- - DNS changes can take up to 48 hours to propagate, though they often complete much sooner. - + + DNS changes can take up to 48 hours to take effect. + ## Next Steps -Congratulations! You've successfully deployed your documentation site with Mintlify. Here are some suggested next steps to enhance your documentation: - - - Learn how to customize colors, fonts, and the overall appearance of your documentation site. - - - Structure your documentation with intuitive navigation to help users find what they need. - - - Enhance your documentation with interactive components like accordions, tabs, and code samples. - - - Create interactive API references with OpenAPI and AsyncAPI specifications. - - -## Troubleshooting - -If you encounter any issues during the setup process, check our common troubleshooting solutions: +You're all set! Here are some ways to make your docs even better: + + + + Customize colors, fonts, and the overall look + + + Create an intuitive structure for your content + + + Add interactive elements like tabs and accordions + + + Document your APIs with interactive examples + + + +## Need Help? - Make sure you have Node.js v19+ installed and that you're running the `mintlify dev` command from the directory containing your `docs.json` file. + 1. Check that Node.js v19+ is installed + 2. Make sure you're in the right directory + 3. Try running `mintlify dev` again - - Deployment can take upwards to a few minutes. Check your GitHub Actions (for code-based workflow) or deployment logs in the Mintlify dashboard to ensure there are no build errors. + + Deployments take a few minutes. Check your: + - GitHub Actions (for code editor) + - Dashboard deployment logs (for web editor) - - Verify that your DNS records are set up correctly and allow sufficient time for DNS propagation (up to 48 hours). You can use tools like [DNSChecker](https://dnschecker.org) to verify your CNAME record. + + 1. Verify your DNS settings + 2. Wait for DNS propagation (up to 48 hours) + 3. Use [DNSChecker](https://dnschecker.org) to confirm - -Need more help? [Contact our Support Team](mailto:support@mintlify.com). \ No newline at end of file +Still stuck? [Email our support team](mailto:support@mintlify.com) for help! \ No newline at end of file diff --git a/text.mdx b/text.mdx index e72d532ea..c57498c41 100644 --- a/text.mdx +++ b/text.mdx @@ -1,104 +1,111 @@ --- title: "Headers and Text" -description: "Text, title, and styling in standard markdown" +description: "A guide to text formatting and styling in markdown" icon: 'heading' --- -## Titles +## Basic Text Formatting -Best used for section headers. +Format your text using simple markdown syntax: -```md -## Titles -``` + + + Write `**bold**` to get **bold** text + + + + Write `_italic_` to get _italic_ text + + + + Write `~strikethrough~` to get ~strikethrough~ text + + -### Subtitles + + Combine formats like `**_bold and italic_**` to get **_bold and italic_** text + -Best used for subsection headers. +## Headers + +Structure your content with headers: ```md -### Subtitles +## Level 2 Header (Section) +### Level 3 Header (Subsection) +#### Level 4 Header (Topic) ``` - Titles and subtitles create anchors and also show up on the table of contents on the right. + Headers automatically create anchors and appear in the table of contents -## Text Formatting - -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. - -| Style | How to write it | Result | -| ------------- | ----------------- | --------------- | -| Bold | `**bold**` | **bold** | -| Italic | `_italic_` | _italic_ | -| Strikethrough | `~strikethrough~` | ~strikethrough~ | - -You can combine these. 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. - -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | - -## Linking to Pages - -You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). - -Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/content/text)` links to the page "Text" in our components section. - -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. - -You can validate broken links in your docs with [our CLI](/installation). - -## Blockquotes - -### Singleline - -To create a blockquote, add a `>` in front of a paragraph. - -> Dorothy followed her through many of the beautiful rooms in her castle. +## Links +### Internal Links +Link to other pages in your documentation using root-relative paths: ```md -> Dorothy followed her through many of the beautiful rooms in her castle. +[Getting Started](/getting-started) ``` -### Multiline - -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. + + Avoid relative paths like `../page` - they load slower and are harder to maintain + +### External Links +Link to external websites: ```md -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. +[Visit our website](https://example.com) ``` -### LaTeX +## Special Text + +### Superscript and Subscript +Use HTML tags for special text positioning: -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)$. + +```md Superscript +Text with superscript +``` -Equations on their own line can be created with double dollar signs (\$\$): +```md Subscript +Text with subscript +``` + -$$\exists \, x \notin [0,1]$$ +### LaTeX Support +Add mathematical equations using LaTeX: +- Inline equations: `$E = mc^2$` renders as $E = mc^2$ +- Block equations: ```md -$$\exists \, x \notin [0,1]$$ +$$ +\sum_{i=1}^{n} x_i = x_1 + x_2 + ... + x_n +$$ ``` -### Line Breaks +## Block Elements -Markdown syntax also recognizes a double enter in your MDX as a linebreak. +### Blockquotes +Add quotes or callouts using `>`: -```html -
+ +```md Single Line +> A single line blockquote ``` -```md -Paragraph 1 - -Paragraph 2 +```md Multiple Lines +> First line of the quote +> +> Second line of the quote ``` + + +### Line Breaks +Create space between paragraphs using: +- Double line break (preferred) +- HTML `
` tag + + + Use double line breaks for better readability in your markdown source + \ No newline at end of file