We’ve invested a lot of effort in ensuring that our writing is helpful, engaging, easy to read on any device, and flexible. This guide helps provide the tools to make composing blog posts and long-form educational content as easy as possible.

Markdown & Markup

In general, we should use markdown for the bulk of the content. For some of the richer elements like pull quotes, figures, and code samples you may need to use markup. The following guidelines may help in some situations with multiple options.

  1. If an element can easily be rendered with markdown, always use the markdown version over the markup version. ex. --- instead of <hr>
  2. Always use double quotes rather than single quotes on element attributes.
  3. Don’t include a trailing slash in self-closing elements. ex. <hr> instead of <hr/> or <img src=""> instead of <img src=""/>
  4. Don’t omit optional closing tags. i.e. </li> or </body>

Some of the original content may not follow these guidelines. This is simply a matter of legacy content only being updated where necessary. These guidelines should be the standard for new content.

Smart Quotes

Jekyll/Markdown will automatically parse regular quotes into smart quotes, but when using quotes inside of markup such as a definition list or regular (non-markdown) list, make sure to use HTML entities for smart quotes. &ldquo; and &rdquo; for left and right double quotes and &lsquo; and &rsquo; for left and right single quotes.

Figures

More than anything, our content is designed to support visual aids. This includes photos, screenshots, charts, graphs, illustrations, and even animated GIF’s when they help illustrate an idea or interaction.

View figures samples…

Options

No class specified
This is the default behavior and intended primarily to support legacy content. In this scenario, the figure is placed inline with the text with the same margins, background color, and padding.
pull
Increases the width of the figure beyond the margins of the text but not the full-width of the page's whitespace.
pull-full
Increases the width to fill the available white space horizontally. This implicitly removes the background color and padding as full-width figures are intended to be larger design elements that blend seamlessly into the content.
pull-left or pull-right
These narrow the width of the figure and pull it outside of the margins of the text to the left and right respectively.
pull-clean
This can be used by itself or in conjunction with pull, pull-left, and pull-right to remove the background color and padding for images that work better without a visual container.

Figure References

We explicitly include figure references within the body of the content so that it’s easier to associate content with the relevant figures. For convenience, the word “figure” as well as the parentheses can be omitted from the markup and are inserted via CSS.

<span class="ref">1</span>

Figcaption

Unless an image is purely decorative, it should include a caption and reference number. The caption should explain the significance of the figure rather than explain what the figure is. The alt attribute on the image should be used for describing the contents of the image.

Similar to the inline figure reference, the word “figure” can be omitted from the markup because it will be handled with CSS.

<figure>
  <img src="image.svg" alt="Description">
  <figcaption><b>1</b> This is the caption text.</figcaption>
</figure>

Figure Content

“Figures” is a rather large catch-all phrase for a wide variety of visual content. As such, it’s useful to consider the subtle differences and purposes of those different types of content rather than place them all in a grey box with a caption.

Screenshots
Composition and Framing. In general, screenshots should not use the pull-clean option if they include large amounts of text. This can make it difficult to discern between the content of the screen shot and content of the article.
Animation. Animation can and should be used to illustrate interaction, but the clips should be short and focused on a single interaction. If the interaction spans multiple pages or events, video is often better.
Size/Dimension/Resolution Guidelines. Figures that use pull-full can be up to 1280 pixels in width. To support HighDPI displays, these figures would likely work best at a resolution width of 2560 or higher.
Recommended Formats. Due to their simplicity, screenshots will often have the smallest total size as GIF's, but JPG and PNG can also be used where needed.
Photos
Composition and Framing.
Usage.
Size/Dimension/Resolution Guidelines.
Recommended Formats.
Charts and Graphs
Composition and Framing. With very rare exceptions, most visualizations should use the full horizontal space available to them. (pull-full)
Typography. Based on the default target width of 1200 pixels, most typography should be set in Gotham Narrow ScreenSmart at 18 point with a line-height of approximately 1.4.
Styling. Axes should be set at a width of 1 pixel while the graph lines should be 2 pixels.
Colors. Visualizations should be predominantly grey scale unless there's an explicit need to add color.
Size/Dimension/Resolution Guidelines. Charts and graphs should be designed to a width of 1200 pixels. Due to the fact that SVG is scalable, it's important to make sure that the graphics are always designed at a consistent size so that the typography is consistent from on visualization to the next.
Recommended Formats. Charts and graphs should always be in the SVG format.
Illustrations
Composition and Framing.
Usage.
Recommended Formats
Sketches
Composition and Framing. When photographing sketches for use in an article, the photo should always be straight on and never taking at an angle or with any depth of field for artistic purposes. Sketches are content and should be photographed as cleanly as possible for simple translation to the articles.
Usage.
Size/Dimension/Resolution Guidelines.
Recommended Formats.

Blockquotes

We support two kinds of blockquotes. Regular blockquotes where the quotation is a key part of the content, and pull quotes for emphasizing key points from the content and providing a level of decoration to the content.

View blockquotes samples…

Options

No class specified
This is the default behavior and intended to be used for content-oriented quotes.
pull
Increases the width of the figure beyond the margins of the text but not the full-width of the page's whitespace. Pull quotes should only quote content from the page for emphasis and decorative purposes.
pull-left or pull-right
Similar to pull quotes, but these narrow the width of the blockquote and pull it outside of the margins of the text to the left and right respectively.

Cite

Content blockquotes can include a cite element to acknowledge the original speaker. When using multiple content blockquotes from the same source article, it’s not necessary to include the cite as long as the original source of the quoted content is clearly referenced elsewhere in the content.

Quoting Longer Passages

