The code-snippet
tag displays code examples in your documentation that are loaded from local files.
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:
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"
/%}
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. | |
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 . |
Example element:
// 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"
/%}
Example element:
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"
/%}
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 a file name to display in the code snippet header using the title
attribute:
```js {% title="scripts.js" %}
function test() {
console.log('Hello World!');
}
```
Result:
function test() {
console.log('Hello World!');
}
Highlight a specific line using [!code highlight]
:
```js
function test() {
console.log('Hello World!'); // [!code highlight]
}
```
Result:
function test() {
console.log('Hello World!');
}
Highlight multiple consecutive lines:
```js
// [!code highlight:3]
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world);
}
```
Result:
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world);
}
Highlight non-consecutive lines using the highlight
attribute:
```js {% highlight="{1,3-4}" %}
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world);
}
```
Result:
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world);
}
Highlight specific words or symbols:
```js
// [!code word:Hello]
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world); // prints "Hello World"
}
```
Result:
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:
```js
function test() {
const hello = 'Hello'; // [!code focus]
const world = 'World';
console.log(hello + " " + world);
}
```
Or with a Markdoc tag and a pattern.
```js {% highlight="/Hello/" %}
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world); // prints "Hello World"
}
```
Result:
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world);
}
Mark lines with error and warning levels:
```js
function test() {
console.log('No errors or warnings');
console.error('Error'); // [!code error]
console.warn('Warning'); // [!code warning]
}
```
Result:
function test() {
console.log('No errors or warnings');
console.error('Error');
console.warn('Warning');
}
Show added and removed lines:
```js
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world); // [!code --]
console.log(`${hello} ${world}`); // [!code ++]
}
```
Result:
function test() {
const hello = 'Hello';
const world = 'World';
console.log(hello + " " + world);
console.log(`${hello} ${world}`);
}
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.
- Code snippet configuration - Complete reference for customizing code snippet appearance, icons, and behavior across your documentation
- Global and page-level configuration - Apply consistent code snippet styling and settings throughout your project