Skip to main content

Code Block Examples

Code blocks are formatted blocks of Markdown that highlight your source code. Syntax highlighting is supported for a wide variety of programming languages and data formats. This page demonstrates how code blocks are handled in our documentation.

Markdown Code Blocks​

Here's a template to use for typical code blocks:

Template
```[Your Language Here] showLineNumbers title="[Your Title Here]"
[Your Content Here]
```
Using pound sign in a code block

The '#' sign is used by Markdown for headings, so using it in a code block will probably not give you the formatting or color-coding that you desire. You can escape the pound sign with '\#' and it will be ignored.

Example using a short bit of TypeScript:

```typescript showLineNumbers title="components/UserProfile.tsx"
import React, { useState, useEffect } from 'react';
import { User, ApiResponse } from '@/types/user';

interface UserProfileProps {
  userId: string;
  onUserUpdate?: (user: User) => void;
}
```

All Code Blocks Have Text Wrap and Copy Buttons​

You simply rollover the upper-right hand corner of the code block:

Rollover Tools

About That Text Wrap Button

The text wrap button will sometimes go away if there is no text to wrap or unwrap.

Here's a live version of the previous TypeScript example:

components/UserProfile.tsx
import React, { useState, useEffect } from 'react';
import { User, ApiResponse } from '@/types/user';

interface UserProfileProps {
  userId: string;
  onUserUpdate?: (user: User) => void;
}

Supported Syntax Highlighting Languages​

Docusaurus uses Prism.js for syntax highlighting.

Commonly Used Front-End Languages @Schwab.​

The Full List Of Types

The full list of supported languages is here: Prism.js

Support for these languages is in our build of Docusaurus:

Programming Languages​

  • typescript | ts - TypeScript
  • javascript | js - JavaScript
  • jsx - JavaScript with JSX
  • tsx - TypeScript with JSX
  • php - PHP
  • mdx - MDX
  • bash | sh - Bash/shell

Web Markup Languages​

  • html - HTML
  • css - CSS
  • sass | scss - Sass/SCSS
  • markdown | md - Markdown

Data Formats​

  • yml - YAML
  • xml - XML
  • json - JSON

Miscellaneous Formats​

  • docker - Docker files
  • diff - Diff/Patch files
  • git - Git
  • http - HTTP
  • sql - SQL
  • mermaid - Mermaid
  • regex - Regular expressions
  • plaintext / text - Plain text (no highlighting)

Other Docusaurus Code Block Features​

Here are some less-commonly used features available for code blocks in Docusaurus:

Collapsible Code Blocks​

Docusaurus does not natively support collapsible code blocks but you can enable it by using the summary and details tags

<details>
<summary>There Is Some Useful Code In Here</summary>

```ts
interface User {
  name: string;
  id: number;
}
 
const user: User = {
  username: "Hayes",
Object literal may only specify known properties, and 'username' does not exist in type 'User'.
  id: 0,
};
```
</details>

Line Highlighting​

```jsx {1,3-5}
// Highlights lines 1, 3, 4, and 5
```

Line Range Selection​

```typescript showLineNumbers {2-10}
// Shows only lines 2-10 of the code
```

Magic Comments for Highlighting​

Lines between // highlight-start and // highlight-end will be highlighted.
The line after // highlight-next-line will be highlighted.

```typescript showLineNumbers
const user = 'John'; // highlight-next-line
const email = user + '@example.com';
// highlight-start
const profile = {
  name: user,
  email: email
};
// highlight-end
```

Custom Start Line Number​

```python showLineNumbers {5-10} title="script.py" 
# Line numbers start from 5
```

Diff Highlighting (with diff language)​

```diff
  function getUserName(user) {
-   return user.firstName + user.lastName;
+   return user.firstName + ' ' + user.lastName;
  }
  
  const config = {
    apiUrl: 'https://api.example.com',
-   timeout: 5000
+   timeout: 10000,
+   retries: 3
  };
```

Custom CSS Classes​

The style is applied to the entire code block.

```javascript className="my-custom-class"
const response = await fetch(/api/users);
```
Custom Styling

The className attribute allows you to apply custom CSS classes to code blocks for specialized styling, such as highlighting API examples, warnings, or different types of code snippets.

Complete Example with Many Features​

components/UserProfile.tsx
import React from 'react';
const UserProfile = () => { // highlight-next-line
  const [user, setUser] = useState(null);
  
  // highlight-start
  useEffect(() => {
    fetchUser();
  }, []); 
  // highlight-end
  
  return <div>{user?.name}</div>;
};