# Code snippet tag

The `code-snippet` tag displays code examples in your documentation that are loaded from local files.

## Syntax and usage

The `code-snippet` tag is a self-closing tag, which means it has no child elements.
Use attributes to pass the path to the local file and configure how the snippet is displayed.

Example element:

museum-redocly.yaml
products:
  tickets:
    name: Museum Tickets
    icon: images/ticket-logo.png
    folder: products/tickets/
  events:
    name: Museum Events
    icon: ./images/event-logo.svg
    folder: ./products/events
navbar:
Example syntax:


```
{% code-snippet
  file="./code-examples/museum-config.yaml"
  language="yaml"
  from=1
  to=10
  title="museum-redocly.yaml"
/%}
```

## Attributes

| Option | Type | Description |
|  --- | --- | --- |
| file | string | The absolute or relative path to the file with the code snippet. |
| from | number | string | Use to specify the **starting point** of your code snippet and *include* it in the rendered element.
Works with either a line number or a specific string contained in the starting line.
Cannot be used with `after`. |
| to | number | string | Use to specify the **ending point** of your code snippet and *include* it in the rendered element.
Works with either a line number or a specific string contained in the starting line.
Cannot be used with `before`. |
| after | number | string | Similar to `from` but *excludes the starting point* from the rendered element.
Cannot be used with `from`. |
| before | number | string | Similar to `to` but *excludes the ending point* from the rendered element.
Cannot be used with `to`. |
| prefix | string | Use to add explanatory information at the start of the code snippet.
Prepend with `//` to style as a comment.
We recommend including a new line (`\n`) at the end of the prefix. |
| language | string | Sets the syntax highlighting rules for the code sample used.
Syntax highlighting is available for all languages listed on the [supported languages page](https://prismjs.com/#supported-languages). |
| title | string | Set the text displayed in the gray header at the top of the code snippet. | Commonly used for filenames. |
| `wrap` | boolean | Wraps long lines in the code snippet to avoid or reduce horizontal scroll.
Default value is `false`. |


## Examples

### Use line numbers as selectors

Example element:

museum-redocly.yaml
// Please reserve navbar entries for important use cases 
  items:
    - page: about-the-museum.md
      label: About
    - page: sponsor-the-museum.md
      label: Benefactors
footer:
Example syntax:


```
{% code-snippet
  file="./code-examples/museum-config.yaml"
  language="yaml"
  from=11
  to=16
  title="museum-redocly.yaml"
  prefix="// Please reserve navbar entries for important use cases \n"
/%}
```

### Use strings as selectors

Example element:

museum-redocly.yaml
footer:
  copyrightText: Redocly Museum API
  items:
    # Column 1
    - page: policies/faq.md
      label: Museum FAQ
    # Column 2
    - group: Resources
      items:
        - href: https://access.si.edu/museum-professionals
          label: Smithsonian Resources
        - href: https://www.aam-us.org/topic/resource-library/
          label: American Alliance of Museums
Example syntax:


```
{% code-snippet
  file="./code-examples/museum-config.yaml"
  language="yaml"
  from="footer"
  to="redirects"
  title="museum-redocly.yaml"
/%}
```

### Compare selection attributes

Using the `to` / `from` selectors **includes** the starting or ending point in the rendered example while the `after` / `before` selectors **excludes** them.

The examples below use the same source file with different selection attributes.

**To / from example syntax**


```
{% code-snippet
  file="./code-examples/useTabs.ts"
  from=12
  to=14
/%}
```

**To / from example element**

  const setTabRef = useCallback((element: HTMLButtonElement | null, index: number) => {
    tabRefs.current[index] = element;
  }, []);
**After / before example syntax**

    tabRefs.current[index] = element;
**After / before example element**


```
{% code-snippet
  file="./code-examples/useTabs.ts"
  after=12
  before=14
/%}
```

### Add file names to code snippets

Add a file name to display in the code snippet header using the `title` attribute:


```markdoc
```js {% title="scripts.js" %}
function test() {
  console.log('Hello World!');
}
```
```

Result:


```js scripts.js
function test() {
  console.log('Hello World!');
}
```

### Highlight lines and text

Highlight a specific line using `[!code highlight]`:


```markdoc
```js
function test() {
  console.log('Hello World!'); // [!code highlight] [!code highlight]
}
```
```

Result:


```js
function test() {
  console.log('Hello World!'); // [!code highlight]
}
```

Highlight multiple consecutive lines:


```markdoc
```js 
// [!code highlight:3] [!code highlight:3]
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);
}
```
```

Result:


```js
// [!code highlight:3]
function test() { 
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);
}
```

Highlight non-consecutive lines using the `highlight` attribute:


```markdoc
```js {% highlight="{1,3-4}" %}
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);
}
```
```

Result:


```js
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);
}
```

Highlight specific words or symbols:


```markdoc
```js
// [!code word:Hello] [!code word:Hello]
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);  // prints "Hello World"
}
```
```

Result:


```js
// [!code word:Hello]
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);  // prints "Hello World"
}
```

Focus on specific lines by dimming others with a code comment:


```markdoc
```js
function test() {
  const hello = 'Hello'; // [!code focus] [!code focus]
  const world = 'World';
  console.log(hello + " " + world);
}
```
```

Or with a Markdoc tag and a pattern.


```markdoc
```js {% highlight="/Hello/" %}
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world);  // prints "Hello World"
}
```
```

Result:


```js
function test() {
  const hello = 'Hello'; // [!code focus]
  const world = 'World';
  console.log(hello + " " + world);
}
```

Mark lines with error and warning levels:


```markdoc
```js
function test() {
  console.log('No errors or warnings');
  console.error('Error'); // [!code error] [!code error]
  console.warn('Warning'); // [!code warning] [!code warning]
}
```
```

Result:


```js
function test() {
  console.log('No errors or warnings');
  console.error('Error'); // [!code error]
  console.warn('Warning'); // [!code warning]
}
```

Show added and removed lines:


```markdoc
```js
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world); // [!code --] [!code --]
  console.log(`${hello} ${world}`); // [!code ++] [!code ++]
}
```
```

Result:


```js
function test() {
  const hello = 'Hello';
  const world = 'World';
  console.log(hello + " " + world); // [!code --]
  console.log(`${hello} ${world}`); // [!code ++]
}
```

## Best practices

**Minimize complexity**

Avoid unnecessary details or context.
Simplified code snippets are easier for your readers to understand and apply.

**Centralize example files**

Store your example code in a central directory to make them easier to manage, update, and reference from code snippet tags.

## Resources

- **[Code snippet configuration](/docs/realm/config/code-snippet)** - Complete reference for customizing code snippet appearance, icons, and behavior across your documentation
- **[Global and page-level configuration](/docs/realm/config/code-snippet#configuration-scope)** - Apply consistent code snippet styling and settings throughout your project