Code Blocks and Syntax Highlighting

Relevant source files

The following files were used as context for generating this wiki page:

• docs.json
• api-reference/openapi.json
• README.md
• essentials/code.mdx (Referenced in docs.json)
• essentials/markdown.mdx (Referenced in docs.json)

Code blocks are a fundamental component of the Mintlify documentation platform, used for displaying code examples, installation commands, and API request/response bodies. The system is designed to provide rich, interactive code blocks that aid developer comprehension and usability. This is achieved through a combination of standard Markdown, specific configuration in docs.json, and automated generation from specifications like OpenAPI for API references.

The documentation structure explicitly dedicates pages to guide content creators on how to use these features, as seen with the essentials/code and essentials/markdown pages defined in the site's navigation. These features are enhanced with contextual tools that allow users to interact with the code directly, such as copying it or opening it in various AI tools and editors.

Sources: docs.json:34-35, docs.json:141-152

Contextual Code Block Options

The interactivity of code blocks is managed through the contextual object in the docs.json configuration file. This configuration enables a set of helper utilities that appear alongside code blocks in the rendered documentation.

Sources: docs.json:141-152

Configuration

The contextual.options array in docs.json specifies which interactive options are available to the end-user. The platform supports a range of tools for code manipulation and analysis.

"contextual": {
  "options": [
   "copy",
   "view",
   "chatgpt",
   "claude",
   "perplexity",
   "mcp",
   "cursor",
   "vscode"
 ]
},

Sources: docs.json:141-152

The following diagram illustrates the flow of how this configuration is applied to a code block.

Sources: docs.json:141-152

Available Options

The configured options provide shortcuts for developers to use the displayed code in other applications.

Option	Description
copy	Allows the user to copy the code snippet to their clipboard.
view	(Functionality not specified in source files)
chatgpt	Opens the code snippet in ChatGPT.
claude	Opens the code snippet in Claude.
perplexity	Opens the code snippet in Perplexity.
mcp	(Functionality not specified in source files)
cursor	Opens the code snippet in Cursor.
vscode	Opens the code snippet in VS Code.

Sources: docs.json:143-151

Usage in Documentation

Code blocks are used throughout the documentation, from getting-started guides to detailed API specifications.

Markdown Content

The README.md file provides a direct example of using a standard Markdown code block for demonstrating a shell command. This is a common pattern for installation instructions and command-line usage examples.

npm i -g mint

Sources: README.md:15-17

The site's navigation structure in docs.json points to dedicated pages for content authors, indicating a structured approach to documenting code usage.

Sources: docs.json:32-36

API Reference Generation

The project uses an openapi.json file to define its API, and this specification is used to automatically generate the API reference documentation, which heavily features code blocks for requests, responses, and data models.

Sources: api-reference/openapi.json, docs.json:51-66

OpenAPI Specification

The api-reference/openapi.json file contains structured data for endpoints, including descriptions, parameters, and schemas. This structured data is the source for the code examples shown in the API reference section of the documentation. For example, the schema for a Plant object is defined directly in the OpenAPI file.

"schemas": {
  "Plant": {
    "required": [
      "name"
    ],
    "type": "object",
    "properties": {
      "name": {
        "description": "The name of the plant",
        "type": "string"
      },
      "tag": {
        "description": "Tag to specify the type",
        "type": "string"
      }
    }
  },

Sources: api-reference/openapi.json:151-169

Rendering Flow

The Mintlify build process parses the openapi.json file to generate the API reference pages. The schemas and endpoint definitions are transformed into formatted documentation, including syntax-highlighted JSON examples.

Sources: api-reference/openapi.json, docs.json:51-57

Summary

The Mintlify documentation project provides a robust system for displaying code with syntax highlighting. It is configurable via docs.json to include interactive elements, allowing users to copy or open code snippets in external tools. Code blocks are authored using standard Markdown for guides and are also automatically generated from OpenAPI specifications for the API reference, ensuring consistency and accuracy. The documentation itself is structured to teach authors how to effectively use these features.

Sources: docs.json, README.md, api-reference/openapi.json