Hey champ! The Aardvark Garden is the Customer Happiness team’s internal testing and knowledge site. In this article, we’ll cover best practices for writing markdown articles to be included here.

Markdown syntax

This beautiful site you’re perusing has been built using Github Pages and Jekyll. If you’re reading this, we’re going to assume that you’re moderately familiar with markdown, so it’s important to note that Jekyll uses a slightly different syntax than you might be used to, called Kramdown. While we won’t be running through all of its features and idiosyncrasies here (there’s extensive documentation for that), we figured it was a good idea to highlight a couple of important bits for you as you start writing your own articles for the Aardvark Garden.

Headers

In Github-Flavored markdown, you don’t need to add a space between the pound symbol and your title when making a header. Kramdown, on the other hand, is all like “yo, put a space between those two, otherwise I’m gonna output garbage.” The space here is your friend:

### My Awesome Header

IMPORTANT NOTE! OLIVIER SAYS: DON’T USE H1s or H2s IN YOUR ARTICLES – STICK TO H3s and H4s. WITH GREATER RESTRICTION COMES INCREASED CREATIVITY.

One neat feature of Kramdown is its support for different URL targets. So, if you want your link to open in a new browser window, you’d just need to add {:target="_blank"} like this:

[This is a link](http://www.wistia.com){:target="_blank"}

Here’s a live example:

This is a link

Code Syntax

Typically, when writing a fenced code block in markdown, you’d use backticks, like this:

```
This is my code block. It solves all the problems.
```

With Kramdown, you use tildes instead:

~~~
This is my code block. It solves all the problems.
~~~

Remember that you can also impose specific syntax highlighting in your code blocks, just like you normally can with markdown. For instance, if I was putting some JavaScript in my code block and wanted to highlight the syntax, I’d just add javascript after the top set of tildes, like this:

~~~ javascript
function helpMeObiWanKenobi() {
  if (!receivedHint) {
  var correctHint = hints[id];
  receivedHint = true;
} else {
  var correctHint = hints[0];
}
  var textAnswer = document.createTextNode(correctHint);
  var textBreak = document.createElement("br");
  answer.appendChild(textAnswer);
  answer.appendChild(textBreak);
};

$("#" + playground).click(function() {
  helpMeObiWanKenobi();
});
~~~

With that specification, your code block will look all spiffy, like this one:

function helpMeObiWanKenobi() {
  if (!receivedHint) {
  var correctHint = hints[id];
  receivedHint = true;
} else {
  var correctHint = hints[0];
}
  var textAnswer = document.createTextNode(correctHint);
  var textBreak = document.createElement("br");
  answer.appendChild(textAnswer);
  answer.appendChild(textBreak);
};

$("#" + playground).click(function() {
  helpMeObiWanKenobi();
});

Note that if you’re just adding some inline code, you can still use backticks:

In this sentence, `this` word and `this` word will be converted to inline code.

In this sentence, this word and this word have been converted to inline code.

That’s it. You did it. You read through this thing, and now you’re prepared to write articles whose awesomeness will be repaid with decent styling. Here, in closing, are a few words of encouragement from our beloved CEO and resident hover-board champion, Chris Savage (watch at half-speed – it’s life-changing):