Madhurima Mindscape

📂 1. Start With a Data Folder

One of the first things I recommend when organizing a Jekyll project is creating a proper data folder.

You can store commonly used information, configuration data, and other reusable content in this folder instead of repeatedly writing the same information across different files.

Jekyll provides a _data directory where you can store structured data in YAML, JSON, or CSV formats. You can then access that information using Liquid.

For example, suppose you have several navigation links that you want to display across your website. Instead of manually writing those links in every page, you can maintain them in a single YAML file.

You can also maintain reusable information such as categories, social links, website settings, blog insights, and SEO metadata.

In my project, the _data directory contains structured information for different article categories, homepage content, blog insights, templates, saved-article page content, and the custom 404 page.

Another useful approach is keeping your configuration centralized. Whenever you need to update something that is used across multiple pages, you have a single place to make that change. This becomes especially helpful when your website contains a large number of pages.

📄 2. Use Include Files for Reusable Components

The next important thing is the _includes folder. This is where you can keep reusable components that you want to include across multiple pages.

For example, consider a website where you have the same navigation header, footer, social links, and other HTML elements appearing on multiple pages. Instead of copying and pasting the same HTML everywhere, you can create separate include files for these components.

In Madhurima Mindscape, I group reusable interface components inside a components directory and page-specific content sections inside an imports directory. The structure looks like this:

_includes/
├── components/
│   ├── footer.html
│   ├── header.html
│   ├── icon-hero-section.html
│   ├── post-actions.html
│   └── slider-carousel.html
└── imports/
    ├── 404.html
    ├── blog-insights.html
    ├── blog.html
    ├── explore-the-blog.html
    ├── index.html
    └── saved-articles.html

You can then include these components wherever you need them using Liquid. For example, the following is a simplified illustration using the actual component paths in my project:

{% include components/header.html %}

<main>
    <h1>Welcome to my website</h1>
</main>

{% include components/footer.html %}

The really useful thing here is that you only need to maintain the component in one place. Suppose you want to change your navigation header. You don't have to search through hundreds of HTML files and update the same structure everywhere. You simply update the corresponding include file, and the change is reflected wherever that component is used during site generation.

You can also pass variables to include files, which makes them even more reusable. I personally find this approach particularly useful for websites with many pages and repeated components.

🧩 3. Use Layouts to Maintain a Consistent Website Structure

Another feature I really like about Jekyll is its layout system. Imagine having hundreds of blog posts. Most of them follow the same general structure: a heading, publication date, article content, and some common elements around the content.

Writing the entire HTML structure separately for every article would be unnecessarily repetitive. Instead, you can create a layout file and reuse it across multiple pages.

My project uses layouts for individual blog posts, the homepage, the Explore the Blog page, the Blog Insights dashboard, and the custom 404 page. A simplified layout directory looks like this:

_layouts/
├── 404.html
├── blog-insights.html
├── blog.html
├── explore-the-blog.html
└── index.html

Your blog layout can contain the common structure required by every article. A simplified example would look something like this:

---
layout: default
---

<article>
    <h1>{{ page.title }}</h1>
    <p>{{ page.date | date: "%B %d, %Y" }}</p>
    {{ content }}
</article>

Now, whenever you create a new article, you only need to specify the layout in its front matter. Jekyll automatically places the page content inside the layout.

This makes it extremely easy to maintain a consistent structure across hundreds or even thousands of articles. If you decide to change the overall blog layout, you only need to update the layout file instead of modifying every individual article.

🔖 4. Organize Your Articles Using Front Matter and Liquid

Another thing I found useful is how Jekyll handles page-specific information through front matter. Every article can have its own metadata, such as its title, permalink, categories, tags, publication date, and other custom information.

For example, you can define something like this at the beginning of an article:

---
layout: blog
title: "My First Article"
date: 2026-11-05
permalink: /my-first-article
categories:
  - Tech Insights
tags:
  - Web Development
  - Programming
  - Developer Tips
---

You can then access these values using Liquid variables. For example, {{ page.title }} gives you the article title, while {{ page.categories }} and {{ page.tags }} allow you to access its categories and tags.

This is especially useful when building dynamic-looking sections of a static website. For instance, you can create a category page that automatically displays all articles belonging to a particular category. Similarly, you can generate tag pages, related article sections, and article listings without manually maintaining every link.

The best part is that whenever you add a new article with the appropriate metadata, your existing Liquid templates can automatically accommodate it.

🔗 5. Permalinks: Keep Your URLs Independent of File Structure

One of my favourite features of Jekyll is the permalink option. Normally, the URL structure of a static website can become closely connected to the way you organize your files and folders.

However, Jekyll allows you to explicitly define the URL at which a particular page should be served.

For example, suppose your article is located inside a nested folder:

_posts/
└── tech-insights/
    └── 2026-11-07-jekyll-migration.html

