Skip to content

Docs updates for new Codeblock v3 docs #802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
Jun 11, 2025
Merged

Docs updates for new Codeblock v3 docs #802

Changes from 21 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
1edd825
outline for updates
ethanpalm Jun 9, 2025
ecfd929
update intro
ethanpalm Jun 9, 2025
ee99afb
add option syntax
ethanpalm Jun 10, 2025
200dd11
update title section
ethanpalm Jun 10, 2025
0e96132
icon section
ethanpalm Jun 10, 2025
666adcf
line highlighting and focusing
ethanpalm Jun 10, 2025
adc23dc
showLineNumbers
ethanpalm Jun 10, 2025
80047ac
expandable
ethanpalm Jun 10, 2025
75f4dcf
wrap
ethanpalm Jun 10, 2025
83ba129
copyedits
ethanpalm Jun 10, 2025
21b0cb4
typo
ethanpalm Jun 10, 2025
4a510ef
update to lines
dks333 Jun 11, 2025
4382d23
add nav tag
dks333 Jun 11, 2025
ce16313
update md to mdx
ethanpalm Jun 11, 2025
58d5cdf
support for all Shiki languages
ethanpalm Jun 11, 2025
daa1aea
update examples
ethanpalm Jun 11, 2025
afb3a3a
edit `New` tag
ethanpalm Jun 11, 2025
50de02d
group code block options
ethanpalm Jun 11, 2025
2e5b7e5
add more options to code block example
ethanpalm Jun 11, 2025
934bc41
Merge branch 'main' into codeblock-v3-docs
ethanpalm Jun 11, 2025
63791e3
add links to icon libraries
ethanpalm Jun 11, 2025
17e817c
fix heading
ethanpalm Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 114 additions & 120 deletions code.mdx
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recommend adding something to note that for all features, they need to have language set first. It doesn't work when it's like this directly

```title="Title"
Code
```

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point. I made all the options H3s under an H2 for code block options to introduce this information and make it more clear that these options only apply to code blocks. It should be apparent that you can't style inline code, but this makes it more direct.

Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,26 @@
title: "Code"
description: "Display inline code and code blocks"
icon: "code"
tag: "New"
---

## Basic
## Adding code samples

### Inline Code
You can add inline code snippets or code blocks. Code blocks support meta options for syntax highlighting, titles, line highlighting, icons, and more.

### Inline code

