Working with the assets Folder Organizing CSS JS and Images in Jekyll
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
assetsfolder - How should you structure CSS, JS, and images inside assets
- Best practices for loading assets in layouts
- Optimizing assets for performance
- Troubleshooting common asset issues
- Where to go after mastering asset management
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.