Code Blocks

Fenced code blocks (blocks delimited by triple backticks) support syntax highlighting via Shiki with dual light/dark themes. Specify the language after the opening fence:

function greet(name) {
  return `Hello, ${name}!`;
}

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: A sample service
spec:
  type: service
  lifecycle: production
  owner: team-platform

Every code block includes a copy button and a word wrap toggle that appear on hover in the top-right corner.

Title bar

Add a filename or label above a code block with title="..." in the meta string:

```ts title="config/site.ts"
export const siteConfig = {
  name: 'My Docs',
}
```

export const siteConfig = {
  name: 'My Docs',
}

The title bar appears above the code block with a muted background.

You can combine title with other meta features like line highlighting:

```ts title="config/site.ts" {2}
export const siteConfig = {
  name: 'My Docs',  // this line is highlighted
}
```

export const siteConfig = {
  name: 'My Docs',
}

Highlighting lines

Highlight specific lines by adding line numbers in curly braces after the language:

```js {2,4-5}
const a = 1
const b = 2  // highlighted
const c = 3
const d = 4  // highlighted
const e = 5  // highlighted
```

const a = 1
const b = 2
const c = 3
const d = 4
const e = 5

Inline highlight comments

Highlight individual lines using an inline comment. The comment is removed from the rendered output:

```js
const regular = true
const highlighted = true
```

const regular = true
const highlighted = true

Diff lines

Show added and removed lines with [!code ++] and [!code --]:

```js
const config = {
  theme: 'light', 
  theme: 'dark',  
}
```

const config = {
  theme: 'light', 
  theme: 'dark',  
}

Focus lines

Dim all lines except the focused ones. Non-focused lines become visible on hover:

```js
const a = 1
const b = 2
const c = 3
```

const a = 1
const b = 2
const c = 3

Comment syntax by language

The inline notations ([!code highlight], [!code ++], [!code --], [!code focus]) use the comment syntax of the code block's language. Here are the most common:

For example, highlighting a line in a YAML block:

server:
  host: localhost
  port: 8080

Best practices

• Use title for filenames — When showing config files or code that readers create, add title="path/to/file" so they know where to put it.
• Use meta line numbers for multiple highlights — {2,4-5} is cleaner than adding [!code highlight] to every line.
• Use inline comments for single-line emphasis — [!code highlight] is better when you want to highlight one specific line in a longer block.
• Use diff notation for before/after — [!code ++] and [!code --] are clearer than describing changes in prose.
• Use focus for teaching — [!code focus] dims everything except the important lines, which is ideal for tutorials where you need to highlight a specific part of a larger snippet.
• Don't mix meta highlights with inline highlights — Pick one approach per code block. Using both can produce unexpected results.