To denote a `word` or `phrase` as code, enclose it in backticks (\`).

```mdx
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```

### Code Block
### Code block

Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. Specify the programming language for syntax highlighting and to enable meta options. Add any meta options after the language.

```java HelloWorld.java
```java HelloWorld.java lines icon="java"
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
Expand All @@ -27,7 +30,7 @@
```

````mdx
```java HelloWorld.java
```java HelloWorld.java lines icon="java"
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
Expand All @@ -36,9 +39,23 @@
```
````

## Syntax Highlighting
## Code block options

You can add meta options to your code blocks to customize their appearance.

<Note>
You must specify a programming language for a code block before adding any other meta options.
</Note>

### Option syntax

* **String and boolean options**: Wrap with `""`, `''`, or no quotes.
* **Expression options**: Wrap with `{}`, `""`, or `''`.

Enable syntax highlighting by adding the language name after the opening backticks of a code snippet.
### Syntax highlighting
Enable syntax highlighting by specifying the programming language after the opening backticks of a code block.

We use Shiki for syntax highlighting and support all available languages. See the full list of [languages](https://shiki.style/languages) in Shiki's documentation.

Check warning on line 58 in code.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

code.mdx#L58 

Did you really mean 'Shiki'?

Check warning on line 58 in code.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

code.mdx#L58 

Did you really mean 'Shiki's'?

```java
class HelloWorld {
Expand All @@ -58,124 +75,36 @@
```
````

### Languages

We use [Shiki](https://shiki.style/languages) for syntax highlighting and support these languages using standard markdown syntax:

<table className="border-collapse">
<thead>
<tr>
<th className="pr-12 py-2 text-left font-medium">Language</th>
<th className="pr-12 py-2 text-left font-medium">ID</th>
</tr>
</thead>
<tbody>
<tr>
<td className="pr-12 py-2">Bash</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">bash</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Laravel Blade</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">blade</code></td>
</tr>
<tr>
<td className="pr-12 py-2">C</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">c</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">C++</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">c++</code></td>
</tr>
<tr>
<td className="pr-12 py-2">C#</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">c#</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Dart</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">dart</code></td>
</tr>
<tr>
<td className="pr-12 py-2">Go</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">go</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Java</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">java</code></td>
</tr>
<tr>
<td className="pr-12 py-2">JavaScript</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">javascript</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">JSON</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">json</code></td>
</tr>
<tr>
<td className="pr-12 py-2">JSX</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">jsx</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Kotlin</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">kotlin</code></td>
</tr>
<tr>
<td className="pr-12 py-2">Log</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">log</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Markdown</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">markdown</code></td>
</tr>
<tr>
<td className="pr-12 py-2">PHP</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">php</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Python</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">python</code></td>
</tr>
<tr>
<td className="pr-12 py-2">Ruby</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">ruby</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">Swift</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">swift</code></td>
</tr>
<tr>
<td className="pr-12 py-2">TypeScript</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">typescript</code></td>
</tr>
<tr className="">
<td className="pr-12 py-2">TSX</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">tsx</code></td>
</tr>
<tr>
<td className="pr-12 py-2">YAML</td>
<td className="pr-12 py-2"><code className="px-1 rounded text-sm">yaml</code></td>
</tr>
</tbody>
</table>

## Names

Add a title after the programming language to set the name of your code example. The text can be anything as long as its all in one line.
### Title
Add a title after the programming language to label your code example. Titles can be any string on a single line.

```javascript Code Block Example
const hello = "world";
```

````mdx Code Block Example
````mdx
```javascript Code Block Example
const hello = "world";
```
````

## Line Highlighting
### Icon
Add an icon to your code block. You can use [FontAwesome](https://fontawesome.com/icons) icons, [Lucide](https://lucide.dev/icons/) icons, or absolute URLs.

Highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.
```javascript icon="square-js"
const hello = "world";
```

```javascript Line Highlighting Example {1,3-5}
````mdx
```javascript icon="square-js"
const hello = "world";
```
````

### Line Highlighting
Highlight specific lines in your code blocks using `highlight` with the line numbers or ranges you want to highlight.

```javascript Line Highlighting Example highlight={1-2,5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
Expand All @@ -184,7 +113,7 @@
```

````mdx
```javascript Line Highlighting Example {1,3-5}
```javascript Line Highlighting Example highlight={1-2,5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
Expand All @@ -193,11 +122,52 @@
```
````

## Expandable
### Line focusing
Focus on specific lines in your code blocks using `focus` with line numbers or ranges.

```javascript Line Focus Example focus={2,4-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```

````mdx
```javascript Line Focus Example focus={2,4-5}
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````

If you have a long code block and `[expandable]` after your title to make it close and expand.
### Show line numbers
Display line numbers on the left side of your code block using `lines`.

```python library.py [expandable]
```javascript Show Line Numbers Example lines
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```

````mdx
```javascript Show Line Numbers Example lines
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```
````

### Expandable
Allow users to expand and collapse long code blocks using `expandable`.

```python Expandable Example expandable
from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass
Expand Down Expand Up @@ -288,8 +258,32 @@
```

````mdx
```javascript Expandable Example [expandable]
const greeting = "Hello, World!";
```python Expandable Example expandable
from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass

# ...

if __name__ == "__main__":
main()
```
````

### Wrap
Enable text wrapping for long lines using `wrap`. This prevents horizontal scrolling and makes long lines easier to read.

```javascript Wrap Example wrap
const greeting = "Hello, World! I am a long line of text that will wrap to the next line.";
function sayHello() {
console.log(greeting);
}
sayHello();
```

````mdx
```javascript Wrap Example wrap
const greeting = "Hello, World! I am a long line of text that will wrap to the next line.";
function sayHello() {
console.log(greeting);
}
Expand Down
Loading