You can still define its permalink in the front matter:

---
permalink: /jekyll-migration
---

Now the article will be available at /jekyll-migration, regardless of the original folder structure. When the site is hosted as a GitHub Pages project site, the configured base URL is also part of the public path. For this project, that means the local URL is /Madhurima-Mindscape/jekyll-migration.

This gives you much more flexibility when organizing your project. You can move files into different directories or restructure your website without necessarily changing the public URLs.

I find this particularly useful when migrating an existing website because you can preserve the URLs that people are already familiar with. It also helps avoid unnecessary broken links when reorganizing a large collection of articles.

🎨 6. Split Large CSS and JavaScript Files Into Smaller Parts

Another problem I frequently encounter when maintaining a website is that CSS and JavaScript files keep growing. Initially, you might have a single CSS file containing all your styling. That is perfectly reasonable for a small project.

But as you introduce new components, pages, and features, the file can become extremely long and difficult to manage. With a Jekyll project, you can organize your stylesheets into smaller, logically separated files.

For example:

css/
├── 404.css
├── blog-insights.css
├── contents.css
├── explore.css
├── icon-hero-section.css
├── index.css
├── post-actions.css
├── saved-articles.css
├── slider-carousel.css
└── themes.css

The same idea applies to JavaScript. Instead of maintaining one enormous file, you can separate different functionalities into individual files.

js/
├── blog-insights.js
├── explore.js
├── index.js
├── post-actions.js
├── saved-articles.js
└── slider-carousel.js

Whenever you want to update a particular component, you know exactly where to look. This becomes increasingly valuable as your website grows. You can introduce new features without turning your existing codebase into one massive collection of unrelated code.

📚 7. Jekyll Becomes Especially Useful When Your Website Grows

This is probably the biggest reason why I would recommend considering Jekyll for a larger static website. Suppose you have hundreds or thousands of blog posts. You are continuously adding new articles, introducing new sections, updating your navigation, and improving different components.

Managing all of this using individual HTML files can eventually become frustrating. You might want to introduce a new feature that needs to appear across all articles. Perhaps you want to update the article structure, change the navigation, add a new CSS component, or modify the footer.

Without a reusable structure, you might have to modify hundreds of files individually. With Jekyll, you can often make the same change by updating just one include file, layout, stylesheet, or data file.

For example:

• New navigation feature: Update the header component.
• New article structure: Update the blog layout.
• New reusable component: Create an include file.
• Updated website information: Modify the relevant data file.
• New styling: Add or update the appropriate CSS file.

This is what makes Jekyll particularly attractive when building and maintaining a large static website. You can keep adding new articles and features while maintaining a relatively organized codebase.

⚖️ 8. When Should You Actually Use Jekyll?

Now, despite all these advantages, I don't think Jekyll is something you should use for every static website. It introduces an additional layer of complexity. You need to understand its folder conventions, layouts, includes, front matter, Liquid syntax, and the build process.

Initially, setting everything up can take some time. You also need to understand how the different parts of your project interact with each other. So, I would divide the decision into two scenarios.

🌱 Small Projects With Limited Future Scope

If you are building a very small website with only a few pages, and you don't expect it to grow much, I would recommend sticking with a simple HTML, CSS, and JavaScript structure.

For example, if you are creating a personal landing page, a small portfolio, or a simple static webpage, introducing Jekyll might be unnecessary.

my-website/
├── index.html
├── about.html
├── style.css
└── script.js

There is nothing wrong with this approach. In fact, for smaller projects, keeping things simple is often the better decision. You don't need layouts, includes, data files, and a build system if your website doesn't actually need them.

🚀 Larger Projects With Significant Future Scope

However, if you are planning to build a website that will continuously grow, Jekyll becomes much more interesting. Suppose you are planning to publish hundreds of articles, introduce multiple categories, create reusable components, and continuously add new features.

In that situation, having a proper structure from the beginning can save you a considerable amount of maintenance work later. You can organize your content, reuse layouts, maintain common components, and update the website centrally.

The initial setup might be slightly complicated, but the benefits become more noticeable as the project grows.

🏗️ 9. How I Organized Madhurima Mindscape

To make these ideas more practical, I want to share how I have organized my own website, Madhurima Mindscape. It is a Jekyll-powered personal blogging platform where I publish technical articles, personal reflections, project experiences, poetry, and photography.

The project uses Jekyll for static site generation, Ruby for the runtime environment, Liquid for templates, YAML for structured data, and HTML, CSS, and JavaScript for the frontend.

I have separated published articles, metadata, layouts, reusable components, standalone blog tools, and frontend assets. This makes it easier to locate a particular feature and maintain it without unnecessarily changing unrelated parts of the website.

My Main Project Structure

