What Are All These Files in a Jekyll Theme For

By -

Why Do Jekyll Projects Have So Many Folders?

If you’re a beginner who just cloned a Jekyll theme like Mediumish and opened the folder for the first time, your reaction might be: “What is all this?” There are folders with underscores, strange file names, and code you’ve never seen before. Don’t worry—you’re not alone. This article will guide you through each part of the Jekyll theme folder and explain what it does in the simplest way possible.

Think of the Theme Folder Like a Blog Toolkit

A Jekyll theme is like a toolbox. Each folder or file has a job. Some control the design, some handle your content, and others manage settings. Let’s go through the most important parts, one by one, so you can feel more in control instead of overwhelmed.

What's the First File You Should Look At?

Start with _config.yml. This is your site’s control panel. It has your blog’s name, description, and theme settings. You don’t need to understand everything inside it right away, but it’s the safest place to make your first change—like updating your blog title or adding your name as the author.

What Does _config.yml Control?

  • Site title and description (shown in browser or homepage)

  • Links to your social profiles

  • Settings like pagination, base URL, or custom menus

What Are Those Underscore Folders?

Folders that start with an underscore (_) are special to Jekyll. They're not shown directly on your website, but they control how your website is built.

Common Underscore Folders You’ll See:

1. _posts/

This is where your blog posts go. Each file here is one article, written in Markdown, and must start with the date in the filename. Example: 2025-07-01-my-first-post.md.

2. _layouts/

These are blueprints. A layout defines how pages look. For example, should the post have a sidebar or not? Should the title be big or small? You can pick different layouts for different pages.

3. _includes/

These are small pieces of HTML reused in many places—like the site’s header, footer, or social icons. They help avoid repeating code across pages.

4. _data/

This folder holds files like .yml or .json that store structured information—such as author bios, menu items, or project lists. Instead of hardcoding these in every file, you centralize them here.

5. _site/

This folder is auto-generated when Jekyll builds your site. It contains the final HTML that gets displayed on the web. You don’t edit this folder—it’s like the final printout from a printer.

Where Is the Homepage?

In most themes, the homepage is index.html in the root folder. This file tells Jekyll what layout to use and how to display content. For example, it might say “show the latest 5 posts” using a loop. You can safely edit the text or title here to change what people see first when visiting your blog.

What About Pages Like About or Contact?

Pages like about.md or contact.md are static pages. You can create more by simply adding a new file like projects.md and adding this at the top:

---
layout: page
title: Projects
permalink: /projects/
---

The content after that is what gets shown on the page.

What Is Front Matter and Why Is It Everywhere?

Almost every file in Jekyll starts with a few lines between triple dashes (---). This is called front matter. It tells Jekyll how to treat the file. For example:

---
layout: post
title: My First Post
date: 2025-07-01
categories: [jekyll,beginner]
---

Without front matter, Jekyll won’t know what type of page this is. Always start each content file with this section.

How Do Themes Like Mediumish Work With This Structure?

Mediumish is a pre-designed theme that uses all the pieces above to give your blog a clean, Medium-style layout. It already includes layouts, includes, and styling, so you can focus on writing posts. But you can override or change anything if you want to customize further.

If You Want to Change the Colors or Fonts:

Look inside the assets/css/ or assets/scss/ folders. These control the design. For example, there may be a file like main.scss or custom.scss. Changing a color here will affect the whole site.

What Should a Beginner Do First?

Here’s a good order to explore the project:

  1. Open and edit _config.yml to update your site title and description.

  2. Write your first post in _posts/ using the proper filename format.

  3. Edit index.html to personalize your homepage message.

  4. Preview the site locally or push to GitHub to publish.

What Makes Jekyll Different from WordPress?

In WordPress, you manage everything from a dashboard. In Jekyll, you edit text files directly. There’s no admin panel, but also no bloat. This makes Jekyll faster and gives you full control, especially if you’re comfortable editing files and using Git.

Who Is Jekyll Best Suited For?

Jekyll is great for:

  • Personal blogs

  • Documentation sites

  • Portfolios or resumes

If you’re okay learning the basics of Markdown and folder structure, Jekyll can be a rewarding long-term solution.

Final Thoughts

At first glance, the folders and files inside a Jekyll theme may feel like a maze. But once you understand their purpose—content, layout, settings, design—it starts to make sense. You don’t have to learn everything at once. Just start by writing your posts and updating your config file. Over time, you’ll grow more confident exploring the rest.