Configure code snippets
You can configure code snippets to change the copy and report icons to text, as well as to customize the label and tooltip text of the report icon. To configure code snippets, you add options under the codeSnippet
option.
Before you begin
Make sure you have the following before you begin:
- a
redocly.yaml
file in the root of your project
Configure globally
Configuration for the codeSnippet
option added to the redocly.yaml
file updates all Markdown and API reference pages globally.
Configure by page
You can configure the codeSnippet
option for individual Markdown pages in the front matter. Front matter configurations take precedence, but if an option's setting is not configured in the front matter but is configured in the redocly.yaml
file, it applies.
The following is an example codeSnippet
configuration in the front matter of a Markdown page:
--- report: tooltipText: Report a problem with code sample label: What is wrong with this code sample? ---
The example configuration updates the text that displays when users hover over the report icon to, "Report a problem with code sample." After selecting the report icon, following the question, "What is wrong with this code sample?", users can then enter a free-form response into a text field.
Configure code snippet icons
You can configure the code snippet icons to be hidden or to display as text instead of the default icons.
To hide the code snippet icons, use the following configuration:
codeSnippet: copy: hide: true report: hide: true expand: hide: true collapse: hide: true
Expand and collapse buttons only appear on JSON request or response examples in OpenAPI files.
To display the code snippet icons as text, use the following configuration:
codeSnippet: elementFormat: text
Configure report options
All code snippets include a report icon users can select to send feedback about the code snippet. You can customize the label or the tooltip text for the report button on code snippets.
To customize the label or the tooltip text for the report button:
Add the
report
object, under thecodeSnippet
object.codeSnippet: report:
Add the
label
option with the value of the statement or question you want displayed above the text box in the comment form modal:codeSnippet: report: label: Please tell us what is wrong with this code sample.
Add the
tooltipText
option with the value of the text you want displayed when users hover over the report icon or text.codeSnippet: report: label: Please tell us what is wrong with this code sample. tooltipText: Send feedback about this code sample.
The example configuration updates the text that displays when users hover over the report icon to, "Send feedback about this code sample." After selecting the report icon, following the statement, "Please tell us what is wrong with this code sample," users can then enter a free-form response into a text field.
The data collected from this feedback form is displayed by project on the Feedback reports page. See View and export feedback data for more information.
Add file name
You can add a file name to code snippets to display in the gray header of the code snippet.
To add a file name to a code snippet, add the following Markdoc tag to your code snippet, directly after the code language:
```js {% title="scripts.js" %}
function test() {
console.log('Hello World!');
}
```
The example is a code snippet of JavaScript code with the file name, "scripts.js" added and would display as follows:
function test() { console.log('Hello World!'); }
Insert code from a file
To add all of or a section of the code from a file in your repository, use the code-snippet
Markdoc tag. You can either use line numbers or actual text from the file to indicate where the code snippet should begin and end. You can also include the file name with the title
attribute and add syntax highlighting when you add the language
attribute.
The following example Markdoc syntax pulls content from a hello-world.js
file and includes the entire file:
{% code-snippet file="../../hello-world.js" language="js" title="hello-world.js /%}
The following code snippet is how the example Markdoc syntax is rendered:
//begin function test() { console.log('Hello World!'); } //end
The following example Markdoc syntax pulls content from a hello-world.js
file and includes code between line 2 and "//end":
{% code-snippet file="../../hello-world.js" from=2 before="//end" language="js" /%}
The following code snippet is how the example Markdoc syntax is rendered:
function test() { console.log('Hello World!'); }
Add prefix
To add a prefix at the beginning of a code snippet pulled from a file in your repository, use the prefix
attribute of the code-snippet
Markdoc tag.
The following example Markdoc syntax pulls lines 2 to 4 from a hello-world.js
file and includes a comment, "Example prefix comment" and includes a newline:
{% code-snippet
prefix="// Example prefix comment\n"
file="../../hello-world.js"
language="js"
from=2
to=4
title="hello-world.js" /%}
The following code snippet is how the example Markdoc syntax is rendered:
// Example prefix comment function test() { console.log('Hello World!'); }