Figures represent the core feature of the publishing system and help seamlessly (and painlessly) interweave prose with images and code. The figure_element isn’t used directly, but since both visual elements and code samples rely on it, this helps provide larger context about the shared functionality.
By using ERb and helpers to implement visual and code elements, it’s easier in the future to make universal updates to the underlying markup to ensure they’re fully-accessible and making the most of modern browser features without having to individually update every figure throughout all of the prose on the site.
Types of Figure Elements
The system supports several types of figures: visual, code, and table are the primary types that the system automatically numbers sequentially. Each is rendered within a figure element and supports automatic numbering and optional figcaption content.
1. Visuals
The visual figure makes it trivial to create semantic responsive images that are optimized for file size and layout size. It has quite a few moving parts to help keep things seamless and reduce the need for manual intervention with every single image. Read the visual elements guide for details on the visual helper.
2. Code Samples
The code figure provides a clean way to customize how blocks of code are displayed based on the language, whether or not to show line numbers, and whether to highlight any of the lines in the code sample. Read the code samples guide for more information on how to include code in prose using the code helper.
3. Tables
The table figure essentially provides a figure wrapper for the purpose of referencing the table and optionall providing a short summary about the information displayed in the table when it isn’t immediately self-explanatory. Read the table samples guide for more information on how to include tables in prose using the table helper or basic table markdown.
Numbering Figures & References
When using figures, the references and associated figures are automatically numbered based on the order in which new slugs are encountered while parsing the content.
So if a figure reference occurs in the first paragraph, but the referenced figure doesn’t show up until the last paragraph, the actual figure element will still be number 1 regardless of how many other figures show up in between because its slug was the first figure referenced in the prose.
The system gracefully handles intermingling of visual , code, and table figures so that the numbering scheme handles the flow of the elements even when switching back and forth between code and images. The numbers will be sequential based on when a figure reference or figure is encountered in the prose regardless of the type of figure.
This makes it easy to move figures and references around to accommodate layout challenges without having to worry about their ordering in the page and manually keeping the numbers in sync. As long as the slugs match, the figures will stay connected to their references.
Figure References
<%= ref 'slug' %> References can be included in the prose using ref with a unique slug, and they’ll automatically be connected to the corresponding code sample with the same slug.
When figures are added, they can optionally be paired with references placed directly inline in the prose, and the system will automatically create bi-directional links between the reference and the figure. (Figure 1) If a figure does not have a reference within the prose, a backlink will not be created since there wouldn’t be anything to link back to.
The figure references make it easier to associate prose with the relevant figures so that figures don’t have to be placed in immediate proximity to the content they’re related to. A concise ref ERb helper does all the heavy-lifting. This may get a little meta, but here’s one now: (Figure 2)
<span class="ref"> (Figure <a id="figure-1-code-1-input-ref" href="#figure-1-code-1-input">1</a>)</span> When the reference is rendered, it creates the link to the corresponding figure which will then have a link back to its corresponding reference.
↩︎<%= ref 'slug-1', 'slug-2' %> References can accept multiple slugs when the prose is referring to something comparing two different figures.
↩︎While most figure references will only be referring to a single figure, there are plenty of cases where a single reference may be the reference point for multiple figures. In that case, it’s useful to pass multiple slugs to reference multiple figures. (Figures 3 & 4)
<span class="ref"> (Figures <a id="figure-1-code-1-input-ref" href="#figure-1-code-1-input">1</a> & <a id="figure-2-code-1-output-ref" href="#figure-2-code-1-output">2</a>)</span> When two references are included, they’re automatically converted to a sentence with just the right connectors regardless of whether there’s 2, 3, 4, or however many references, and ‘Figure’ is intelligently pluralized to boot.
↩︎Layout
Like most non-prose elements, figures can be arranged with the prose in different ways in order to best accommodate the ideal size of the figure and ensure they flow well with the prose. For any figure-based helper, you can add a pull variant to control the layout of the element as well as an optional modifier to affect the layout and visual styling.
<%= visual 'slug', pull: 'margin clean', alt: 'A detailed description of the visual depiction.', caption: 'A brief explanation about the context or significance of the figure.' %> Every figure element supports using the pull: keyword to specify a variant and optional modifier to adjust the figure’s layout.
Variants
Variants are the key option for controlling layout for figures, callouts, and pull/block quotes. The system supports the following four options:
measurePlaces the figure inline with and matching the width of the prose. This is the default if no variant is specified.marginPlaces the figure in the margin and uses the full width of the margin for the figure’s width.widePlaces the figure inline with content but sets the width equal to the content plus the right margin.fullPlaces the figure inline with the content but goes beyond thewidevariant to include the majority of the padding on either side to provide a little more space.
Modifiers
Modifiers provide a way to make visual adjustments to some figure elements so they work better with the layout of the prose and other nearby elements:
compactSets the figure width to auto for figures that may not need the full margin width. Pairs well with thecleanandmarginmodifiers.cleanRemoves any background color, borders, or other visual decoration for the figures. Good for visuals that stand on their own like book covers or diagrams that feel more natural without containers.
Don’t Use Too Many
Figure variations should be used sparingly. When a page has a significant number of figures present in the layout, they can be counter-productive and create significant amounts of visual noise.
As a result, instead of working with the prose, they can start to detract from it. If a large number of figures is a critical part of an article, there are some editorial options that can help reduce the noise.
- Reduce. With images, crop and zero-in on the key part. Only show the portion that’s immediately relevant. With code, are all of the lines necessary, or are there key lines that can tell the story without additional context?
- Consolidate. In some cases, multiple images can be combined into a single larger image to illustrate comparisons or simple unify loosely-related ideas into a single figure.
- Cut. Can the figure be removed completely from the article? Maybe it can be part of a different article with a laser-focus on a specific aspect.
The system is designed specifically to facillitate the frictionless use of images, code, callouts, and quotations, but when it’s super-easy, one can easily get carried away. It’s important to always remember the key message an article is trying to convey, and just like pruning words is important, it’s often help to remember to be judicious with the other elements as well.