How Do You Structure Blog Posts in Jekyll for GitHub Pages

By -

When you start creating a blog with Jekyll on GitHub Pages, one of the first things you will encounter is the _posts folder. This directory is where all of your blog articles live, and understanding how it works is essential for publishing content the right way. Many beginners ask questions like: “Why do I need this special folder?” or “Why does the file name need a date?” In this guide, we will decode the _posts directory so that you can structure your content properly and avoid common mistakes.

Essential Topics We Will Cover

What role does the _posts folder play in Jekyll

The _posts folder is the default location for all blog content in a Jekyll site. Jekyll automatically looks inside this folder when generating your blog pages. Any Markdown or HTML file stored here will be treated as a post and displayed in chronological order, with the most recent post appearing first. This automatic ordering is what makes Jekyll a natural choice for building blogs.

Without the _posts folder, Jekyll would not know which content belongs to your blog. It would treat everything as a regular page instead. That is why understanding and using this directory correctly is critical if your goal is to run a blog on GitHub Pages.

Why does Jekyll require a specific naming convention

Every file inside the _posts directory must follow a strict naming convention:

YEAR-MONTH-DAY-title.md

For example:

2025-09-25-first-jekyll-post.md

The date at the beginning tells Jekyll when the post was published, and the slug (the text after the date) determines the URL of the post. This rule helps Jekyll automatically sort your posts and generate clean permalinks without extra work.

If you forget the date or mistype the format, Jekyll will ignore the file completely. This is one of the most common beginner mistakes, so always double-check your file names before committing to GitHub.

How front matter works and why it matters

Each post in Jekyll begins with a section called “front matter.” This is a block of YAML at the top of your file, wrapped in triple dashes:

---
title: "My First Blog Post"
date: 2025-09-25
categories: [jekyll,blogging]
tags: [jekyll-tutorial,markdown,github-pages]
description: "This is my very first Jekyll blog post."
---

The front matter gives Jekyll important details about your post, such as its title, publication date, and metadata. Without it, Jekyll would not know how to display your article properly. Adding categories and tags also makes it easier to organize your posts and improve SEO.

Think of front matter as a label on a package. The content of the package may be your article, but the label tells everyone (including search engines) what it contains and where it belongs.

Tips for writing and formatting content in posts

Inside your Markdown file, you can write content just like you would in any blogging platform. Jekyll supports Markdown by default, which means you can add headings, paragraphs, lists, links, and images easily. Here are some tips for structuring your content:

  • Use ## and ### for subheadings to break up long text.
  • Write short paragraphs for readability.
  • Add bullet points or numbered lists when explaining steps.
  • Include images by placing them inside an assets folder and linking to them in your Markdown.

Good formatting not only makes your posts easier to read but also helps Google understand the structure of your content. This is key to making your blog posts SEO-friendly.

How to organize posts by topics and categories

Categories and tags are powerful tools in Jekyll. By assigning categories in the front matter, you can group related posts together. For example, you might have categories like tutorials, reviews, and case-studies. Tags, on the other hand, are more specific keywords like jekyll-config or liquid-templates.

Organizing your content this way not only helps your readers navigate your blog but also signals to search engines that your site is well-structured. Over time, this organization will improve your SEO and make your blog easier to maintain.

Using drafts vs publishing posts

Sometimes you may not be ready to publish a post immediately. Jekyll provides a _drafts folder where you can store unfinished posts without a date in the filename. Drafts are not published unless you run Jekyll with the --drafts option.

This workflow allows you to experiment and refine your articles before making them public. Once you are ready, simply move the draft into the _posts folder, give it a proper date, and it will go live on your site.

By default, Jekyll generates post URLs based on their filename. For example, 2025-09-25-first-jekyll-post.md becomes /2025/09/25/first-jekyll-post.html. You can customize this behavior in your _config.yml file using the permalink option.

For instance, if you prefer shorter URLs, you might use:

permalink: /:title/

This setting would make the post URL /first-jekyll-post/ instead of including the date. Shorter URLs are often more user-friendly and easier to share, though including dates can be useful for blogs where the publication timeline matters.

SEO considerations when structuring your blog content

Search engines love clean and well-structured content. To optimize your Jekyll posts for SEO, make sure to:

  • Write unique meta descriptions in your front matter.
  • Use descriptive file names that reflect your topic.
  • Organize posts into logical categories and tags.
  • Link between related posts to keep readers engaged.

These practices will help your GitHub Pages blog rank better in search results and attract more readers over time. Remember, SEO is not about tricking Google—it is about making your content easy to understand for both readers and search engines.

Common mistakes to avoid with Jekyll posts

Beginners often run into these issues when working with the _posts folder:

  • Forgetting the correct date format in file names.
  • Leaving out required front matter fields like title.
  • Accidentally saving drafts in the wrong folder.
  • Breaking Markdown syntax by mixing spaces and tabs.

Avoiding these mistakes will save you hours of frustration and help you publish your content smoothly on GitHub Pages.

Where to go after learning the basics of posts

Now that you understand the basics of the _posts folder, you are ready to move deeper into Jekyll’s directory structure. The next logical step is learning about the _layouts directory, which controls how your posts are displayed. By combining well-structured posts with flexible layouts, you can create a blog that looks professional and scales with your content.

Remember, the _posts folder is not just a storage location. It is the foundation of your Jekyll blog. By mastering it early, you set yourself up for success as you explore more advanced features.

Final Thoughts

The _posts folder might seem simple, but it carries a big responsibility. It organizes your content, defines your URLs, and gives Jekyll the structure it needs to display your blog correctly. By following the rules of naming, using front matter wisely, and keeping SEO in mind, you can publish professional blog posts without relying on complex tools. This is the true power of Jekyll: simplicity and control in one place.

What Should You Do Next

Take a moment to create your first post inside the _posts folder. Use the proper filename format, write a meaningful front matter, and experiment with different permalink styles. Once you are comfortable, move on to exploring layouts, which will help you customize how your posts appear. With consistent practice, you will quickly build confidence in managing your Jekyll blog on GitHub Pages.