---
layout: docs
title: Writing posts
prev_section: frontmatter
next_section: pages
---

One of Jekyll’s best aspects is that it is “blog aware”. What does that mean, exactly? Well, simply put it means that blogging is baked into Jekyll’s functionality by default. For people who write articles and publish them online, this means that you can publish and maintain a blog simply by managing a folder full of text-files on your computer. Compared to the hassle of configuring and maintaining databases and web-based CMS systems, this will be a welcome change for many.

## The Posts Folder

As detailed on the [directory structure](../structure) page, the `_posts` folder in any Jekyll site is where the files for all your articles will live. These files can be either [Markdown](http://daringfireball.net/projects/markdown/) or [Textile](http://textile.sitemonks.com/) formatted text files, and as long as they have [YAML front-matter](../frontmatter) defined, they will be converted from their source format into a HTML page that is part of your static site.

### Creating Post Files

To create a new post, all you need to do is create a new file in the `_posts` folder. The filename structure used for files in this folder is important—Jekyll requires the file to be named in the following format:

{% highlight bash %}
YEAR-MONTH-DAY-title.MARKUP
{% endhighlight %}

Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is an appropriate file extension for the format your post is written in. For example, the following are examples of excellent post filenames:

{% highlight bash %}
2011-12-31-new-years-eve-is-awesome.markdown
2012-09-12-how-to-write-a-blog.textile
{% endhighlight %}

### Content Formats

The first thing you need to put in any post is a section for [YAML front-matter](../frontmatter), but after that, it's simply a case of deciding which format you prefer to write in. Jekyll supports two popular content markup formats: [Markdown](http://daringfireball.net/projects/markdown/) or [Textile](http://textile.sitemonks.com/). These formats each have their own way of signifying different types of content within a post, so you should read up on how these formats work and decide which one suits your needs best.

## Including images and resources

For people who publish articles on a regular basis, it’s quite common to need to include things like images, links, downloads, and other resources along with their text-based content. While the ways to link to these resources differ between Markdown and Textile, the problem of working out where to store these files in your site is something everyone will face.

Because of Jekyll’s flexibility, there are many solutions to how to do this. One common solution is to create a folder in the root of the project directory called something like `assets` or `downloads`, into which any images, downloads or other resources are placed. Then, from within any post, they can be linked to using the site’s root as the path for the asset to include. Again, this will depend on the way your site’s (sub)domain and path are configured, but here some examples (in Markdown) of how you could do this using the `{{ "{{ site.url " }}}}` variable in a post.

Including an image asset in a post:

{% highlight bash %}
… which is shown in the screenshot below:
![My helpful screenshot]({{ "{{ site.url " }}}}/assets/screenshot.jpg)
{% endhighlight %}

Linking to a PDF for readers to download:

{% highlight bash %}
… you can [get the PDF]({{ "{{ site.url " }}}}/assets/mydoc.pdf) directly.
{% endhighlight %}

<div class="note">
  <h5>ProTip™: Link using just the site root URL</h5>
  <p>You can skip the <code>{{ "{{ site.url " }}}}</code> variable if you <strong>know</strong> your site will only ever be displayed at the root URL of your domain. In this case you can reference assets directly with just <code>/path/file.jpg</code>.</p>
</div>

## Displaying an index of posts

It’s all well and good to have posts in a folder, but a blog is no use unless you have a list of posts somewhere for people. Creating an index of posts on another page (or in a [template](../templates)) is easy, thanks to the [Liquid template language](http://liquidmarkup.org/) and it’s tags. Here’s a basic example of how to create an unordered list of links to posts for a Jekyll site:

{% highlight html %}
<ul>
  {{ "{% for post in site.posts " }}%}
    <li>
      <a href="{{ "{{ post.url "}}}}">{{ "{{ post.title "}}}}</a>
    </li>
  {{ "{% endfor " }}%}
</ul>
{% endhighlight %}

Of course, you have full control over how (and where) you display your posts, and how you structure your site. You should read more about [how templates work](../templates) with Jekyll if you’re interested in these kinds of things.

## Highlighting code snippets

Jekyll also has built-in support for syntax highlighting of code snippets using [Pygments](../extras), and including a code snippet in any post is easy. Just use the dedicated Liquid tag as follows:

{% highlight ruby %}
{{ "{% highlight ruby"}} %}
def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end
{{ "{% endhighlight"}} %}
{% endhighlight %}

And the output will look like this:

{% highlight ruby %}
def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end
{% endhighlight %}

<div class="note">
  <h5>ProTip™: Show line numbers</h5>
  <p>You can make code snippets include line-numbers easily, simply add the word <code>linenos</code> to the end of the opening highlight tag like this: <code>{{ "{% highlight ruby linenos " }}%}</code>.</p>
</div>

Those basics should be more than enough to get you started writing your first posts. When you’re ready to dig into what else is possible, you might be interested in doing things like [customizing post permalinks](../permalinks) or using [custom variables](../variables) in your posts and elsewhere on your site.