Writing a tutorial

Utkarsh Sinha edited this page Aug 24, 2014 · 7 revisions

Here's a short guide to writing tutorials for AI Shack

The tutorial URL

A tutorial's URL is picked up from its filename. If you store a file in tutorials/this-is-my-tutorial.md, it will show up as http://aishack.in/tutorials/this-is-my-tutorial/

If you put in funky charaters (like [?!_+()]), they will be discarded. Also, make sure the URL is well formed for SEO!

Frontmatter

Every tutorial needs to have some frontmatter. It looks something like this:

---
title: "My tutorial's title"
date: "YYYY-MM-DD HH:MM:SS"
excerpt: "A brief 2-3 liner goes here"
category: "Computer vision"
author: "email@something.com"
post_image: "/static/img/tut/post-mine.png"
featured: true
series: "My tutorial is part of a series"
part: "4"
---
<actual tutorial>

Most of the fields are self explanatory.

  • featured: If set to true, displays the tutorial on the home page. The most recent 3 featured tutorials are displayed there.
  • post_image: This is the graphic displayed at the top of each tutorial
  • series: If set to a string, makes this tutorial part of a series. A series is shown as one single entity on the /tutorials/ page (with multiple page numbers)
  • part: Required if series is set to something. It lets you specify the order of the tutorial.

Writing the tutorial

The tutorial needs to be a markdown document. There are some additional tags that are available. You can look at those here: Markdown for tutorials