Last updated

Code Snippet Tag Redocly Custom Tag

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

Syntax and usage

Code snippet 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

OptionTypeDescription
fileStringThe absolute or relative path to the file with the code snippet.
fromNumber | StringUse 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.
toNumber | StringUse 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.
afterNumber | StringSimilar to from but excludes the starting point from the rendered element. Cannot be used with from.
beforeNumber | StringSimilar to to but excludes the ending point from the rendered element. Cannot be used with to.
prefixStringUse 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.
languageStringSets the syntax highlighting rules for the code sample used. Syntax highlighting is available for all languages listed on the supported languages page.
titleStringSet the text displayed in the grey header at the top of the code snippet. Commonly used for filenames.
wrapBooleanWraps long lines in the code snippet to avoid or reduce horizontal scroll. Default value is false.

Examples

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"
/%}

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
/%}

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.

 
Next page