To create content using the Theme JekyllOne for Jekyll, no deep HTML knowledge is required. The sources for all website content pages are based on the well-known top-level markup languages Asciidoc (Asciidoctor) or Markdown. Jekyll processes the Markup source code fully automated and puts out valid standalone HTML5 code.
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!
Notice for Jekyll version A major regression in We addressed this by having Jekyll scan the directory path only if the user explicitly configures the Read //jekyllrb.com/docs/configuration/#glob-patterns-in-front-matter-defaults[Glob patterns in Front matter defaults] for more details. A huge shout-out to @mmistakes for bringing this to our notice and additionally providing us with a test repository to aid in resolving the issue. Another regression reported was related to our Custom collections directory feature introduced in Users setting collection_dir to a certain directory would have altered paths to their posts still at the root of their site’s source. This roughly translated to 404 errors on URLs to their posts. Props to @localheinz for bringing this regression to our notice. We decided to resolve this by having Jekyll ignore posts and drafts at the root of the site’s source directory if the user customizes the Ergo, if you set a custom location for your collections, please ensure you move all of your collections into that directory. This includes posts and drafts as well. Your links generated by |
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.
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. |
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:
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:
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.
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 |
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:
... which is shown in the screenshot below:

Linking to a PDF for readers to download:
... you can [get the PDF]({{ site.url }}/assets/mydoc.pdf) directly.
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:
<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:
{{ 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:
---
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 ""
.
Also, as with any output generated by Liquid tags, you can pass the |
Glob patterns in Front Matter defaults
For Jekyll version >= 3.7.2
it is also possible to use glob patterns (currently limited to patterns that contain a star *
) when matching defaults. For example, it is possible to set specific layout for each special-page.html in any subfolder of section folder.
collections:
my_collection:
output: true
defaults:
- scope:
path: section/*/special-page.html
values:
layout: specific-layout