The _site Folder Explained: What Happens Behind the Scenes in Jekyll Builds

By -

When you run jekyll build or deploy your site to GitHub Pages, Jekyll generates a special folder called _site. This is not just another directory; it is the compiled version of your website that gets served to the browser. If you think of your Jekyll project as a factory, then _site is the final packaged product ready for delivery. Understanding what goes on inside _site can save you from many headaches when debugging or customizing your site’s deployment.

Key Questions This Guide Will Answer

What is the purpose of the _site folder?

The _site folder contains the fully processed, static version of your website. While you write posts, pages, and templates using Liquid, Markdown, and front matter, these raw files are not what the browser understands. Jekyll compiles them into plain HTML, CSS, and JavaScript files inside _site. In short: _site is the output folder that browsers actually see.

What files and folders are generated inside it?

Here’s what you’ll typically find inside _site after running a build:

  • HTML pages – Every Markdown or HTML file in your project is converted into a proper HTML page.
  • Assets – CSS, JavaScript, images, and other static files are copied over.
  • Posts – All posts from _posts are turned into HTML pages with permalinks.
  • Collections – Custom collections defined in _config.yml are compiled here.
  • Feeds & sitemaps – If you use plugins like jekyll-feed or jekyll-sitemap, their outputs appear in this folder.

Essentially, if it is viewable on your website, it exists in some form inside _site.

Why should you ignore _site in Git?

Since _site is a generated directory, you should not commit it to version control. Doing so bloats your repository and creates unnecessary merge conflicts. Instead, add it to your .gitignore file:

_site/

GitHub Pages automatically runs Jekyll to build _site on the server, so there’s no need to track it locally.

How can you use _site for debugging?

Even though you don’t commit _site to Git, it is extremely useful for debugging. By inspecting the compiled HTML inside _site, you can:

  • Check whether Liquid tags and variables resolved correctly.
  • Confirm that permalinks are working as expected.
  • Verify whether assets (like images or CSS) are being copied properly.
  • Spot broken links or missing resources.

If something looks wrong on your live site, always compare your local _site output with what you expect.

What happens to _site during GitHub Pages deployment?

When you push your repository to GitHub, you don’t actually push the _site folder. Instead, GitHub runs Jekyll on their servers to generate _site automatically. This ensures consistency and prevents unnecessary files from being uploaded. However, if you’re deploying to a platform that doesn’t run Jekyll (like Netlify or Vercel), you may need to build locally and upload _site as the deploy target.

Best practices for managing _site

  • Always add _site/ to your .gitignore.
  • Never edit files directly inside _site; your changes will be overwritten during the next build.
  • Use it only for testing, debugging, or verifying builds.
  • If you use continuous integration (CI/CD), configure the pipeline to build Jekyll and deploy the _site output.

Next steps after mastering _site

Once you understand the _site folder, the next step is learning about _data, _layouts, and _includes, which all contribute to how _site is generated. By mastering these inputs, you’ll gain full control over the final HTML that appears in your _site directory—and by extension, your live website.

Final Thoughts

The _site folder might seem like a behind-the-scenes detail, but it’s the most important part of your Jekyll workflow. Without it, your site wouldn’t exist in a form the browser can understand. Treat _site as a final product—inspect it often, but never modify it directly. Once you master how _site works, you’ll have a much clearer picture of the entire Jekyll build process.

What Should You Do Next

Run jekyll build locally and explore the _site folder. Compare it with your source files and note how Jekyll transforms your Markdown, layouts, and Liquid tags into clean HTML. This practice will sharpen your debugging skills and help you become more confident in managing your GitHub Pages site.