* [Syntax explanation](http://tutorials.github.com/pages/explanation.html)

All Tutorials

You can [browse all tutorials here](/pages/table-of-contents.html).

* [Syntax explanation](/pages/explanation.html)

layout: default

title: Test

ignore: true

This site works by using [Github Pages](http://pages.github.com/) to automatically generate and serve content. Github Pages works by using by using [Jekyll](https://github.com/mojombo/jekyll), a "blog-aware, static site generator in Ruby." Since it's a completely static site, all interactions are done through javascript on a per-page basis.

All tutorials are stored in the `/pages` subdirectory of the repo. Although jekyll supports several different markup languages such as markdown, textile, etc., tutorials.github.com has only been tested using markdown (for now).

Since Github Pages are (unfortunately) not parsed using [Github Flavored Markdown](http://github.github.com/github-flavored-markdown/), we use the [kramdown](https://github.com/gettalong/kramdown)'s extended markdown syntax to enable things like syntax highlighting and allowing markdown parsing _within_ an html tag.

Tutorials have, at a minimum, the following structure:

{% highlight html %}

<div markdown="1" class="tutorial" data-facets='{"some": "json"}'>

some _markdown_ content

</div>

{% endhighlight %}

Let's explore each in more detail.

These data attributes that are used to list key-value pairs that javascript uses to "facet" the document with. We store JSON because jQuery automatically converts HTML5 data attributes into `camelCase`, so we'd lose formatting.

The `markdown="1"` attribute to tell kramdown to parse the content of the divs as markdown instead. Because of this internal parsing, is it recommended to outdent the content inside the div (that is, type your content without leading whitespace), like in the example above.

Tutorial divs should have `class="tutorial"` to separate them from internally-nested divs. I haven't tested nesting divs, but they should work.

We parse all the tutorials on a page and generate a sidebar so that users can drill-down to the most relevant tutorial. For example, a document like this:

{% highlight html %}

<div markdown="1" class="tutorial" data-facets='{"Operating System": "OS X", "Package Management": "Homebrew"}'>

...

</div>

<div markdown="1" class="tutorial" data-facets='{"Operating System": "OS X", "Package Management": "Macports"}'>

...

</div>

<div markdown="1" class="tutorial" data-facets='{"Operating System": "Ubuntu", "Package Management": "Source"}'>

...

</div>

{% endhighlight %}

should show the following sidebar:

Operating System (2)

OS X (2)

Ubuntu (1)

Package Management (3)

Homebrew (1)

Macports (1)

Source (1)

If you clicked on the "Source (1)" `li` then you should see this:

Operating System (1)

Ubuntu (1)

Package Management (3)

Source

First we need to [https://github.com/tutorials/tutorials.github.com/fork_select](fork the repo). Then we need to clone it:

{% highlight sh %}

git clone git@github.com:some_user/tutorials.github.com.git

{% endhighlight %}

Now we need to install some gems using bundler:

{% highlight sh %}

cd tutorials.github.com

bundle

{% endhighlight %}

Then start the jekyll server:

{% highlight sh %}

jekyll --server --auto

{% endhighlight %}

Now you can browse to [http://localhost:4000](http://localhost:4000) and see the site running locally.

{% highlight sh %}

jekyll --server --auto

{% endhighlight %}

Creating a new tutorial is easy. All you need to do is create a new file in the `pages` directory, but it's a lot easier if you just start from the `template.md` file:

{% highlight sh %}

cp pages/template.md pages/my-new-tutorial.md

{% endhighlight %}

Then just follow the guide and `pages/hello-world.md` as an example.

Once you're done (and it looks good when running locally), send me a pull request and I'll merge in your new page, regenerate the table of contents and other cleanup, and then push it to github.

layout: default

title: Template

ignore: true

Introductory content: Salvia freegan pickled post-ironic. Hoodie mcsweeney's beard, lomo aesthetic semiotics echo park pitchfork typewriter. Fanny pack organic 3 wolf moon shoreditch. Swag cardigan thundercats, marfa authentic fap gastropub small batch scenester.

Portland quinoa hella. Biodiesel forage pickled bushwick fingerstache godard. Put a bird on it tofu aesthetic organic flexitarian.

Now here are two tutorials:

<div markdown="1" class="tutorial" data-facets='{"Language": ["Ruby", "JRuby"]}'>

{% highlight ruby %}

puts "Hello, World!"

{% endhighlight %}

</div>

<div markdown="1" class="tutorial" data-facets='{"Language": "C"}'>

{% highlight c %}

#include <stdio.h>

int main(void)

{

printf("Hello, World!");

return 0;

}

{% endhighlight %}

</div>