What Happens When You Build a Jekyll Blog Step by Step
What Does It Mean to "Build" a Jekyll Blog?
For complete beginners, the term "building a blog with Jekyll" can sound technical and intimidating. But the concept is actually quite simple when you think of it like putting together pages in a notebook. Jekyll is just a tool that turns a folder full of plain text into a real, working website. Let’s explore what that really means, step by step, without code or jargon.
Imagine You’re Assembling a Book
Think of your blog as a printed book. You write your chapters (blog posts), design the cover (homepage layout), and organize the table of contents (navigation). Once you’ve written everything, you hand the pieces to a printing machine (Jekyll), which turns it all into a finished book (your blog website).
In this analogy:
Your Markdown files are the raw text of your blog posts.
Layouts and templates are the design instructions for how each page should look.
The build process is like printing and binding everything together.
Where Does GitHub Pages Come In?
GitHub Pages is like the online library that hosts your book for free. When you “publish” your site using GitHub Pages, you’re basically putting your finished website on a public shelf for the world to read. And the best part? You don’t have to know how to run a server, or manage a database. GitHub does the hosting. Jekyll does the building.
The Relationship Explained Simply
Here’s how it all connects in basic terms:
You write content → using Markdown files.
Jekyll builds the site → using templates and settings.
GitHub Pages hosts the final site → and makes it visible to everyone.
So What’s Inside a Jekyll Blog Project?
When you first download or fork a Jekyll theme like Mediumish, you get a folder full of files. It might look confusing, but think of these files like parts of a puzzle that Jekyll puts together.
The important parts for beginners:
_posts/: This is where your blog articles go. You write them in Markdown (.md files).
_layouts/: These are the page designs—like deciding where the title goes or what the sidebar looks like.
_config.yml: This is the control panel. You set your blog name, author name, and some options here.
index.html: This is your homepage. It usually uses a layout and pulls your latest posts.
It’s All Based on Rules
Jekyll follows predictable rules. Every post must be in the _posts/ folder and must be named with the date first. Layouts should be inside _layouts/. And settings go into _config.yml. If you stick to the rules, your site will work every time.
What Does “Building” the Site Mean?
“Building” in Jekyll means: it reads all your text files and templates, and then generates actual HTML files. These HTML files are the final product that web browsers can understand. So your readers never see the raw Markdown—you do. They only see the clean, styled blog thanks to Jekyll.
You Don’t Build It Manually
Jekyll builds everything automatically. On GitHub Pages, you don’t even need to run Jekyll on your computer. When you push your changes, GitHub builds your site in the background. This makes it perfect for beginners.
What If Something Goes Wrong?
When your blog doesn’t show updates, or shows a blank page, don’t panic. Here are the most common beginner mistakes:
1. Wrong File Naming
All blog post files must follow this format: YYYY-MM-DD-your-title.md. If the date or format is off, Jekyll will ignore it.
2. Invalid Front Matter
Each file must start with a section called “front matter” using three dashes (---). If that’s missing or has mistakes, the build will fail.
3. Forgot to Push Changes
Jekyll only builds the version of the site you pushed to GitHub. If it’s still showing old content, make sure your changes were committed and pushed.
How Can You Make Small Customizations Without Breaking It?
One of the best parts about Jekyll is that you can customize almost anything. But for beginners, it’s safer to change only certain files:
Change text inside your posts in
_posts/.Update site name or description in
_config.yml.Edit
index.htmlif you want to change your homepage intro.
Don’t Touch Layouts Too Soon
Until you're comfortable, it’s better to avoid modifying files in _layouts or _includes. These control design and structure. Changing them without understanding could break your site’s appearance.
How Do You Know Jekyll Is Right for You?
If you:
Prefer writing in Markdown over using a CMS dashboard
Want free hosting on GitHub
Like learning how things work under the hood
Then yes—Jekyll is a great choice. But if you prefer visual editors and drag-and-drop design, you might be happier with something like WordPress or Wix.
What Should You Do Next After Setting Up?
Here’s a recommended path for beginners:
Write your first post in
_posts/using a simple Markdown format.Push the site to GitHub and see how it looks.
Customize your homepage text.
Change your blog title and description in
_config.yml.
Final Advice for New Jekyll Users
Start slow. Don’t worry about layouts or plugins yet. Focus on writing posts and understanding how your changes affect the site. As you gain confidence, you’ll find it easier to explore deeper customization. And remember: because everything is version-controlled with Git, you can always undo a mistake.
Why This Stack Is Empowering for Beginners
Jekyll may seem unusual at first, but it teaches you a lot about how websites actually work—file structures, templates, hosting, and more. Once you get past the initial learning curve, you’ll appreciate the speed, control, and simplicity it offers.