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 Colors 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...

Colors

Here’s a breakdown of some the site’s colors, which can be useful for SVG graphics. Click a value to copy it to the clipboard:

Greens

#008f68
rgba(0,143,104,1)
#6DB65B
rgba(109,182,91,1)
#4AAE9B
rgba(74,174,155,1)

Yellows

#FAE042
rgba(250,224,66,1)
#EFBB35
rgba(239,187,53,1)
#DFA612
rgba(223,166,18,1)

Can't copy, hit Ctrl+C!

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!');
}

To highlight whole blocks of code, use the block-annotation class:

let upper = (str) => str.toUpperCase();

let getFood = (foodChoice = 'bacon') => {
  return (modifierFn) => {
<span class="block-annotation">    if (foodChoice !== 'bacon') {
      return `Not sure about ${ foodChoice }.`;
    } else {
      return `Yes, some ${ modifierFn('bacon') } please!`;
    }</span>
  }
}

console.log(getFood()(upper)); // Yes, some BACON please!

White-space at the first line of the code block needs to be included inside the block-annotation span. Here’s the result:

let upper = (str) => str.toUpperCase();

let getFood = (foodChoice = 'bacon') => {
  return (modifierFn) => {
    if (foodChoice !== 'bacon') {
      return `Not sure about ${ foodChoice }.`;
    } else {
      return `Yes, some ${ modifierFn('bacon') } please!`;
    }
  }
}

console.log(getFood()(upper)); // Yes, some BACON please!

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.


You can also use warning boxes:

<p class="info-box warning">
  You're entering the danger zone!
</p>

You're entering the danger zone!

…and success boxes:

<p class="info-box success">
  Your app is now ready for production!
</p>

Your app is now ready for production!

Internal links should be relative:

<!--  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...