The publishing system supports quite a few ways to include code and related technical content, and the various markup options can affect semantics. So this should make it easier to remember what to use where and how—particularly the code helper which has quite a few options.

Inline Code Samples

For inline bits of technical content-samp, var, and code, most of the standard options are supported, but often there is a corresponding helper that’s more advanced and will generate more complete and progressively-enhanced markup with more polished styling.

In all cases, standard Markdown options are supported, but the ERb helpers take things a little further by creating richer markup and supporting options for customization of the resulting output.

Pre-formatted Content

<pre> Pre-formatted content with extra spaces and a line break.</pre>
Figure 1

You can keep whitespace with the pre element, but it should be used sparingly.

↩︎

While it won’t often make sense on its own, the pre element (Figure 1) provides a way to maintain whitespace when used with any of the other elements. It can also come in handy for formatting quotations or things like poetry that have specific line breaks. In most cases, the custom helpers handle this via CSS by using white-space: pre;.

Markdown Backticks

`code-sample`
Figure 2

Backtick code samples can be handy.

↩︎

Markdown’s ` (backtick) (Figure 2) can be used to show a small portion of code directly inline. In general, if it’s long enough to wrap to a new line, the full code helper will be a better choice.

Sample Output

<samp>output</samp>
Figure 3

The samp element comes in handy for showing example output from things like command-line interfaces.

↩︎

The samp element (Figure 3) represents sample output from a computer program. Using it will render something like Output.

From the MDN documentation for the samp element:

The <samp> HTML element is used to enclose inline text which represents sample (or quoted) output from a computer program. Its contents are typically rendered using the browser’s default monospaced font (such as Courier or Lucida Console).

Variables

<var>x</var>
Figure 4

The var element won’t necessarily be used a lot, but it has its purposes.

↩︎

The var element (Figure 4) represents a variable in a math expression or programming context. Using it will render something like x.

From the MDN documentation for the var element:

The var statement declares a function-scoped or globally-scoped variable, optionally initializing it to a value.

Extended Code Samples

Small bits of inline code come in handy, but frequently, there’s a good case for longer block-level code sampes with syntax highlighting. And naturally, the system supports several options.

Fenced Code Blocks

``` rubyx = Object.new```
Figure 5

It’s tough to beat fenced code blocks for simplicity, but they don’t provide many additional options.

↩︎

Markdown’s fenced code blocks (Figure 5) provide the most convenient option in cases where a figure, filename, and/or reference are overkill.

For example, this code block was rendered using standard Markdown:

<%= code 'ruby-method-with-numbers', :ruby, numbers: true, start_line: 1, highlights: 26..34, file: 'app/models/file.rb', caption: 'This has line numbers.' do %>def section_key case [first_slug_component, second_slug_component] when [:accessibility, nil] then :accessibility when [:colophon, nil] then :colophon when [:interviews, nil] then :colophon when [:now, nil] then :now else second_slug_component endend<% end %>

It looks nice, uses the same syntax highlighting, and it’s convenient. For longer articles, though, it doesn’t provide the same level of functionality and customization as the code helper.

The Code Helper

For longer blocks of code, the code helper provides everything you could ever want for displaying rich code samples with syntax highlighting, line numbers, and optional highlighting of specific lines.

It also supports specifying a filename and the starting line number so that if a code snippet was taken from a larger file, the reader has some context where that code snippet belongs.

Due to the number of options, this sample will likely be handy on the regular for quickly remembering the syntax. (Figure 6)

app/helpers/content_helper.rb <%= code 'ruby-method-with-numbers', :ruby, numbers: true, start_line: 1, highlights: 26..34, file: 'app/models/file.rb', caption: 'This has line numbers.' do %>def section_key case [first_slug_component, second_slug_component] when [:accessibility, nil] then :accessibility when [:colophon, nil] then :colophon when [:interviews, nil] then :colophon when [:now, nil] then :now else second_slug_component endend<% end %>
Figure 6

This code block was rendered using code helper. It provides options above and beyond what’s possible with fenced code blocks. It can show/hide line numbers, change the starting line number, highlight specific lines, and specify a filename if relevant.

↩︎

That’s a full example, so here’s the breakdown on how the various options work.

Required Parameters

  • slug is a unique identifier so that the figure can have references anchored to it the same as any other figure-based element.
  • lang is the programming language to use for the syntax highlighting. The language for the code sample needs to be specified in order to ensure the correct syntax highlighting. While Rouge supports many lexers, the most frequently-used values for languages here will be a much smaller subset.

Optional Parameters

  • pull pull variants for adjusting the layout. Code figures support the figure element layout variants.
  • caption a brief description of the unique features of the code or why it is interesting/relevant.
  • numbers a boolean to override whether or not to display line numbers. If not specified, it will show line numbers when the code includes more than 5 lines of code.
  • highlights an array determining the line numbers to visually highlight in the code sample.
  • start_line the number to start with for the line numbers. If not specified, it will default to starting with 1.
  • filename the name of the file that the section of code was pulled from. When discussing multiple files, this can be helpful for avoiding confusion on where a given bit of code originated from.

Filenames, Line Numbers, and Highlights

Code samples support specifying a filename, line numbers, and highlights. All are optional, but they can provide helpful context in the case of tutorials or extended prose that involves multiple code samples.

If a filename is specified with the filename: option, it will be displayed at the top of the code sample so readers know where the code sample originated or where they should place the code in their own setup if they copy and paste it.

Line numbers can be explicitly shown or hidden for a given code sample. By default, they will be shown when the code sample includes more than 5 lines. Passing numbers: false will ensure the line numbers are suppressed no matter how many lines of code are present, and passing numbers: true will ensure they’re shown even if there’s only a single line.

When line numbers are shown, you can specify the start_line so that the line numbers will start from the specified number instead of ‘1’. You can also specify the highlights in order to draw attention to specific lines of code in the sample. You can pass a range (1..5) or array ([1,5]) of line numbers to highlight within the code sample. If start line: is specified, these line numbers will need to be adjusted accordingly.