Jekyll Directories Explained Where Everything Goes on Your GitHub Pages Blog

-

When you start a Jekyll project, you'll see a collection of folders and files, some with an underscore in their name and some without. This is the core of Jekyll's powerful and simple system. Each directory has a specific job, and understanding these roles is the key to building and managing a clean, organized blog on GitHub Pages. This article will explain what each of the main directories does, so you know exactly where to put your content, where to find your design files, and how Jekyll processes everything to create your final website. By the end, you'll have a clear mental map of your Jekyll project, making it much easier to work with.

Table of Contents

The beauty of Jekyll lies in its conventions. It's a "zero configuration" tool in many ways because it already knows what to do with a file based on where it's located. For example, it expects blog posts to be in a folder named `_posts`. This means you don't have to tell Jekyll where to find your content; it just knows. This predictable structure is what allows Jekyll to automate the process of building a static website, making it a perfect choice for blogging and documentation. Let's start by looking at the special folders that are at the heart of Jekyll's system.

The Underlined Folders The Heart of Jekyll

_posts The Home of Your Blog

For any blog, the _posts directory is where all the magic happens. This is the dedicated home for all your articles. Every file you place here must be a Markdown file with a very specific naming convention: YYYY-MM-DD-your-post-title.md. The date at the beginning of the filename is used by Jekyll to automatically sort your posts and generate a clean URL. The title part of the filename is used to create the final URL slug. This system ensures that your blog is always organized chronologically and that your URLs are clear and SEO-friendly. Inside each post file, you will also use a YAML front matter block at the top to set the post's title, author, and which layout it should use.

By keeping all your blog content in one place, the _posts folder makes it incredibly easy to manage and find your articles. It also signals to Jekyll that these are time-stamped, chronological pieces of content that should be processed differently than a static page, such as your "About" page.

_layouts Your Site's Templates

The _layouts directory is where your website's design comes to life. This folder contains all the HTML templates, or layouts, that define the overall structure of your pages and posts. You might have a default.html layout that provides the basic HTML, including the header, navigation, and footer for your entire site. You could then have a more specific post.html layout that uses the default layout but adds a dedicated space for the post's content and maybe a comment section. This approach allows you to create a consistent look and feel across your entire website without repeating a lot of HTML code. If you need to change your navigation bar, you only have to edit the layout file, and the change will be applied everywhere.

This separation of content from design is a key principle of Jekyll. Your blog posts and pages contain only the content, while the layouts provide the framework. This makes your site much easier to maintain and update.

_includes for Reusable Snippets

For smaller, reusable pieces of code, Jekyll uses the _includes directory. This is where you can store HTML snippets like a site-wide footer, a social media icon block, or a contact form. Instead of copying and pasting this code into every layout, you can save it as a file in the _includes folder and then use a simple Liquid include tag to insert it wherever you need it. For example, {% include footer.html %} will place the content of your footer file right there. This practice keeps your code clean, modular, and easy to maintain. If you ever need to change a reusable component, you only have to edit the file in _includes, and the change will be reflected everywhere it's used.

The Root and Your Static Files

The _config.yml File Your Site's Settings

At the root of your project, the _config.yml file is the most important configuration file. It’s where you define global settings for your site, such as its title, description, and base URL. This is also where you can set the permalink structure for your posts and tell Jekyll which plugins to use. Because these settings are global, any changes you make here will affect your entire website. It's the central control panel for your project and should be kept clean and well-documented.

The Role of Pages

For static content that isn't a blog post, you simply place your Markdown or HTML files directly in the root directory. These are your "pages." For example, a file named about.md will become the /about/ page on your website. You can also create subdirectories to organize your pages, such as /docs/getting-started.md, which will become the /docs/getting-started/ page. This simple file-based approach to creating pages makes it very intuitive and easy to manage the non-blog content on your site.

Assets and Other Static Content

Your website also needs static assets like images, CSS stylesheets, and JavaScript files. Any file or folder in the root directory that does not start with an underscore is treated as a static asset. Jekyll simply copies these files directly to the final website folder without any processing. A common practice is to create an assets folder at the root of your project and put subdirectories inside it for images, css, and js. This keeps your project organized and ensures that your files are easy to find and link to.

The Output and the Final Product

Once you run the Jekyll build command, all of these files and folders are processed and compiled into a single, complete, and static website inside the _site directory. This is the final output of your project, containing all the HTML, CSS, JavaScript, and images that a web browser needs. The _site folder is what gets published to GitHub Pages. It is crucial to remember that you should never edit anything inside this folder directly, as it gets completely erased and rebuilt every time you build your site. To prevent accidentally committing this temporary folder to your Git repository, always add _site/ to your .gitignore file.

Comments

Post a Comment