Working with the assets Folder Organizing CSS JS and Images in Jekyll

By -

When building a Jekyll website, one of the most practical questions beginners face is where to put their static files such as stylesheets, scripts, and images. The assets folder plays a central role in keeping your project structured, maintainable, and scalable. Without a clear assets strategy, websites quickly become messy, slow, and hard to maintain. This guide will help you understand how to work effectively with the assets directory in Jekyll and GitHub Pages.

Key Topics Covered in This Guide

Why does Jekyll use an assets folder

The assets folder is a central location for your project’s static resources. Instead of scattering images and scripts throughout your repository, placing them in assets creates order and predictability. This helps in:

  • Keeping your project organized and easy to navigate.
  • Ensuring consistent paths when linking files in templates and posts.
  • Making it easier to optimize and update files in bulk.

How should you structure CSS, JS, and images inside assets

Jekyll does not force a strict internal structure inside assets, so you can design it according to your needs. However, a recommended convention looks like this:

assets/
  css/
    style.css
    theme.css
  js/
    main.js
    analytics.js
  images/
    logo.png
    banner.jpg
    icons/
      twitter.svg
      github.svg

This clear separation makes it obvious where to find a particular file and prevents conflicts when your project grows.

Best practices for loading assets in layouts

Once your files are in place, you need to reference them in layouts or includes. For example, to load a stylesheet in your _layouts/default.html file:

<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">

And for JavaScript:

<script src="{{ '/assets/js/main.js' | relative_url }}"></script>

Using relative_url ensures compatibility across different environments, such as local builds and GitHub Pages deployment.

Optimizing assets for performance

Large and unoptimized assets slow down websites. Here are strategies to improve performance:

  • Minify CSS and JavaScript – Use tools like Jekyll plugins, or preprocess assets before adding them.
  • Compress images – Tools such as TinyPNG or ImageOptim can drastically reduce file size.
  • Use modern formats – Prefer SVG for icons and WebP for photos when possible.
  • Lazy loading – Add loading="lazy" to images to improve page speed.

Troubleshooting common asset issues

Sometimes assets don’t load correctly. Here are common problems and fixes:

Issue Cause Solution
Broken asset links Incorrect file paths Double-check the relative_url or absolute_url filters
CSS not applying Cache or missing link tag Clear browser cache and confirm <link> tag placement
Images not showing Case sensitivity on file names Ensure image file names match exactly (Linux servers are case-sensitive)

Where to go after mastering asset management

Once you are comfortable with organizing CSS, JS, and images in Jekyll, the next step is exploring how to use Jekyll’s _includes folder to create reusable snippets for loading assets. For example, you can define a single include file for analytics scripts and reference it across multiple layouts. This will streamline your workflow even further.

Final Thoughts

The assets folder may seem like a small detail in the bigger picture of Jekyll, but in reality, it is critical for maintainability and performance. A well-organized assets strategy makes your site cleaner, faster, and easier to update. Whether you’re managing a blog, portfolio, or documentation site, mastering asset management is a skill that pays off in the long run.

What Should You Do Next

Take a moment to review your current Jekyll project. Do your CSS, JavaScript, and image files live in a messy root directory, or are they neatly organized under assets? Rearrange them into structured subfolders, update your layout references, and test your site locally. Once you see the improvement in clarity and performance, you’ll never go back to a scattered setup.