# Expressive Code

Reference advanced code block markers, diffs, line numbers, and configuration.

Lotus enables Expressive Code by default. Use this reference when a page needs
more than a basic fenced code block.

## Configuration

Disable Expressive Code entirely when a site should use Astro's built-in Shiki
renderer instead.

```ts
lotus({
  expressiveCode: false,
})
```

Pass Expressive Code options through the Lotus integration when you need to
change the default themes or block behavior.

```ts
lotus({
  expressiveCode: {
    themes: ['github-light', 'github-dark'],
    defaultProps: {
      wrap: true,
    },
  },
})
```

## Inserted And Deleted Lines

Use `ins={...}` and `del={...}` for changed lines. Plain `{...}` remains a
neutral highlight.

````md
```ts del={2} ins={3-6} {8} title="src/theme.config.ts"
export default defineLotusConfig({
  navigation: [{ label: 'Docs', href: '/docs/' }],
  navbar: [
    { label: 'Docs', href: '/docs/' },
    { label: 'Dashboard', href: '/app/', variant: 'soft' },
  ],
  pageActions: [],
})
```
````

```ts del={2} ins={3-6} {8} title="src/theme.config.ts"
export default defineLotusConfig({
  navigation: [{ label: 'Docs', href: '/docs/' }],
  navbar: [
    { label: 'Docs', href: '/docs/' },
    { label: 'Dashboard', href: '/app/', variant: 'soft' },
  ],
  pageActions: [],
})
```

## Inline Markers

Mark text inside a line with quoted strings or regular expressions. Prefix the
marker with `ins=`, `del=`, or `mark=` to choose the marker type.

````md
```ts "docsBase" ins="'/docs'" del="'/documentation'" title="src/theme.config.ts"
export default defineLotusConfig({
  docsBase: '/docs',
  previousBase: '/documentation',
})
```
````

```ts "docsBase" ins="'/docs'" del="'/documentation'" title="src/theme.config.ts"
export default defineLotusConfig({
  docsBase: '/docs',
  previousBase: '/documentation',
})
```

Regular expressions are useful when the exact value changes across examples.

````md
```ts /variant: '[^']+'/ title="src/theme.config.ts"
export const navbar = [
  { label: 'Dashboard', href: '/app/', variant: 'soft' },
  { label: 'Login', href: '/login/', variant: 'outline' },
]
```
````

```ts /variant: '[^']+'/ title="src/theme.config.ts"
export const navbar = [
  { label: 'Dashboard', href: '/app/', variant: 'soft' },
  { label: 'Login', href: '/login/', variant: 'outline' },
]
```

## Diff Blocks

Use the `diff` language for compact before-and-after examples.

````md
```diff
- navigation: [{ label: 'Docs', href: '/docs/' }]
+ navbar: [{ label: 'Docs', href: '/docs/' }]
```
````

```diff
- navigation: [{ label: 'Docs', href: '/docs/' }]
+ navbar: [{ label: 'Docs', href: '/docs/' }]
```

Use `lang="..."` when you want diff markers and syntax highlighting for the
underlying language.

````md
```diff lang="ts" title="src/theme.config.ts"
 export default defineLotusConfig({
-  navigation: [{ label: 'Docs', href: '/docs/' }],
+  navbar: [{ label: 'Docs', href: '/docs/' }],
 })
```
````

```diff lang="ts" title="src/theme.config.ts"
 export default defineLotusConfig({
-  navigation: [{ label: 'Docs', href: '/docs/' }],
+  navbar: [{ label: 'Docs', href: '/docs/' }],
 })
```

## Line Numbers

Lotus includes Expressive Code's line number plugin, but keeps line numbers off
by default. Add `showLineNumbers` to a block when line references matter.

````md
```ts showLineNumbers title="src/content.config.ts"
import { docsLoader } from '@prosefly/astro-theme-lotus/content';
import { defineCollection } from 'astro:content';

const docs = defineCollection({
  loader: docsLoader(),
});

export const collections = { docs };
```
````

```ts showLineNumbers title="src/content.config.ts"
import { docsLoader } from '@prosefly/astro-theme-lotus/content';
import { defineCollection } from 'astro:content';

const docs = defineCollection({
  loader: docsLoader(),
});

export const collections = { docs };
```

Use `startLineNumber` for snippets taken from the middle of a file.

````md
```ts showLineNumbers startLineNumber=24 {27} title="src/theme.config.ts"
  appearance: {
    accent: 'indigo',
    gray: 'neutral',
    radius: 'medium',
  },
```
````

```ts showLineNumbers startLineNumber=24 {4} title="src/theme.config.ts"
  appearance: {
    accent: 'indigo',
    gray: 'neutral',
    radius: 'medium',
  },
```

## Hanging Indent

Use `hangingIndent` with `wrap` to keep wrapped lines easier to scan.

````md
```ts wrap hangingIndent=2 title="src/sidebar.ts"
export const sidebar = [{ label: 'Guides', items: [{ label: 'Getting Started', items: ['overview', 'installation', { label: 'Configuration', items: [{ autogenerate: { directory: 'configuration' } }] }] }] }]
```
````

```ts wrap hangingIndent=2 title="src/sidebar.ts"
export const sidebar = [{ label: 'Guides', items: [{ label: 'Getting Started', items: ['overview', 'installation', { label: 'Configuration', items: [{ autogenerate: { directory: 'configuration' } }] }] }] }]
```