What is in My Jekyll Folder

-

If you've just started with Jekyll and GitHub Pages, opening up your project folder might feel a bit like a treasure hunt. There are a bunch of files and folders, some starting with an underscore and some not. It can be confusing at first, but each part has a specific job. Understanding this structure is the key to building a clean, well-organized website that is easy to manage and grow over time. This guide will walk you through the most important files and directories so you can start creating with confidence. We’ll break down what each piece does, how they work together, and why a good structure is so important for your site's long-term health.

Table of Contents

Jekyll’s power comes from its convention-over-configuration philosophy, meaning it expects certain files to be in certain places to work correctly. By learning this system, you’ll spend less time figuring out where things go and more time focusing on your content. Whether you're building a simple blog or a documentation site, this foundational knowledge will be your best friend. This setup also makes it very easy for GitHub Pages to understand how to build your site without any extra steps, making the entire process seamless.

The Main Files and Folders

The Jekyll Configuration

At the very heart of any Jekyll site is the _config.yml file. This file is your control center. It's where you define global settings for your website, from the site's title and description to the base URL and permalink structure for your posts. Think of it as the brain of your operation; it tells Jekyll how to behave and how to process all the other files. You can also specify which plugins to use and how to handle different types of content here. It's important to keep this file clean and organized because any change you make here will affect the entire site. For example, if you want to change your site’s name, you do it here, not on every page manually.

Another crucial file is Gemfile. While not a core Jekyll file itself, it manages the software libraries, or "gems," that your Jekyll site depends on. This is where you would list the Jekyll gem itself, along with any plugins you want to use, like a sitemap generator or an image optimization tool. The Gemfile.lock is automatically generated and locks the specific versions of these gems, ensuring that your site builds consistently every time, whether you're building it on your local machine or on GitHub Pages. You don't usually need to edit this file, but it's good to know why it's there.

The Posts and Pages

Content is king, and in Jekyll, your content lives in a few key places. For blog posts, all your files go inside the _posts directory. These files must follow a specific naming convention: YYYY-MM-DD-your-post-title.md. This format is not just for organization; it's how Jekyll determines the post’s date and URL. Jekyll automatically processes these files and turns them into blog posts on your site. The content itself is written using Markdown, which is a simple, easy-to-read text format that converts to HTML.

For all other content that isn't a blog post, you create files or folders directly in the root directory. These are your "pages." A file named about.md in the root directory will become an "About Us" page at the URL /about/. Similarly, you can create subdirectories like docs/ and place files inside, and Jekyll will mirror that structure in your final website. This simple system makes it very clear where your content lives and how it will appear on the web.

.
├── _config.yml
├── _posts/
│   ├── 2024-01-01-my-first-post.md
│   └── 2024-01-05-my-second-post.md
├── about.md
├── contact.html
└── index.md

Other Important Parts

Templating with Layouts

How does Jekyll know what your pages should look like? This is where the _layouts directory comes in. Inside this folder, you'll find HTML templates that define the overall structure of your site. For example, you might have a default.html layout that includes the header, navigation, and footer for your entire site. You might also have a post.html layout for blog posts and a page.html for static pages. These templates use a powerful templating language called Liquid to pull in content from your Markdown files. By using layouts, you avoid repeating the same HTML code on every single page, making your site much easier to maintain.

When you create a new post or page, you simply specify which layout it should use in the YAML front matter at the top of the file. This tells Jekyll to take your content and insert it into the correct template. This separation of content and presentation is a core principle of Jekyll and helps you keep your site organized and consistent. If you ever want to change the look of all your blog posts, you only need to edit one file: the post.html layout.

Reusable Components with Includes

Sometimes you have small chunks of HTML that you want to reuse across multiple layouts or pages, like a footer or a social media icon list. Instead of copying and pasting this code everywhere, you can place these reusable components inside the _includes directory. Each file in this folder can then be "included" wherever you need it using a simple Liquid tag. This keeps your code clean and helps you avoid redundancy. If you need to update a component, you just change the file in _includes, and the change will be reflected everywhere it’s used.

For instance, you could have a file named _includes/footer.html that contains your site's footer. Then, in your _layouts/default.html file, you would just add {% include footer.html %}. This method is incredibly useful for building complex websites while keeping the code manageable and easy to follow. It also makes it much easier to collaborate with others since the code is logically separated into smaller, more focused pieces.

What About My Assets?

Any file that doesn't start with an underscore—like your CSS stylesheets, JavaScript files, or images—is a static asset. Jekyll will simply copy these files directly to the final website folder without processing them. A common practice is to create a folder at the root level, often named assets or images, to store all of these files. For example, you might have an assets/css/style.css file and an assets/images/logo.png file. When Jekyll builds your site, these files will appear in the exact same location inside the final _site directory.

This simple approach to handling assets means you don't have to worry about any special configuration for them. You can link to them from your pages just like you would on a regular HTML site. Just make sure to use a relative path. For example, to link to a stylesheet in your layout, you would use <link rel="stylesheet" href="/assets/css/style.css">. By keeping all your assets in one or two dedicated folders, your project stays organized and easy to navigate.

What Happens When I Build the Site?

Once you have all your files and folders set up, you need to "build" your site. This is a process where Jekyll takes all your source files—the Markdown posts, the layouts, the includes, and the static assets—and processes them into a fully functional static website. The final result of this process is a new directory named _site. This folder is the final destination for your website; it contains pure HTML, CSS, JavaScript, and images—everything a web browser needs to display your site.

The _site directory is what gets deployed to GitHub Pages. You should never edit any files inside this folder directly because it gets completely erased and rebuilt every time you run Jekyll. This is why it’s often a good practice to add _site/ to your .gitignore file. By understanding that your work is in the source files and the _site folder is just the output, you can avoid a lot of confusion. This clear separation of source and output is a key concept that makes Jekyll so effective for building static websites.

Comments

Post a Comment