Skip to content
Writing Documentation

Code blocks

Highlight code, compare changes, and draw directory trees.

All fence options are optional. Use a plain block, add a language for highlighting, or combine the options below when they help explain an example.

Plain code

Write a fence without a language or options:

md
```
Hello, RDX!
```
Code
Hello, RDX!

The header uses the default code label, with no syntax highlighting or line numbers.

Highlight a language

Add the language after the opening triple backticks. For example, use ts, tsx, js, json, bash, py, css, or sql.

md
```tsx
export function Welcome() {
  return <h1>Hello, RDX!</h1>
}
```
tsx
export function Welcome() {
  return <h1>Hello, RDX!</h1>
}

Highlighting runs on the server with Shiki. Its palette follows the light/dark theme. Unknown languages and unlabelled fences remain readable as plain text; inline code is not highlighted.

Choose syntax themes

Set a bundled Shiki theme for either appearance in rdx.config.ts. For example, use Catppuccin Mocha in dark mode:

rdx.config.ts
syntaxHighlighting: {
  themes: {
    dark: 'catppuccin-mocha',
  },
},

Set light: 'catppuccin-latte' to use Catppuccin in light mode too. When a theme is omitted, RDX uses github-light or github-dark for that appearance. The palette applies to syntax tokens in built-in and custom languages.

Highlight a custom language

Save a TextMate JSON grammar in your project, for example at grammars/task-example.tmLanguage.json:

grammars/task-example.tmLanguage.json
{
  "scopeName": "source.task-example",
  "patterns": [
    { "match": "\\b(task|run)\\b", "name": "keyword.control.task-example" },
    {
      "begin": "\"",
      "end": "\"",
      "name": "string.quoted.double.task-example"
    }
  ]
}

Add the grammar to your existing defineConfig options:

rdx.config.ts
syntaxHighlighting: {
  languages: {
    'task-example': './grammars/task-example.tmLanguage.json',
  },
},

Use the key as the fence language in any .md or .mdx page:

md
```task-example title="build.task" lineNumbers
task "build"
run "rdx build"
```
build.task
task "build"run "rdx build"

Paths are relative to the project root. Use a lowercase fence name and a self-contained grammar with its own scopeName. The grammar identifies tokens, and RDX's light and dark themes supply their colors. Include the JSON file when deploying your project.

Show a filename

Add title="rdx.config.ts" after the language to display a filename or label in the header:

md
```ts title="rdx.config.ts"
import { defineConfig } from '@lexibase/rdx'

export default defineConfig({
  metadata: { applicationName: 'My documentation' },
  search: true,
})
```
rdx.config.ts
import { defineConfig } from '@lexibase/rdx'

export default defineConfig({
  metadata: { applicationName: 'My documentation' },
  search: true,
})

Use quotes for titles with spaces, such as title="Install dependencies". Titles also work with text, diff, and folder fences. The language continues to control highlighting, and the copy button copies only the block content. Without a title, the header shows the language or the default block label.

Number lines

Add only lineNumbers after the language to display numbers starting at 1. A title and starting value are optional:

md
```tsx lineNumbers
export function Welcome() {
  return <h1>Hello, RDX!</h1>
}
```
tsx
export function Welcome() {  return <h1>Hello, RDX!</h1>}

Omit lineNumbers to keep numbers hidden. Numbering works with highlighted code, plain text, diff, and folder fences. The copy button excludes the numbers.

Set the starting line

Add startLine=20 alongside lineNumbers for a fragment from a larger file. You can leave out the title:

md
```ts lineNumbers startLine=20
const enabled = true

console.log(enabled)
```
ts
const enabled = true
console.log(enabled)

startLine must be a positive integer. Omit it to start at 1; it only sets the starting value when lineNumbers is present. Blank lines in code count as lines, and wrapping a long line keeps its original number.

Combine options

Add a title when you want the filename alongside the custom starting line:

md
```ts title="example.ts" lineNumbers startLine=20
const enabled = true
console.log(enabled)
```
example.ts
const enabled = trueconsole.log(enabled)

Copy a block

The icon in the header copies only the code, preserving indentation and line breaks. A checkmark confirms success. If clipboard permission is unavailable, the code remains selectable for manual copying.

Clipboard access needs HTTPS or localhost and browser permission.

Wrap long lines

On small screens, use the wrap-lines icon in the header to toggle line wrapping for that block. Wrapping starts disabled so indentation stays intact. The copy button keeps the original text and line breaks in either mode.

Long blocks on mobile

On screens narrower than 768px, blocks taller than about 12 visible lines show a preview with a Show more button. Use Show less to return to the preview. This happens automatically, including when wrapping makes a block taller.

Short blocks and desktop views show the complete content. The copy button always copies the full block, including the portion beyond the preview.

Show Markdown source

Use four backticks around a source example that contains triple backticks:

md
```tsx
export function Welcome() {
  return <h1>Hello, RDX</h1>
}
```

Long blocks scroll horizontally inside their container. Keep examples focused; use Tabs for related alternatives.

Mermaid diagrams

Use a mermaid fence to render a diagram. The header can show an optional title, copy the definition, switch between diagram and source, or open a larger view:

Documentation flow
flowchart LR
    A[Write Markdown] --> B[Preview] --> C[Publish]

See Diagrams for syntax examples and accessibility.

Directory trees

Use a folder fence with two spaces per level. End folder names with /; RDX generates the connecting branches from the indentation:

Folder
my-docs/
docs/
guides/
introduction.mdx
public/
rdx.config.ts

Names ending in / receive a folder icon. File icons follow their extension: code, JSON, images, text documents, or a generic file icon. Names without an extension use the generic icon.

ASCII branches

To type the branches explicitly, use these prefixes with a space before the name:

TypeRendered branch
|-├──
|_└──
|│
md
```folder title="Project files"
my-docs/
|- docs/
|   |_ intro.mdx
|- package.json
|_ logo.svg
```
Project files
my-docs/
docs/
intro.mdx
package.json
logo.svg

Prefixes are converted at the start of tree lines; characters inside filenames stay literal. You can also paste a tree that already uses Unicode branches. The copy button copies the Unicode text diagram without icons. A text fence keeps the original characters unchanged.

Compare changes

Use a diff fence. Prefix removed lines with -, added lines with +, and unchanged lines with a space:

diff
 const search = false
 const search = true
 console.log(search)

Removed and added lines use distinct backgrounds and markers. The copy button preserves the full patch, including its markers and original line breaks.