diff --git a/api-playground/adding-sdk-examples.mdx b/api-playground/adding-sdk-examples.mdx index 48cd6faf7..5be6b73de 100644 --- a/api-playground/adding-sdk-examples.mdx +++ b/api-playground/adding-sdk-examples.mdx @@ -6,6 +6,8 @@ keywords: ["x-codeSamples", "SDK examples"] If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages. +SDK examples appear alongside the default cURL examples in your API playground, making it easier for developers to integrate with your API using their preferred language or framework. + This property can be added to any request method and has the following schema. @@ -48,3 +50,96 @@ paths: planter.list({ potted: true }); ``` +## Multiple SDK languages + +You can provide examples in multiple programming languages to support different developer audiences. Common languages include: + + + +```yaml Python example +x-codeSamples: + - lang: python + label: Get user by ID + source: | + import requests + + response = requests.get( + 'https://api.example.com/users/123', + headers={'Authorization': 'Bearer YOUR_TOKEN'} + ) + user = response.json() +``` + +```yaml JavaScript example +x-codeSamples: + - lang: javascript + label: Get user by ID + source: | + const response = await fetch('https://api.example.com/users/123', { + headers: { + 'Authorization': 'Bearer YOUR_TOKEN' + } + }); + const user = await response.json(); +``` + +```yaml Go example +x-codeSamples: + - lang: go + label: Get user by ID + source: | + client := &http.Client{} + req, _ := http.NewRequest("GET", "https://api.example.com/users/123", nil) + req.Header.Add("Authorization", "Bearer YOUR_TOKEN") + resp, _ := client.Do(req) +``` + +```yaml Ruby example +x-codeSamples: + - lang: ruby + label: Get user by ID + source: | + require 'net/http' + require 'json' + + uri = URI('https://api.example.com/users/123') + req = Net::HTTP::Get.new(uri) + req['Authorization'] = 'Bearer YOUR_TOKEN' + response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| + http.request(req) + end + user = JSON.parse(response.body) +``` + + + +## Best practices + + + + Provide examples that reflect actual use cases rather than placeholder code. Include error handling and common patterns your users will need. + + + + Focus on the essential code needed to make the API call. Avoid unnecessary boilerplate that distracts from the core functionality. + + + + If you provide official SDKs, ensure the examples match your SDK's actual API and conventions. Keep examples updated when your SDK changes. + + + + Show how to properly authenticate requests in each language, as authentication patterns vary significantly across SDKs. + + + + Use descriptive labels when providing multiple examples for the same endpoint to help users find the right example quickly. + + + +## Related resources + + + Configure OpenAPI specifications and generate API documentation + + diff --git a/create/code.mdx b/create/code.mdx index 62c6bdc30..bc972d590 100644 --- a/create/code.mdx +++ b/create/code.mdx @@ -8,6 +8,10 @@ keywords: ["code blocks", "syntax highlighting", "code styling"] You can add inline code snippets or code blocks. Code blocks support meta options for syntax highlighting, titles, line highlighting, icons, and more. + + Format text, create headers, and style content + + ### Inline code To denote a `word` or `phrase` as code, enclose it in backticks (\`). diff --git a/create/text.mdx b/create/text.mdx index b6947758c..4bfff4244 100644 --- a/create/text.mdx +++ b/create/text.mdx @@ -8,6 +8,10 @@ keywords: ["Markdown formatting", "text styling", "headers", "anchor links"] Headers organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation. + + Display and style inline code and code blocks + + ### Creating headers Use `#` symbols to create headers of different levels: diff --git a/deploy/ci.mdx b/deploy/ci.mdx index 0c53a8509..752949e3c 100644 --- a/deploy/ci.mdx +++ b/deploy/ci.mdx @@ -10,6 +10,10 @@ keywords: ["continuous integration", "CI/CD", "checks", "Vale", "linter"] Use CI checks to lint your docs for errors and provide warnings before you deploy. Mintlify CI checks run on pull requests against a configured deployment branch. + + Connect to a GitHub repository for automated deployments and pull request previews + + ## Installation To begin, follow the steps on the [GitHub](/deploy/github) page. diff --git a/deploy/github.mdx b/deploy/github.mdx index 1aa7a99a1..2014ca8de 100644 --- a/deploy/github.mdx +++ b/deploy/github.mdx @@ -15,6 +15,10 @@ Mintlify uses a GitHub App to automatically sync your documentation with your Gi See your repository in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard. + + Deploy from CI/CD pipelines with GitHub Actions, GitLab CI, and more + + If your repository is in the `mintlify-community` organization, the GitHub App is automatically configured and managed by Mintlify. You can use the web editor to make changes to your documentation. If you want to work on your documentation locally, clone the repository to your own organization and update your Git settings to use your own repository. ## Install the GitHub App diff --git a/docs.json b/docs.json index 9201726c3..6c8444666 100644 --- a/docs.json +++ b/docs.json @@ -228,7 +228,8 @@ "group": "Overview", "icon": "book-open", "pages": [ - "guides/index" + "guides/index", + "guides/common-tasks" ] }, { diff --git a/guides/common-tasks.mdx b/guides/common-tasks.mdx new file mode 100644 index 000000000..6924ecac2 --- /dev/null +++ b/guides/common-tasks.mdx @@ -0,0 +1,177 @@ +--- +title: "Common tasks" +description: "Quick reference for frequently performed documentation tasks." +keywords: ["quick reference", "common tasks", "how-to", "getting started"] +--- + +This page provides quick links to common documentation tasks. Use this as a starting point to find the information you need quickly. + +## Getting started + + + + Set up your documentation and create your first page + + + Install the Mintlify CLI for local development + + + Select and customize your documentation theme + + + Set up your documentation structure and navigation + + + +## Content creation + + + + Learn Markdown formatting, headers, and links + + + Display code with syntax highlighting and options + + + Add interactive components like accordions and tabs + + + Highlight important information with callouts + + + +## Organization + + + + Set titles, descriptions, and frontmatter + + + Structure content with navigation groups + + + Create separate documentation sections with tabs + + + Customize global documentation settings + + + +## API documentation + + + + Generate API docs from OpenAPI specifications + + + Build interactive API playgrounds + + + Set up API authentication methods + + + Enhance API pages with custom content + + + +## Customization + + + + Set your brand colors and theme + + + Configure a custom domain for your docs + + + Customize footer links and content + + + Track documentation usage with analytics + + + +## Deployment + + + + Connect GitHub for automated deployments + + + Automate linting and validation in CI/CD + + + Generate preview deployments for pull requests + + + Set up a custom domain for your documentation + + + +## Optimization + + + + Optimize for search engines and social sharing + + + Enhance page discoverability in search + + + Find and fix broken links in your docs + + + Set up URL redirects for moved content + + + +## Integrations + + + + Integrate Google Analytics, Mixpanel, and more + + + Collect user feedback on documentation pages + + + Customize search functionality + + + Integrate chat support widgets + + + +## Troubleshooting + + + + Resolve common GitHub deployment problems + + + Use the CLI to find broken links + + + Ensure your docs.json is properly configured + + + Fix navigation structure issues + + + +## Need more help? + + + + Explore comprehensive documentation guides + + + See all available documentation components + + + Review all configuration options + + + Get help from the Mintlify team + + diff --git a/organize/navigation.mdx b/organize/navigation.mdx index 3f9a0d94b..7f5c5ce3c 100644 --- a/organize/navigation.mdx +++ b/organize/navigation.mdx @@ -14,6 +14,10 @@ Choose one primary organizational pattern at the root level of your navigation. Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository. + + Configure page metadata, titles, and frontmatter properties + + -For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup). + + Set up OpenAPI specifications and generate API documentation + ```json { diff --git a/organize/pages.mdx b/organize/pages.mdx index a212b8aa5..14351b219 100644 --- a/organize/pages.mdx +++ b/organize/pages.mdx @@ -18,6 +18,10 @@ Use frontmatter to control: - SEO meta tags - Custom metadata + + Design information architecture and configure navigation structure + + The title of your page that appears in navigation and browser tabs. @@ -132,7 +136,9 @@ openapi: "GET /endpoint" --- ``` -Learn more about building [API documentation](/api-playground/overview). + + Build interactive API playgrounds and reference documentation + ## External links @@ -159,7 +165,9 @@ Most SEO meta tags are automatically generated. You can set SEO meta tags manual --- ``` -See [SEO](/optimize/seo) for complete SEO metadata options. + + Optimize your documentation for search engines and social sharing + ## Internal search keywords