Normal blockquotes can be used for either a single paragraph of content or multiple paragraphs, including lists. When quoting longer passages, however, the contents of the blockquote must use markup instead of markdown.

Pull Quotes

Pull quotes are designed to emphasize key points in an ornamental way. They can use pull, pull-left, or pull-right. When using a pull quote, the cite should not be included as the quote is implied to be from the source material.

Asides

While most of our blog posts should be short-form content, occasionally, our longer form stuff can benefit from brief callouts to draw attention to key points, warnings, or interesting tidbits. Enter the aside element.

You can think of asides as a way to enable someone to skim an article but still gain actionable value from the ideas within. Use them to reinforce ideas and draw attention to key points that are easily overlooked.

View asides sample…

Options

pull
Increases the width of the figure beyond the margins of the text but not the full-width of the page's whitespace.
pull-left or pull-right
These narrow the width of the figure and pull it outside of the margins of the text to the left and right respectively.
pull-note
You can think of notes as the sort of thing that someone would be benefit from jotting down if the content was a lecture. In someways, these are very similar to pull quotes but designed to be summaries of key points.
pull-takeaway
Takeaways are for actionable advice or next steps after reading something. So even if an article or page is brief, it's often handy to use a takeaway to make it crystal clear how the reader can apply the information from the article.
pull-warning
Warnings are a way to anticipate common problems and draw attention so that readers aren't unpleasantly surprised. For instance, if we talk about an experimental CSS technique, it wold be helpful to include warnings about browser compatibility so the reader isn't disappointed when they go to implement it and find out that it doesn't work well in older browsers.

Code

There are two ways that we use the code tag. First, you can use it inline to highlight code samples similar to samp and kbd. Second, you can use it indirectly by leaning on Jekyll’s built-in Pygments code syntax highlighting with code blocks using {% highlight ruby %} and {% endhighlight %}.

View code samples…

Highlight Options

The Pygments highlight command accepts two parameters. The first is the language to be used to parse the contents. ex. ruby, CSS, etc. The second is an optional command to show line numbers.

{lang}
Let Pygments know what language the code is in.
linenos
This will prepend line numbers to the code snippet. Unfortunately, the line numbers make copying and pasting a tad tedious, so it's best to avoid using this unless you explicitly need to reference line numbers within your writing.

Here’s a quick reference for some of the supported languages/markup More languages are supported, but these are the ones we’re more likely to use in our writing.

Layout Options

For longer code blocks, you may want more horizontal space. In these cases, the highlight calls can be wrapped in a div with either or both of the following:

pull
At full-width, this will provide approximately 80 characters of horizontal space. It's likely to be the best choice for most scenarios that need more space.
pull-full
In the event you're working with some code with really long lines, you can go crazy with this, and the code block will expand horizontally to fill the width of the content area. This could almost be considered a design element in cases where the code is a significant portion of the content. In general, you should probably avoid this, but it's here if you need it. And, if you do need it, given it's size, it's generally best to include line numbers when using this option.

Samp & Kbd

In addition to code blocks, there are also times where we’ll want to call out input or output inline with the content. For these, samp indicates sample output while kbd represents keyboard input, or commands that someone would type.

View samp/kbd sample…

Headings

All of the content pages are designed to fully support all six levels of headings. Despite the availability, you should focus on keeping heading use beyond level three to a minimum.

View headings sample…

Lists & Nested Lists

We have several different type of lists all of which render the list items outside of the margin for cleaner text alignment with nearby content. You can use ol, ul, and modify these with classes.

checklist
Will change the preceding icons to checkmarks.
roman
Will change an ordered list to use 'I.', 'II.', 'III.', etc.
latin
Will change an ordered list to use 'A.', 'B.', 'C.', etc.

View lists sample…

Horizontal Rules

Given the target length of our blog posts, it’s unlikely that horizontal rules will be necessary or useful in day-to-day writing. However, they can be very handy when working on some of the other longer-form pages on the site.

A horizontal rule should generally only be used for a change of voice or a logical break in the train of thought. For instance, we use them with customer stories to signal the transition from us talking about the customer to the customer talking about their own usage.

View horizontal rule sample…

Ins & Del

Occasionally, you might have to make an edit to a blog post. If it’s a change that updates the meaning of the content, you’ll want to make sure to use ins and del tags so that it’s clear to the reader when a passage has been materially changed. If it’s a simple typo or edit that doesn’t change the meaning, there’s no need to use these tags.

View ins/del sample…

Abbr

While the element is technically “abbreviation,” it’s also used for acronyms. The generally accepted practice is to include the title attribute on the first use of a given abbreviation in an article and to use the element without the title for subsequent instances of the same abbreviation.

View abbr sample…

Footnotes

Footnotes should be used in place of parenthetical comments. Since you’re writing online, linking directly to the sources is best. In some cases, like books, it’s better to provide the reference and book information, ideally with a link to Amazon or the book’s web site so the reader can easily read more if they’re interested.

View footnotes sample…

Post URLs

Linking to other posts within Jekyll can be done with the post_url tag.

For Blog Posts

{% post_url /blog/2014-05-21-name-of-post %}

For Changelog Posts

{% post_url /changelog/2014-05-21-name-of-post %})

These can also be used within markdown links.

[Name of Link]({% post_url /blog/2014-05-21-name-of-post %})

Embedded Content

Tweets

Gists

Jekyll has built-in Gist support. So you can include Gists easily with the gist command.

{% gist garrettdimon/931c1c8d465a04042403 %}

And you can optionally specify a file name to display with the Gist at the end.

{% gist garrettdimon/931c1c8d465a04042403 garrett.rb %}

Codepens

YouTube

Wistia

Speakerdeck