layout: page description: Manage and Write Blog Posts with Jekyll
title: Blog Posts tagline: Manage and Write Blog Posts with Jekyll
group: pages toc: true
:website: jekyllrb.com/docs/posts/ :revnumber: 3.2.1
//Ref :liquid-date-formats: docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date
- [write-posts]
-
Managing posts¶ ↑
One of Jekyll’s best aspects is that it is `blog aware`. What does this mean, exactly? Well, simply put, it means that blogging is baked into Jekyll’s functionality. If you write articles and publish them online, you can publish and maintain a blog simply by managing a folder 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!
- [posts-folder]
-
The Posts Folder¶ ↑
As explained on the directory structure page, the `_posts` folder is where your blog posts will live. These files are generally Markdown or HTML, but can be other formats with the proper converter installed. All posts must have YAML Front Matter, and they will be converted from their source format into an HTML page that is part of your static site.
NOTE: The Posts Folder `_posts` contains your dynamic content, so to speak. The naming convention of these files is important, and must follow the format: `YEAR-MONTH-DAY-title.MARKUP`. The permalinks can be customized for each post, but the date and markup language are determined solely by the file name.
- [create-posts]
-
Creating Post Files¶ ↑
To create a new post, all you need to do is create a file in the `_posts` directory. How you name files in this folder is important.
Jekyll
requires blog post files to be named according to the following format:- source, bash
YEAR-MONTH-DAY-title.MARKUP
Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. For example, the following are examples of valid post filenames:
- source, bash
2015-12-31-new-years-eve-is-awesome.md 2016-02-12-how-to-write-a-blog.textile
Content Formats¶ ↑
All blog post files must begin with YAML Front Matter. After that, it’s simply a matter of deciding which format you prefer.
Jekyll
supports Markdown out of the box, and has myriad extensions for other formats as well, including the popular Textile format. These formats each have their own way of marking up different types of content within a post, so you should familiarize yourself with these formats and decide which one best suits your needs.- NOTE
-
¶ ↑
Content processors can modify certain characters to make them look nicer. For example, the smart extension in Redcarpet converts standard ASCII quotation characters to curly, Unicode ones.
In order for the browser to display those characters properly, define the charset meta value by including `<meta charset=“utf-8”>` in the `<head>` section of your HTML layout.
¶ ↑
NOTE: Markup languages like Asciidoc use some often used characters, like the underscore `_` for the posts folder `_posts` to markup e.g. formatting. Typically all those markups comes in pairs like `_italic_` to format something e.g. italic. If you note for exammple a single underscore with Asciidoc, the engine will interprete the undercore as the beginning of a italic formatted sequence and and your following text will look very strange - this is because no closing underscore follows. To prevent Markup engines to (mis-)interprete those (single) characters (with no special meaning), write them as the `HTML Entity for the ASCII character` like `A` for an uppercase `A`. Don't miss to place a colon `;` at the end!
Including images and resources¶ ↑
Chances are, at some point, you’ll want to include images, downloads, or other digital assets along with your text content. While the syntax for linking to these resources differs 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 are 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:
- source, bash
... which is shown in the screenshot below: 
Linking to a PDF for readers to download:
- source, bash
... you can [get the PDF]({{ site.url }}/assets/mydoc.pdf) directly.
TIP: Link using just the `site root URL`. You can skip the `{{ site.url }}` variable if you know your site will only ever be displayed at the root URL of your domain. In this case you can reference assets directly with just `/path/file.jpg`.
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. Creating an index of posts on another page (or in a template) is easy, thanks to the Liquid template language and its tags. Here’s a basic example of how to create a list of links to your blog posts:
- source, html
<ul> {% for post in site.posts %} <li> <a href="{{ post.url }}">{{ post.title }}</a> </li> {% endfor %} </ul>
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 with
Jekyll
if you want to know more.Note that the post variable only exists inside the for loop above. If you wish to access the currently-rendering page/posts’s variables (the variables of the post/page that has the for loop in it), use the page variable instead.
Post excerpts¶ ↑
Each post automatically takes the first block of text, from the beginning of the content to the first occurrence of `excerpt_separator`, and sets it as the post.excerpt. Take the above example of an index of posts. Perhaps you want to include a little hint about the post’s content by adding the first paragraph of each of your posts:
- source, bash
{{ post.excerpt | remove: '<p>' | remove: '</p>' }}
If you don’t like the automatically-generated post excerpt, it can be explicitly overridden by adding an excerpt value to your post’s YAML Front Matter. Alternatively, you can choose to define a custom `excerpt_separator` in the post’s YAML front matter:
- source, bash
excerpt_separator: <!–more–>
This is the text to excerpt <!–more–>
All following is out-of-excerpt
You can also set the `excerpt_separator` globally in your `_config.yml` configuration file. Completely disable excerpts by setting your `excerpt_separator` to `“”`.
- NOTE
-
¶ ↑
Also, as with any output generated by Liquid tags, you can pass the `| strip_html filter` to remove any html tags in the output. This is particularly helpful if you wish to output a post excerpt as a `meta=“description”` tag within the post head, or anywhere else having html tags along with the content is not desirable.
¶ ↑