From Zero to Hero A Walkthrough of the Jekyll Directory for GitHub Pages Beginners
If you're a beginner, a Jekyll project folder might seem a little intimidating at first. You'll see a mix of files and folders, some with underscores and some without, and it's not immediately obvious what each one does. This guide is a step-by-step walkthrough designed to take you from a complete beginner to someone who confidently understands the Jekyll directory structure. We will break down each key file and folder, explaining its role in a simple and straightforward way. By the time you're done, you'll know exactly where to put your content, how to change your site's settings, and where to find your website's templates. This foundational knowledge is all you need to start building your own website on GitHub Pages and move from zero to hero.
Table of Contents- Your First Steps with Jekyll
- The Root Directory What You See First
- The Special Folders for Design and Structure
- Building and Publishing Your Site
Your First Steps with Jekyll
Jekyll is an incredibly powerful tool because it automates much of the website creation process. It knows how to take your raw content and templates and turn them into a complete, static website. This is made possible by its predictable directory structure. You don't have to tell Jekyll where your blog posts are; it knows to look in the _posts folder. You don't have to specify where your templates are; it knows they're in the _layouts folder. Learning this system is the most efficient way to get up and running, so let's start with the files you'll see as soon as you open your project folder.
The Root Directory What You See First
The _config.yml File Your Sites Settings
When you look inside your Jekyll project, the most important file you will see at the top level is **_config.yml**. This is your site's main settings file, written in YAML. It’s where you define all the global information about your website, such as the title, description, and author. You also use this file to set your website's base URL, which is very important for GitHub Pages, and to configure your post's URL structure (permalinks). Any change you make here will apply to your entire site. For a beginner, this is the first place to look when you want to change your site's name or other core information.
This file is also where you tell Jekyll which plugins to use and which files or folders to ignore. For example, if you want Jekyll to ignore a folder of images you're not ready to use yet, you can add its name to the exclude list in this file. The _config.yml file is the single source of truth for your site’s behavior, making it a critical file to understand from the very beginning.
Posts, Pages, and index.md
In Jekyll, content is divided into two main categories: posts and pages. Pages are for static, standalone content like your home page, an "About" page, or a "Contact" page. You create a page by simply placing a Markdown or HTML file directly in the root directory. For example, your home page is typically named index.md or index.html. An "About" page could be about.md. When you build your site, these files become pages at the corresponding URLs, like /about/.
Posts, on the other hand, are for chronological content, like blog articles. All of your posts must be placed inside the **_posts** directory. These files must be named using a specific format: YYYY-MM-DD-your-post-title.md. This naming convention is not just for organization; it's how Jekyll knows the date of your post and what to name its URL. By keeping your blog articles in this separate folder, you keep your main directory clean and make it easy for Jekyll to handle your content automatically.
The Special Folders for Design and Structure
_layouts Your Site's Templates
How does your content get its final look? That's the job of the **_layouts** folder. This directory contains all the HTML templates for your website. Think of a layout as a blueprint for a page. You might have a default.html file that contains the common HTML for your header, navigation, and footer. Then, you might have a post.html file that uses the default.html layout but adds a special sidebar or comment section for blog posts. By using layouts, you avoid repeating the same HTML on every single page. Instead, you just tell a page or post which layout to use in its YAML front matter, and Jekyll does the rest.
This system is a great way to ensure consistency across your entire site. If you decide to change your site's navigation, you only have to edit the code in one place—the layout file—and the change will appear on every page that uses that layout. This is a fundamental concept for building a professional and maintainable website.
_includes Reusable Code Snippets
The **_includes** folder is like your personal toolbox of HTML components. This is where you put small, reusable snippets of code that you want to use across multiple layouts or pages. Common examples include a footer, a social media icon block, or a navigation bar. By placing these snippets in a file inside the _includes directory, you can then add them to a layout using a simple Liquid tag, like {% include footer.html %}. This keeps your code clean and organized. When you need to make an update, you just change the file in _includes, and the change automatically appears everywhere that snippet is used.
This folder is a fantastic resource for beginners because it helps you start thinking about modular design. Instead of writing the same code over and over again, you can create a single component and reuse it wherever you need it, making your site more efficient and easier to manage.
Assets for Images and Styles
When you're building a website, you will need images, CSS stylesheets, and JavaScript files. For these, it's a best practice to create a folder at the root of your project, often named **assets**. Inside, you can create subfolders for css, js, and images. Any file that does not start with an underscore is considered a static asset, and Jekyll will simply copy it directly to the final website without processing it. This means you can link to your files using a simple path. For example, your stylesheet might be located at /assets/css/style.css. This approach keeps your project organized and prevents your root directory from becoming cluttered with unrelated files.
Building and Publishing Your Site
Once you've added your content and set up your templates, you'll need to "build" your site. This is when Jekyll takes all of your source files and compiles them into a complete, ready-to-publish website in a new directory named **_site**. This folder contains all the static HTML, CSS, and images that a web browser needs. It is the folder that gets deployed to GitHub Pages. It's very important to know that you should never edit files inside the _site folder. It is a temporary output directory that is deleted and rebuilt every time you run the build command. To make sure you don't accidentally commit it to your Git repository, it's a great habit to add _site/ to your .gitignore file.