Madhurima-Mindscape/
├── _data/
│   ├── 404/
│   ├── creative-clicks/
│   ├── introduction/
│   ├── personal-insights/
│   ├── poem-perspectives/
│   ├── project-diaries/
│   ├── tech-insights/
│   ├── blog-insights.yml
│   ├── blog-template.yml
│   ├── index.yml
│   └── saved-articles.yml
│
├── _includes/
│   ├── components/
│   │   ├── footer.html
│   │   ├── header.html
│   │   ├── icon-hero-section.html
│   │   ├── post-actions.html
│   │   └── slider-carousel.html
│   └── imports/
│       ├── 404.html
│       ├── blog-insights.html
│       ├── blog.html
│       ├── explore-the-blog.html
│       ├── index.html
│       └── saved-articles.html
│
├── _layouts/
│   ├── 404.html
│   ├── blog-insights.html
│   ├── blog.html
│   ├── explore-the-blog.html
│   └── index.html
│
├── _posts/
│   ├── creative-clicks/
│   ├── introduction/
│   ├── personal-insights/
│   ├── poem-perspectives/
│   ├── project-diaries/
│   └── tech-insights/
│
├── blog-tools/
├── css/
├── images/
├── js/
├── website_snapshots/
├── 404.html
├── _config.yml
├── Gemfile
├── Gemfile.lock
└── index.html

This is a simplified overview of the repository rather than every individual file. The category folders inside _posts keep articles grouped by subject, while the matching folders inside _data hold related structured information.

The blog-tools directory contains standalone tools such as Saved Articles, Blog Insights, and the Blog Template Library. Keeping these separate from _posts helps keep the posts directory focused on published articles.

🛠️ 10. Technologies and Browser Features Behind the Website

Jekyll handles the generation and organization of the website, while standard frontend technologies provide the visual design and interactive experience.

• Jekyll: Generates the static website and manages blog content.
• Ruby and Bundler: Provide the runtime and dependency environment.
• Liquid: Renders templates, variables, loops, and conditional content.
• YAML: Stores configuration, article metadata, and structured website data.
• HTML5: Defines the structure and content of pages.
• CSS3: Handles styling, responsive layouts, and themes.
• JavaScript: Powers interactive components and client-side features.
• Font Awesome: Supplies icons used throughout the interface.
• Git and GitHub: Support version control and repository management.
• GitHub Pages: Hosts the generated website.

I also use browser-native APIs to provide useful features without requiring a separate backend for every interaction.

• LocalStorage: Saves bookmarked articles in the visitor's browser.
• Web Share API: Enables native sharing on supported browsers and devices.
• Clipboard API: Copies article links.
• Web Speech API: Provides browser-based read-aloud functionality.

These technologies work together to create a website that is statically generated but still offers interactive features in the browser.

🔄 11. How Jekyll Builds the Website

One thing worth understanding when working with Jekyll is what happens when the website is built. Jekyll reads the source files, processes front matter and Liquid templates, combines content with layouts and includes, and writes the generated website into the _site directory.

The overall workflow looks like this:

Blog Articles (_posts)     Structured Data (_data)
          \                         /
           \                       /
            v                     v
                 Jekyll + Liquid
                        |
              +---------+---------+
              |                   |
              v                   v
           Layouts              Includes
         (_layouts)            (_includes)
              |                   |
              +---------+---------+
                        |
                        v
                Generated HTML
                        |
              +---------+---------+
              |                   |
              v                   v
             CSS              JavaScript
              |                   |
              +---------+---------+
                        |
                        v
                 Complete Website
                        |
                        v
                  GitHub Pages

In simple terms, the source files are used to generate the final pages. Visitors receive the generated HTML, CSS, JavaScript, and assets rather than needing Jekyll or Ruby installed on their devices.

💻 12. Running a Jekyll Website Locally

Before deploying changes, it is useful to run the website locally. This lets you check whether pages build correctly, whether links work, and whether the layout looks as expected.

For a typical Jekyll project, you need Git, Ruby, RubyGems, and Bundler. You can check whether Ruby and Bundler are installed by running:

ruby --version
gem --version
bundle --version

After cloning the repository and moving into the project directory, install the dependencies:

git clone https://github.com/madhurimarawat/Madhurima-Mindscape.git
cd Madhurima-Mindscape
bundle install

Then start the local Jekyll server:

bundle exec jekyll serve

Open the local address in your browser:

http://127.0.0.1:4000/Madhurima-Mindscape/

Jekyll rebuilds the website when supported source files change. If you only want to generate the website without starting the development server, use:

bundle exec jekyll build

The generated files will be available in the _site directory. If a build fails, check the terminal output carefully. Missing include files, invalid Liquid syntax, and incorrect paths are common issues to investigate.

One important detail when writing technical articles about Jekyll: Liquid examples inside an article can be interpreted as real template instructions during the build. If you want to display Liquid syntax as code, wrap the example in Liquid's raw and endraw tags around the example so Jekyll displays the Liquid code instead of executing it.