Alligator.io Style Guide

Here’s a style guide for posts on Alligator.io. The first paragraph of each post is a lead-in paragraph that’s styled automatically with the left yellow line. Posts are written in markdown.

😎 You can get in touch with us here if you're interesting in collaborating content.

The articles are short and sweet. Longer explanations are broken-down into easier to digest bullets points whenever possible.

Contents:

Jekyll Formatting & Front Matter Titles & Meta Headings Styling Text Alligator Vocabulary Bullet Points Code Snippets Code Annotations Separators Info Boxes Links File Descriptions Images & Screenshots Parting Thoughts Some Fun Emojis

Jekyll Formatting & Front Matter

Alligator.io is a Jekyll-powered website, so every post starts with some Jekyll front matter. Here’s an example of the typical front matter for a post:

---
layout: page-fullwidth
title:  "Using JavaScript to Make Crispy Bacon"
categories:
    - js
tags:
    - bacon
header: no
breadcrumb: true
meta_description: "Using the latest JavaScript techniques to properly cook your bacon."
author: john_doe
---

File names should start with the date, like this:

js/2017-02-09-crispy-bacon.md

Post Dates

You can add something like this to the front matter to add a post date that will be visible under the title:

the-date: 2017-02-27

It’s a good idea to add a date if the post is about an API that changes often. Otherwise, if the post is about something set in stone, like with vanilla JS or CSS for example, a post date is not required.

Titles & Meta:

Keep article titles short, but do include what framework or language it covers. For example: How to Cook Bacon With Vue.js.

Articles should also come with a meta description that’s 160 characters or less. The meta description should give a brief overview of what the article is about.

Headings

Use h2 and h3 headings. Capitalize h2 titles, but don’t capitalize h3 titles:

## A Great Title

Some text...

### And a great subtitle

Some more text...

Styling Text

Use em to highlight text, strong to highlight again, and code for variable and function names. For example, in markdown:

*let* is the new *var*. **let** is block-scoped.

An example where we define a `getBacon` function...

Alligator Vocabulary

Here are some ideas for Alligator-related words, as options to use for variable names instead of the traditional foo, bar & baz: nest, eggs, bite, gator, grip, belly, jaw, reptilian, meat, tail, crocodilian, bayou, gator, cayman.

Foods and animal names are also good options for words to use.

Bullet Points

Breakdown complex ideas or list of thoughts into bullets points. For example:

* *Point 1*: Text for point 1.
* *Point 2*: Text for point 2.
* *Point 3*: Text for point 3.

Becomes this:

  • Point 1: Text for point 1.
  • Point 2: Text for point 2.
  • Point 3: Text for point 3.

Code Snippets

Here are a few rules for code snippets:

  • Use 2 spaces for code indentation.
  • Don’t forget your semi-colons in JavaScript. You can omit semi-colons in TypeScript if you prefer.
  • Use single quotes in JavaScript.
  • Use newer ES6/ES7 syntax whenever appropriate. For example, use let and const instead of var.

Markup your code snippets like this:

<pre><code class="javascript">let alligator = true;

if (alligator) {
  console.log('It bites!');
}

// ...</code></pre>

Use <code class="nohighlight">...</code> to turn off syntax highlighting.

For markup that includes html markup, you can use the ``` syntax and the html entities will be converted automatically:

```html
<input type="text">
<button type="submit">
```

Breakdown long lines of code or markup:

<!--  Avoid this -->
<button md-icon-button [md-menu-trigger-for]="menu"><md-icon>more_vert</md-icon></button>

<!-- Do this instead -->
<button md-icon-button [md-menu-trigger-for]="menu">
  <md-icon>more_vert</md-icon>
</button>

<!-- Or even this -->
<button md-icon-button
        [md-menu-trigger-for]="menu">
  <md-icon>more_vert</md-icon>
</button>

Using {{ mustache }} syntax in your code snippets? Escape it like this:

{% raw %}{{ mustache }}{% endraw %}

Code Annotations

You can highlight specific sections of code by wrapping it in a span with the code-annotation class:

let alligator = true;

if (alligator) {
  <span class="code-annotation">console.log('It bites!');</span>
}

And here’s the result:

let alligator = true;

if (alligator) {
  console.log('It bites!');
}

Separators

Use horizontal lines for separations:

---

It’ll look like this:


Info Boxes

You can add info boxes like this:

<p class="info-box">
  I am an info box for a special note about the subject on hand.
</p>

Note that markdown doesn’t get evaluated inside these info boxes. So instead of something like *something*, you’ll want to use markup like <em>something</em>.

Here’s now an info box looks like:

I am an info box for a special note about the subject on hand.

Internal links should be relative links.

<!--  Avoid this -->
[Fr unit](https://alligator.io/css/css-grid-layout-fr-unit/)

<!--  Do this instead -->
[Fr unit](/css/css-grid-layout-fr-unit/)

File Descriptions

Some code snippets are easier to understand when given a file name, and this can be included by adding the following markup right before a code snippet:

<p class="file-desc">Module: <span>bacon.js</span></p>

Or with just the file name like this:

<p class="file-desc"><span>bacon.js</span></p>

Here’s how it looks like:

bacon.js

export default function getBacon() {
  console.log('Bacon for you! 🐖');
}

Images & Screenshots

Image are placed inside a paragraph with centered text like this:

<p class="text-center">
 <img src="/images/js/cooking-bacon.png" width="600" height="400" class="slight-shadow" alt="Crispy bacon with JavaScript">
</p>

If the image appears later in the post, you can use the data-original attribute instead of src and the image will be lazy-loaded:

<p class="text-center">
 <img data-original="/images/js/cooking-bacon.png" width="600" height="400" class="slight-shadow" alt="Crispy bacon with JavaScript">
</p>

To make for an easier workflow, only one image format is provided, so the image should be twice the size so that it looks sharp on retina displays. An image that displays at 600px wide should therefore be saved at 1200px wide. Jpegs can be saved with a quality of around 50%-60% to make the images as small as possible.

SVGs are of welcome, for graphs and charts.

Parting Thoughts

If you have one last funny or insightful thought for the post, it can be included like this:

<p class="t70 text-center">
  👉 Now all that's left is to make sure the bacon is crispy enough!
</p>

Here’s the result:

👉 Now all that's left is to make sure the bacon is crispy enough!

Some Fun Emojis

🐊 🦄 🤓 🎩 👉 🌵 ☠ 💣 🐼 💪 🐷 ✨ 🚀 🌈 🐸 🐙 😷 😍 🤖 👽 🐥 🐢 🐟 🐿

✖ Clear

🕵 Search Results

🔎 Searching...