Code Snippet Pattern Overview

For a long time, code in Vanilla was simply set in a monospace font, and we saw an opportunity to improve the way we deliver code examples to users.

A key goal is code clarity – code is not particularly resistant to errors: a missing character (or in some languages, a space or tab) can lead to problems and frustrated users – so the user should be able to select and copy the code easily. Syntax highlighting goes further toward making the code legible and we felt this was important to include via a third-party library.

Many code examples for modern applications and APIs can have different versions of the same snippet, for example for different languages or versions of the API. We wanted to allow for this so users can easily switch between examples from the code snippet itself.

Goals

Code clarity

A key goal is code clarity - the user should be able to identify the code they need, either to copy and use or as a reference example. It should be clear that the user is looking at code (rather than prose) and that the code is readable.

Ease of use

Code is not particularly resistant to errors: a missing character (or in some languages, a space or tab) can lead to errors so the user should be able to select and copy the code easily. It should be clear which version, platform or other switchable type is being used - in addition, showing a title and description can help a user who is skimming the page (or arriving from a search engine) to immediately understand the significance of the code snippet.

Modularity

Not all code examples are the same and this pattern should be modular and extensible - allowing the documentation author to decide which elements to use and which are not required.

Examples

Minimal example

All features utilised

No description, one version, no output

On-page mockup