Mastering Git Beyond the Basics

When managing a digital marketing blog, especially one powered by Jekyll on GitHub Pages, the tools you use to interact with your Git repository significantly impact your workflow. We've previously discussed the merits of GitHub Desktop for its ease of use and the power of the Git Command Line Interface (CLI) for granular control. This article takes a different perspective, focusing on scenarios where the Git CLI isn't just an option, but a necessity. It's about transcending basic operations and truly mastering Git beyond the basics, understanding why and when the command line becomes your most powerful ally.

While GitHub Desktop handles common tasks admirably, the true depth and flexibility of Git are unlocked through its command-line interface. This is where advanced users, developers, and those looking to automate complex processes find their stride. If you're aiming to elevate your repository management skills and gain a profound understanding of version control, embracing the Git CLI is an inevitable and rewarding journey.

When GitHub Desktop Falls Short

GitHub Desktop is fantastic for many common Git operations, but there are distinct limitations that necessitate a move to the CLI. Understanding these limitations is the first step toward appreciating the power of the command line.

Complex History Manipulation

One of the areas where GitHub Desktop's abstraction becomes a hindrance is in manipulating your commit history. While you can revert commits, advanced operations like interactive rebasing (git rebase -i) are not directly available. This command allows you to:

• Squash commits: Combine multiple small, iterative commits into a single, more meaningful one. This keeps your project's history clean and easier to understand, especially before merging into a main branch. Imagine drafting a blog post with 10 minor commits for typos; squashing them into one "Added new article: [Title]" commit is far cleaner.
• Reorder commits: Change the sequence of commits in your history.
• Edit commit messages: Modify previous commit messages.
• Drop commits: Completely remove unwanted commits from your history.

These operations are crucial for maintaining a tidy, logical, and review-friendly project history, which is particularly important in collaborative environments or when preparing a feature branch for merging. GitHub Desktop simply doesn't offer this level of surgical precision.

Granular Staging and Partial Commits

GitHub Desktop typically allows you to stage entire files or discard all changes within a file. However, what if you've made several distinct changes within a single file, and you only want to commit a specific part of it? This is where partial commits come into play, a feature handled expertly by the Git CLI.

With commands like git add -p (patch mode), you can interactively stage specific "hunks" or even individual lines of code within a file. This gives you incredibly granular control over what goes into each commit. For instance, if you've updated both a blog post's content and fixed a minor stylistic issue in the same file, you can commit the content change separately from the style fix, leading to more atomic and understandable commits.

Resolving Intricate Merge Conflicts

While GitHub Desktop provides a basic interface for resolving simple merge conflicts, complex scenarios can quickly become overwhelming. When multiple team members make conflicting changes to the same lines of code or content, the merge conflicts can be deep and difficult to visually untangle.

The Git CLI, combined with external merge tools configured in Git (e.g., KDiff3, Beyond Compare), offers a far more robust and precise way to resolve intricate merge conflicts. You can manually inspect conflicting sections, choose which changes to keep, and even integrate parts from both versions. For a digital marketing team collaborating on large articles or Jekyll layouts, mastering conflict resolution via CLI is crucial for maintaining project integrity.

Advanced Git Concepts Best Handled by CLI

Beyond the basic push, pull, and commit, Git offers a suite of powerful features that are primarily (or exclusively) accessed via the CLI.

Git Hooks for Automation

Git hooks are custom scripts that Git executes automatically before or after certain events, such as committing, pushing, or receiving changes. They reside in the .git/hooks directory of your repository and are a powerful way to automate workflows, enforce standards, and integrate with external systems.

For a digital marketing blog on GitHub Pages, Git hooks can be incredibly valuable:

• Pre-commit hooks: Automatically check Markdown syntax, enforce style guides, or validate image sizes before a commit is created. This ensures content quality and consistency.
• Pre-push hooks: Run a quick Jekyll build locally to catch any build errors before pushing to GitHub, preventing broken deployments.
• Post-receive hooks (server-side): Trigger custom deployments, notifications, or content synchronization after new changes are pushed to your remote repository.

Implementing and managing Git hooks requires direct interaction with the command line.

Submodules and Subtrees for Dependency Management

For more complex Jekyll setups or when integrating external themes, plugins, or shared components, Git submodules or subtrees can be used. These allow you to embed one Git repository as a subdirectory within another.

• Submodules: Useful for including external libraries or themes that you want to keep separate but track within your main project. For instance, you might include a common CSS framework or a Jekyll theme as a submodule.
• Subtrees: A more flexible way to manage external dependencies, allowing you to merge a subtree of another repository into your own and then push changes back to the original.

While powerful for managing complex dependencies, these features are managed entirely through Git CLI commands (e.g., git submodule add, git subtree add) and are not supported by GitHub Desktop.

Reflog and Repository Recovery

Every time your head (the current commit you are on) is updated, Git stores that information in a reference log, or reflog. This is a powerful safety net that allows you to recover "lost" commits or reset states that you thought were gone.

If you accidentally reset to the wrong commit, deleted a branch, or somehow ended up in a strange state, git reflog is your first port of call. It shows a history of where your HEAD has been, allowing you to easily go back to a previous state using git reset. This crucial recovery mechanism is a CLI-exclusive feature and can save you from potentially disastrous data loss.

The CLI as an Automation Powerhouse

Perhaps the most compelling reason to master the Git CLI, especially for a digital marketing blog, is its immense automation capability. Command-line tools are inherently scriptable, allowing you to create custom workflows that streamline your publishing process.

Continuous Integration and Deployment (CI/CD)

For advanced digital marketing strategies, you might want to implement a CI/CD pipeline for your Jekyll site. This means automating the process of building and deploying your blog whenever changes are pushed to GitHub. Services like GitHub Actions, GitLab CI/CD, or Netlify use Git CLI commands under the hood to:

• Fetch the latest changes: git pull
• Build the Jekyll site: This might involve a script that runs bundle exec jekyll build.
• Run tests: Validate links, check for broken images, or even run SEO audits.
• Deploy the site: Copy the built site to a hosting provider or push it to a deployment branch.

This level of automation ensures consistency, reduces manual errors, and speeds up content delivery, all driven by Git CLI commands executed within your CI/CD scripts.

Custom Scripting for Content Management

Beyond CI/CD, you can write simple shell scripts to automate specific content-related tasks. For example:

• A script to automatically generate new post boilerplate files with correct YAML front matter.
• A script that checks all image paths in your Markdown files and reports missing images before committing.
• A script to automatically update internal links across your blog posts when a page URL changes.

These custom solutions can significantly enhance your content management efficiency, and they rely entirely on the power of the Git CLI.

Conclusion

While GitHub Desktop provides a friendly entry point into Git for content creators and those with simpler needs, the Git CLI is where true mastery and versatility reside. It offers unparalleled control over your repository's history, allows for fine-grained staging, provides robust tools for conflict resolution, and is the cornerstone of powerful automation through scripting and CI/CD pipelines.

For digital marketers who aspire to a deeper technical understanding, developers managing complex Jekyll themes, or anyone looking to truly optimize and automate their content publishing workflow, investing time in learning the Git CLI is not just beneficial, but essential. It's about moving beyond basic version control to truly command your projects with precision and efficiency, empowering you to unlock the full potential of Git for your digital marketing endeavors.

generate a contributor page automatically in Jekyll

Why build a contributor page in documentation sites?

Open collaboration thrives on visibility and recognition. Listing contributors not only builds trust and transparency with readers, but also encourages ongoing participation by showing appreciation for contributors' work.

In a Jekyll-based documentation repo, we can automatically create a contributor page by reusing existing metadata—without external databases or plugins.

Step 1: Standardize the author field in front matter

Make sure each post, page, or guide contains a clear author or authors field:

---
title: "API Authentication"
author: "devina"
contributors: ["nita", "aldo"]
---

Use a consistent naming convention, preferably matching GitHub usernames, to allow potential link generation later.

Step 2: Create a data file to enrich author metadata

Define author bios, links, and profile pictures in _data/contributors.yml:

devina:
  name: "Devina Rahma"
  github: "devina-r"
  avatar: "https://avatars.githubusercontent.com/devina-r"
  role: "Lead Technical Writer"

nita:
  name: "Nita Suryani"
  github: "nitas"
  avatar: "https://avatars.githubusercontent.com/nitas"
  role: "Documentation Contributor"

Step 3: Extract all unique contributors

On your contributors.md page, iterate over site content to build a dynamic list:

---
layout: default
title: "Documentation Contributors"
permalink: /contributors/
---

{% raw %}
{% assign authors = "" | split: "" %}
{% for page in site.pages %}
  {% if page.author %}
    {% assign authors = authors | push: page.author %}
  {% endif %}
  {% if page.contributors %}
    {% assign authors = authors | concat: page.contributors %}
  {% endif %}
{% endfor %}

{% assign unique_authors = authors | uniq | sort %}

<div class="contributors-grid">
  {% for username in unique_authors %}
    {% assign profile = site.data.contributors[username] %}
    <div class="contributor-card">
      <img src="{{ profile.avatar }}" alt="{{ profile.name }}" />
      <h3>{{ profile.name }}</h3>
      <p>{{ profile.role }}</p>
      <a href="https://github.com/{{ profile.github }}" target="_blank">@{{ profile.github }}</a>
    </div>
  {% endfor %}
</div>
{% endraw %}

This layout generates a full contributor grid, automatically updated as more files are added.

Step 4: List all documents each person contributed to

{% raw %}
{% assign target = "nita" %}
<h2>Contributions by {{ site.data.contributors[target].name }}</h2>
<ul>
{% for doc in site.pages %}
  {% if doc.author == target or doc.contributors contains target %}
    <li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
  {% endif %}
{% endfor %}
</ul>
{% endraw %}

You can use this block on contributor profile subpages, or even filter via URL params using JavaScript if needed.

Step 5: Show contributor info on each page

At the bottom of each article layout, add:

{% raw %}
{% assign creator = site.data.contributors[page.author] %}
<div class="author-block">
  <img src="{{ creator.avatar }}" alt="{{ creator.name }}" />
  <p>Written by {{ creator.name }} – {{ creator.role }}</p>
  <a href="https://github.com/{{ creator.github }}">GitHub Profile</a>
</div>
{% endraw %}

This adds personal context, authority, and transparency to every article.

Optional: Include commit-based authorship using GitHub Actions

If you want to include people who touched the file even if they didn’t write the original content:

1. Create a script or GitHub Action that parses git log --format='%an' per file
2. Generate a JSON/YAML file with contributor mapping
3. Use that data in addition to front matter for full accuracy

Best practices for contributor credit systems

• Keep _data/contributors.yml updated in PRs
• Use GitHub usernames as keys for cross-referencing
• Avoid hardcoding names in layouts—use data lookup instead
• Add a CONTRIBUTING.md guide to explain how to get credited

Conclusion: Documentation is a community effort—show it

By automating a contributor page in Jekyll, you honor the time and expertise of your team while encouraging new voices to join. You also create a more human-centered documentation experience where readers know exactly who’s behind the work—and who to thank (or ping).

And the best part: once set up, the contributor system runs itself, updating with every pull request and every new guide added to your repo.

Turn a Cloned Jekyll Site Into a Multilingual Website?

Want to Serve Your Jekyll Site in Multiple Languages?

After you clone and modularize your Jekyll theme, one of the most powerful upgrades you can add is multilingual support. Whether you’re publishing documentation, a blog, or a portfolio — localization helps you reach new audiences and markets.

Jekyll doesn’t support multiple languages out-of-the-box, but you can achieve it using smart data structure, flexible layouts, and community plugins.

Step 1: Choose a Multilingual Strategy

There are two common approaches to multilingual Jekyll:

1. Directory-based structure: Separate folders per language (e.g., /en/, /id/, /fr/)
2. Data-driven with plugin: Use jekyll-multiple-languages-plugin to manage translations

We’ll use the second method — cleaner, scalable, and works better with modular cloned themes.

Step 2: Install the Multilingual Plugin

gem "jekyll-multiple-languages-plugin"

Add it to your _config.yml:

plugins:
  - jekyll-multiple-languages-plugin

Specify Supported Languages

languages: ["en", "id", "fr"]
default_lang: "en"
exclude_from_localizations: ["assets", "admin"]

This will tell Jekyll to build a version of your site for each language.

Step 3: Create Translation Data Files

In your _data folder, create YAML files for each language:

_data/translations.en.yml
_data/translations.id.yml
_data/translations.fr.yml

Example Content:

title: "Welcome to My Site"
menu:
  home: "Home"
  about: "About"
  contact: "Contact"

Use those values in includes:

{% raw %}
<nav>
  <a href="/">{{ site.data.translations[site.lang].menu.home }}</a>
</nav>
{% endraw %}

Step 4: Translate Content Files

Create versions of each content file with language suffixes:

_posts/
  2025-07-01-intro.en.md
  2025-07-01-intro.id.md
  2025-07-01-intro.fr.md

_pages/
  about.en.md
  about.id.md

Each file should have front matter that includes:

lang: en
permalink: /about/
title: "About Us"

Step 5: Localize Includes and Layouts

Update your modular includes to pull text from translation data instead of hardcoding:

{% raw %}
<h1>{{ site.data.translations[site.lang].title }}</h1>
{% endraw %}

You can even pass parameters to includes for flexible rendering:

{% raw %}
{% include section.html 
  heading=site.data.translations[site.lang].cta.title 
  text=site.data.translations[site.lang].cta.description %}
{% endraw %}

Step 6: Add Language Switcher

Let users navigate between language versions:

{% raw %}
<ul class="lang-switcher">
  {% for lang in site.languages %}
    <li>
      <a href="{{ page.url | replace: '/' | prepend: '/' | prepend: lang | append: '/' }}">
        {{ lang | upcase }}
      </a>
    </li>
  {% endfor %}
</ul>
{% endraw %}

Step 7: Configure Build and Deployment

Once localization is active, each language will live under its own path:

• /en/ → default language
• /id/ → Indonesian version
• /fr/ → French version

Use Netlify, GitHub Actions, or Cloudflare Pages with bundle exec jekyll build to generate the multilingual output.

Optional: Use Multilingual Collections

If you use custom collections, add language support in the file structure:

_tutorials/
  welcome.en.md
  welcome.id.md

SEO Tips for Multilingual Sites

• Add hreflang tags in your _includes/head.html
• Customize titles and meta descriptions per language
• Ensure sitemaps include all localized URLs

Example hreflang Tags:

{% raw %}
<link rel="alternate" hreflang="en" href="{{ site.url }}/en{{ page.url }}" />
<link rel="alternate" hreflang="id" href="{{ site.url }}/id{{ page.url }}" />
<link rel="alternate" hreflang="fr" href="{{ site.url }}/fr{{ page.url }}" />
{% endraw %}

Conclusion: Modular Cloning Enables Global Publishing

Forking got you started. Cloning gave you control. Modularizing made your theme reusable. Now, making your Jekyll site multilingual opens the door to global reach and accessibility.

Whether you're running a personal blog, documentation, or business site — internationalization is now within reach, thanks to your clean cloned foundation and the right plugin strategy.

Learn from Popular GitHub Repository Names?

Why Study Real Repository Names?

Instead of theory, this article breaks down real-world examples of repositories that rank well, get widely shared, and build strong credibility. By analyzing their naming structures, patterns, and outcomes, we can uncover strategies that any creator or team can adopt for better results with GitHub Pages.

What Makes a Repository Name “Successful”?

We define “successful” repository names as those that:

• Appear high on search engines (SEO visibility)
• Are shared widely on platforms like Reddit, Twitter, and Product Hunt
• Generate engagement (stars, forks, discussions)
• Support a clear brand, product, or informational resource

Case Study #1: awesome-selfhosted

This repo has become a go-to resource for open-source alternatives. Let’s analyze why:

• Keyword-rich: “selfhosted” targets a strong, evergreen tech niche
• Community branding: The “awesome” prefix aligns it with a known GitHub convention
• Clarity: Anyone seeing the name immediately understands what it offers

🔑 Lesson: Use established naming conventions (like “awesome-”) for visibility and trust, especially in curated lists or resource pages.

Case Study #2: freeCodeCamp/freeCodeCamp

This is one of GitHub’s most starred repositories. While the org and repo names are the same, here’s what works:

• Brand-aligned: Mirrors their main domain and product branding
• Readable and meaningful: No versioning, no obscure words
• Reinforces memorability: Repetition strengthens identity

🔑 Lesson: Align your repository name exactly with your product or company if you intend to build strong brand recognition.

Case Study #3: 30-seconds/30-seconds-of-code

This educational repository went viral multiple times due to:

• Clear value proposition: Short, fast coding tips in under 30 seconds
• Unique phrasing: Not just a generic “javascript-tips” name
• Brand stickiness: Easy to remember and share

🔑 Lesson: If your content has a unique angle, reflect that in the name. It makes SEO and social sharing more effective.

Case Study #4: vercel/next.js

Despite being a technical framework, this name does more than you think:

• Simplicity: Just the product name, no clutter
• SEO power: “next.js” is the keyword developers search for
• Clean branding: Matches website, docs, and all marketing

🔑 Lesson: If your project has a clear single-word or domain-specific name, keep it tight and keyword-focused.

Case Study #5: sw-yx/learn-in-public

This personal branding project gets frequent attention due to:

• Emotional hook: The phrase “learn in public” connects with developer culture
• Readable: Lowercase and spaced with dashes
• Shareable identity: It became a movement, not just a repo

🔑 Lesson: If your repo supports a mindset or philosophy, use language that sparks curiosity and shares well.

What Patterns Do These Popular Names Share?

From the above examples, we can distill some patterns:

• Clarity > Cleverness: Descriptive names win over witty ones
• SEO-aware: Keywords are embedded naturally
• No noise: Minimal use of symbols, versioning, or filler words
• Consistency: Matches domain, logo, documentation, and mentions

What Kinds of Names Tend to Underperform?

Conversely, repo names that often underdeliver include:

• final-project-new
• v3-redesign-wip
• test-abc-def
• mywebsite or myapp

These lack clarity, audience targeting, and long-term relevance. They also fail in search engine visibility or credibility when shared publicly.

How to Apply These Lessons to Your Own GitHub Pages Repositories?

When naming your repos, especially those tied to GitHub Pages, ask:

• Can someone understand what this is about just by seeing the name?
• Would I click this link if I saw it shared randomly on Reddit?
• Is this name aligned with the product, topic, or brand?
• Does it contain a target keyword that users would search?

If the answer is “no” to any of these, it might be time to revise.

Conclusion: Inspiration is the Shortcut to Naming Mastery

You don’t have to invent naming strategies from scratch. By studying what works—real repositories with real traction—you can shape your own naming conventions to align with what the internet already favors. Whether you’re building a personal brand, launching an open source tool, or publishing via GitHub Pages, your repo name deserves attention.

When in doubt, look at the top GitHub repos in your niche. Patterns emerge. Mimic what works. Customize to your voice. And let the name do its job: attract, clarify, and elevate.

How Do You Build a Plugin-Friendly Workflow After Cloning a Jekyll Theme?

Ready to Unlock the Full Power of Jekyll Plugins?

Once you clone a Jekyll theme and break free from GitHub Pages restrictions, you gain access to the entire ecosystem of Ruby gems and custom plugins. But many users don’t take full advantage of this newfound freedom.

This article walks you through building a flexible, plugin-friendly workflow after you've converted from a fork to an independent Jekyll project.

Why You Couldn't Use All Plugins Before

GitHub Pages imposes strict limitations on what plugins you can use for security and performance reasons. Only a few "whitelisted" plugins are allowed, and anything outside that list will be ignored unless you build the site locally or externally.

Now that you're using a cloned repo — and ideally deploying with a custom build step — you can enable plugins freely.

Step 1: Create a Clean Gemfile

If your project doesn't already have a Gemfile, create one to manage plugins using Bundler.

source "https://rubygems.org"

gem "jekyll", "~> 4.3"

# Core Plugins
gem "jekyll-seo-tag"
gem "jekyll-sitemap"
gem "jekyll-feed"

# Optional Plugins
gem "jekyll-redirect-from"
gem "jekyll-archives"
gem "jekyll-paginate-v2"
gem "jekyll-include-cache"

# Your Custom Plugin (if any)
# gem "your-plugin-name"

Then run:

bundle install

Step 2: Enable Plugins in Your _config.yml

Add the plugins you want to activate in your main config file:

plugins:
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-feed
  - jekyll-redirect-from
  - jekyll-paginate-v2

Some themes may use the deprecated gems: key — replace it with plugins:.

Step 3: Use Bundle to Build and Serve

Replace old Jekyll commands with Bundler equivalents to ensure plugin compatibility:

bundle exec jekyll serve
bundle exec jekyll build

This guarantees that your project uses the exact versions specified in the Gemfile.lock.

Step 4: Move Your Build Process Off GitHub Pages

If you're still letting GitHub Pages build your site, you're stuck in restricted mode. To unlock plugins, you need to build the site yourself and push the generated _site folder to the deployment platform.

Recommended Hosting Options

• Netlify: Runs bundle exec jekyll build automatically and supports custom plugins
• Cloudflare Pages: Works with custom build commands
• GitHub Actions: Automate builds before pushing to gh-pages branch

Step 5: Explore Advanced Plugins for Real Use Cases

1. SEO and Performance

• jekyll-seo-tag — adds meta tags, Open Graph, and JSON-LD
• jekyll-sitemap — auto-generates your sitemap.xml
• jekyll-minifier — compresses HTML output (third-party)

2. Content Management

• jekyll-paginate-v2 — flexible pagination for blogs, categories, tags
• jekyll-archives — auto-creates yearly/monthly archive pages
• jekyll-include-cache — improves performance with cached includes

3. Navigation and UX

• jekyll-redirect-from — setup redirects from old URLs
• jekyll-toc — automatic table of contents per page
• jekyll-multiple-languages-plugin — multilingual content

Step 6: Split Config Files for Different Environments

For large projects, separate your dev and production configs:

_config.yml
_config.dev.yml
_config.prod.yml

Build with:

bundle exec jekyll build --config _config.yml,_config.prod.yml

Step 7: Version Control Your Dependencies

Keep both Gemfile and Gemfile.lock in your repo. This locks exact plugin versions and avoids build inconsistencies.

Common Mistakes to Avoid

• Missing Bundler: Always use bundle exec when running Jekyll
• Relying on GitHub Pages for plugin builds: It won’t work — use external builds
• Forgetting to declare plugins in _config.yml
• Installing plugins globally: Prefer project-local installation via Gemfile

Conclusion: Cloning Sets You Free — Now Take Control with Plugins

Forking is fast, but limiting. Once you clone a Jekyll project, you're finally in full control. Use that opportunity to build a real development workflow that scales — with SEO tools, custom layouts, redirects, multilingual support, and optimized performance.

You’ve broken the fork. Now unlock Jekyll’s full ecosystem and build something your way.

What Do All These GitHub Terms Mean When Starting a Blog with Jekyll

Why Do GitHub and Jekyll Sound So Complicated at First?

If you’re just starting your blogging journey with GitHub Pages and Jekyll, chances are you’ve already encountered words like “fork,” “repository,” “branch,” or “commit.” They might sound technical or intimidating—but they’re actually just fancy names for simple things you already understand.

How Can You Start Without Feeling Overwhelmed?

The trick is this: you don’t need to master everything at once. You only need to understand just enough to take the next small step. In this guide, we’ll decode the essential terms and explain them in simple, real-world language—so you can keep building your blog without fear or frustration.

What Is a Repository, Really?

A repository (or repo for short) is just a folder. Like the folders on your phone or laptop, it contains files. The only difference is that a repository lives online, inside your GitHub account.

Analogy:

Think of a repository like a Google Drive folder where all your blog’s pages, images, and settings are stored. When you update a file in that folder, GitHub will also update your blog if GitHub Pages is enabled.

What Is GitHub Pages, and Why Do You Need It?

GitHub Pages is a free service by GitHub that lets you turn any folder (repository) into a live website. You don’t need to pay for hosting, install anything, or even have a domain name. GitHub does all the heavy lifting in the background.

Here’s How It Works:

• You create a folder on GitHub.
• You put your website files in that folder.
• You tell GitHub to turn that folder into a live website.

What Is Jekyll, and Why Is It Important?

Jekyll is a tool that takes your text files and turns them into a website. You don’t need to install Jekyll yourself, because GitHub already has Jekyll built-in. When you upload the right kind of files to your GitHub repository, GitHub will automatically use Jekyll to turn them into a blog.

In Simpler Terms:

You write articles in plain text (usually in Markdown), and Jekyll transforms them into a nice-looking blog page with menus, layouts, and themes like Mediumish.

What Does “Fork” Mean in GitHub?

Forking is GitHub’s way of letting you copy someone else’s project to your own account so you can customize it.

Why Fork Instead of Starting from Scratch?

• You get a fully working blog without writing code.
• You can make your own changes and edits without affecting the original version.
• It’s faster, especially for beginners.

Imagine someone shared a ready-to-use blog template with you—forking is just clicking a button to save a copy to your GitHub account.

What Does “Branch” Mean, and Do You Need to Care?

A branch is like a separate version of your folder. The default one is called main or master. Most beginners don’t need to create new branches—they just work inside the main one.

Should You Create Branches?

Not at first. Just stick with the default branch. When you're more confident, you can explore creating branches to test layout or design changes safely.

What Is a Commit?

A commit is like saving a file with a note. Every time you change something—like editing a blog post or uploading an image—you “commit” your changes. This lets GitHub keep track of what you did and when.

How Do You Commit Changes Without Coding?

On GitHub's website, when you edit a file or upload something, you’ll see a field that says “Commit changes.” Just type a short message (like “updated blog post”) and click commit. That’s it.

What Is the `_config.yml` File?

_config.yml is a special file in Jekyll that controls your blog’s settings. You can use it to change your site’s title, author name, menu links, and more.

Think of It Like:

A control panel for your blog. But instead of buttons and sliders, it’s a text file with settings. You don’t have to understand everything—just start by editing the basics like your name, email, and site title.

What Are Markdown Files?

Markdown files are simple text files that use symbols to format content. For example, instead of using a button to make text bold, you use double asterisks like **this**. When Jekyll sees your Markdown file, it converts it into a web page.

Example:

---
title: "My First Post"
date: 2025-07-03
---

This is **bold text** and this is _italic text_.

That’s all you need to write a blog post. Jekyll takes care of the rest.

Why Don’t You Need to Install Anything?

Because GitHub runs Jekyll for you. Everything is done in the cloud, inside your browser. You don’t need to install Jekyll, Ruby, Git, or anything technical on your laptop.

Can You Blog Without Knowing HTML or CSS?

Absolutely. The Mediumish theme already includes HTML and CSS. All you need to do is add your own content in Markdown files. You can edit everything using GitHub’s web interface without writing any code.

Conclusion

GitHub and Jekyll might seem complex at first, but they’re built on simple concepts. A repository is just a folder. A commit is just saving your changes. Forking is copying someone else’s work. With these ideas in mind, you can confidently move forward and start building your blog—even if you’ve never written a single line of code before.

What You Should Remember as a Beginner

• You don’t have to know everything on day one.
• Focus only on what you need to launch your blog.
• Don’t be afraid to experiment—GitHub lets you undo changes anytime.
• Every tech term is just a label for something you already understand.

What’s Next?

In the next article, we’ll guide you through customizing the _config.yml file line by line, with plain English explanations for every setting—so your blog feels like your own.

automate a clean Jekyll repo structure from the start

Why automate the initial structure of a Jekyll project?

When building multiple Jekyll sites—whether for clients, documentation, blogs, or internal tools—it becomes inefficient to manually replicate best practices each time. Errors creep in, folders are misnamed, critical includes get forgotten, and inconsistent layouts affect maintainability.

Automation ensures every project starts with the same clean foundation. It also simplifies onboarding for teams by providing a predictable starting point.

What does a clean Jekyll starter structure include?

A solid starter structure contains:

• Minimal but complete folder hierarchy
• Pre-configured layouts and includes
• Common data files (authors, metadata)
• Placeholder content to test build
• Editable configuration layers

/
├── _config.yml
├── _data/
│   ├── authors.yml
│   └── nav.yml
├── _layouts/
│   ├── base.html
│   ├── post.html
│   └── page.html
├── _includes/
│   ├── head.html
│   ├── header.html
│   └── footer.html
├── _posts/
│   └── 2025-01-01-welcome.md
├── pages/
│   └── about.md
├── assets/
│   ├── css/
│   └── js/
├── .gitignore
├── Gemfile
└── README.md

How can you automate this structure creation?

There are several methods to automate the setup of a Jekyll repository:

1. Use a custom bash or Node.js CLI script

Create a CLI tool that copies predefined folder templates into a new project directory. Example bash script:

#!/bin/bash

echo "Creating Jekyll project: $1"
mkdir "$1"
cd "$1"

mkdir _layouts _includes _posts _data pages assets assets/css assets/js

touch _config.yml Gemfile README.md
echo "---" > _posts/$(date +%Y-%m-%d)-welcome.md

You can enhance it to copy starter layout files, insert license headers, or configure Git remotes automatically.

2. Use GitHub repository templates

Create a master repository with your preferred structure, then mark it as a template repository on GitHub. Whenever you need a new project, click “Use this template” to generate a fresh copy.

This preserves history-less cloning and allows new users to instantly get the best structure—no setup required.

3. Use Jekyll scaffolding tools

While Jekyll's jekyll new command creates a basic scaffold, it’s often too minimal for real-world projects. Instead, create your own starter CLI like jekyll-starter-cli using Ruby or Node.js that wraps:

• Repository cloning
• Dependency installation
• Git initialization and branching
• Environment configuration

4. Use GitHub Actions to validate structure on push

To enforce your structure, include a GitHub Action that checks if all required folders and files exist:

name: Validate Jekyll Structure

on: [push]

jobs:
  check-structure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for essential directories
        run: |
          test -d _layouts || exit 1
          test -d _includes || exit 1
          test -f _config.yml || exit 1

What should be included in your starter repo?

To cover the needs of most projects, include:

• Standard layouts: base.html, post.html, page.html
• Reusable includes: head.html, footer.html, language-switcher.html
• Empty _posts/ folder with a sample post
• _data/authors.yml and _data/nav.yml
• Basic Sass and JavaScript under assets/
• README.md with usage instructions

How do you make this automation reusable across teams?

You can publish your starter in three formats:

• As a public GitHub template repo
• As a private npm package or gem that sets up a project
• As a downloadable zip used with internal CLI tools

Add clear versioning and changelogs to communicate updates. Encourage team members to always begin from the official starter to maintain consistency.

Can you automate content scaffolding too?

Yes. Use script prompts to generate content templates:

bash new-post.sh

Script output:

Enter title: "How to Automate Jekyll Structure"
Creating file: _posts/2025-07-05-how-to-automate-jekyll-structure.md

Resulting file:

---
title: "How to Automate Jekyll Structure"
date: 2025-07-05
layout: post
author: admin
tags: [jekyll,automation]
---

This guarantees naming consistency, date formatting, and front matter correctness.

What naming conventions should be enforced?

Automation also helps enforce naming conventions for:

• File names: kebab-case for posts and pages
• Folders: lowercase only, no spaces
• Permalinks: standardized via front matter

Use linting or custom Git hooks to catch violations before commit.

How does automation contribute to clean repo growth?

With a well-automated setup:

• New projects follow best practices by default
• Teams spend less time on boilerplate and more on content
• Structure is enforced automatically, not just by policy
• Project scaling (e.g. adding languages, content types) becomes predictable

Conclusion: What’s the most efficient way to start clean with Jekyll?

Build once, reuse forever. Automating your Jekyll starter structure saves time, prevents errors, and sets every project on a path toward long-term maintainability. Whether you're creating internal docs, product sites, or SEO-optimized blogs—structure matters. And automation ensures structure is never left to chance.

Treat your starter repo like software: version it, document it, and make it easy for others to use.

What Are All These Files in a Jekyll Theme For

Why Do Jekyll Projects Have So Many Folders?

If you’re a beginner who just cloned a Jekyll theme like Mediumish and opened the folder for the first time, your reaction might be: “What is all this?” There are folders with underscores, strange file names, and code you’ve never seen before. Don’t worry—you’re not alone. This article will guide you through each part of the Jekyll theme folder and explain what it does in the simplest way possible.

Think of the Theme Folder Like a Blog Toolkit

A Jekyll theme is like a toolbox. Each folder or file has a job. Some control the design, some handle your content, and others manage settings. Let’s go through the most important parts, one by one, so you can feel more in control instead of overwhelmed.

What's the First File You Should Look At?

Start with _config.yml. This is your site’s control panel. It has your blog’s name, description, and theme settings. You don’t need to understand everything inside it right away, but it’s the safest place to make your first change—like updating your blog title or adding your name as the author.

What Does _config.yml Control?

• Site title and description (shown in browser or homepage)

• Links to your social profiles

• Settings like pagination, base URL, or custom menus

What Are Those Underscore Folders?

Folders that start with an underscore (_) are special to Jekyll. They're not shown directly on your website, but they control how your website is built.

Common Underscore Folders You’ll See:

1. _posts/

This is where your blog posts go. Each file here is one article, written in Markdown, and must start with the date in the filename. Example: 2025-07-01-my-first-post.md.

2. _layouts/

These are blueprints. A layout defines how pages look. For example, should the post have a sidebar or not? Should the title be big or small? You can pick different layouts for different pages.

3. _includes/

These are small pieces of HTML reused in many places—like the site’s header, footer, or social icons. They help avoid repeating code across pages.

4. _data/

This folder holds files like .yml or .json that store structured information—such as author bios, menu items, or project lists. Instead of hardcoding these in every file, you centralize them here.

5. _site/

This folder is auto-generated when Jekyll builds your site. It contains the final HTML that gets displayed on the web. You don’t edit this folder—it’s like the final printout from a printer.

Where Is the Homepage?

In most themes, the homepage is index.html in the root folder. This file tells Jekyll what layout to use and how to display content. For example, it might say “show the latest 5 posts” using a loop. You can safely edit the text or title here to change what people see first when visiting your blog.

What About Pages Like About or Contact?

Pages like about.md or contact.md are static pages. You can create more by simply adding a new file like projects.md and adding this at the top:

---
layout: page
title: Projects
permalink: /projects/
---

The content after that is what gets shown on the page.

What Is Front Matter and Why Is It Everywhere?

Almost every file in Jekyll starts with a few lines between triple dashes (---). This is called front matter. It tells Jekyll how to treat the file. For example:

---
layout: post
title: My First Post
date: 2025-07-01
categories: [jekyll,beginner]
---

Without front matter, Jekyll won’t know what type of page this is. Always start each content file with this section.

How Do Themes Like Mediumish Work With This Structure?

Mediumish is a pre-designed theme that uses all the pieces above to give your blog a clean, Medium-style layout. It already includes layouts, includes, and styling, so you can focus on writing posts. But you can override or change anything if you want to customize further.

If You Want to Change the Colors or Fonts:

Look inside the assets/css/ or assets/scss/ folders. These control the design. For example, there may be a file like main.scss or custom.scss. Changing a color here will affect the whole site.

What Should a Beginner Do First?

Here’s a good order to explore the project:

1. Open and edit _config.yml to update your site title and description.

2. Write your first post in _posts/ using the proper filename format.

3. Edit index.html to personalize your homepage message.

4. Preview the site locally or push to GitHub to publish.

What Makes Jekyll Different from WordPress?

In WordPress, you manage everything from a dashboard. In Jekyll, you edit text files directly. There’s no admin panel, but also no bloat. This makes Jekyll faster and gives you full control, especially if you’re comfortable editing files and using Git.

Who Is Jekyll Best Suited For?

Jekyll is great for:

• Personal blogs

• Documentation sites

• Portfolios or resumes

If you’re okay learning the basics of Markdown and folder structure, Jekyll can be a rewarding long-term solution.

Final Thoughts

At first glance, the folders and files inside a Jekyll theme may feel like a maze. But once you understand their purpose—content, layout, settings, design—it starts to make sense. You don’t have to learn everything at once. Just start by writing your posts and updating your config file. Over time, you’ll grow more confident exploring the rest.

How Do You Validate and Sanitize External JSON Data in Jekyll Using Ruby

Why Should You Validate External Data in Jekyll?

When fetching data from external APIs or remote JSON feeds, you can’t always trust the structure or content:

• The API may change field names
• The response might be nil or empty
• Unexpected values may break Liquid templates

If not handled properly, this can cause your Jekyll build to crash, silently skip data, or render broken pages.

When Should You Validate?

• Immediately after fetching and parsing external JSON
• Before writing data to _data/
• During Liquid rendering — to handle missing keys safely

Strategy 1: Validate with Ruby Before Saving to _data

Let’s say you fetch GitHub issues and expect each entry to have: - `number` (Integer) - `title` (String) - `html_url` (String) Here’s a Ruby plugin that checks the schema:

# _plugins/validate_github_data.rb
require "net/http"
require "json"
require "fileutils"

def valid_issue?(obj)
  obj["number"].is_a?(Integer) &&
  obj["title"].is_a?(String) &&
  obj["html_url"].is_a?(String)
end

Jekyll::Hooks.register :site, :after_init do |_site|
  uri = URI("https://api.github.com/repos/jekyll/jekyll/issues?per_page=10")
  raw = Net::HTTP.get(uri)
  parsed = JSON.parse(raw)

  valid_data = parsed.select { |i| valid_issue?(i) }

  FileUtils.mkdir_p("_data")
  File.write("_data/github_issues.json", JSON.pretty_generate(valid_data))
end

Strategy 2: Sanitize and Default Missing Values

Let’s say some issues are missing `title` or `url`. You can insert defaults:

def sanitize_issue(issue)
  {
    "number"   => issue["number"] || 0,
    "title"    => issue["title"] || "Untitled Issue",
    "html_url" => issue["html_url"] || "#"
  }
end

cleaned_data = parsed.map { |i| sanitize_issue(i) }

Strategy 3: Detect Invalid Entries and Log Them

parsed.each do |i|
  unless valid_issue?(i)
    puts "[WARN] Invalid issue skipped: #{i.inspect[0..100]}"
  end
end

This logs malformed data in the build console without halting execution.

Strategy 4: Validate in Liquid Templates with Safe Defaults

Even with validated data, it’s smart to protect templates:

<ul>
{% for item in site.data.github_issues %}
  <li>
    <a href="{{ item.html_url | default: '#' }}">
      {{ item.title | default: "No Title" }}
    </a>
  </li>
{% endfor %}
</ul>

Can You Use JSON Schema in Jekyll?

Yes, you can use a Ruby gem like json-schema to validate structure more formally. Add it to your Gemfile:

gem "json-schema"

Then:

require "json-schema"

schema = {
  "type" => "object",
  "required" => ["number", "title", "html_url"],
  "properties" => {
    "number" => { "type" => "integer" },
    "title" => { "type" => "string" },
    "html_url" => { "type" => "string", "format" => "uri" }
  }
}

parsed.each do |obj|
  if JSON::Validator.validate(schema, obj)
    valid_data << obj
  else
    puts "Invalid: #{obj["title"]}"
  end
end

Should You Abort the Build on Invalid Data?

That depends:

• Public-facing website? Better to fail fast to avoid bad UX
• Internal tool or report? Skip and warn is acceptable

Abort the build manually with:

raise "Build failed due to missing API data" if valid_data.empty?

Bonus: Check Network Status Before Fetching

begin
  response = Net::HTTP.get_response(uri)
  raise "API error: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
  parsed = JSON.parse(response.body)
rescue => e
  puts "[ERROR] Failed to fetch API data: #{e.message}"
  parsed = []
end

Conclusion

External data is powerful — but fragile. Always assume the worst:

• Data may be missing, invalid, or broken
• APIs may fail or be rate-limited
• Jekyll build may break if you don’t check

With Ruby schema validation and safe Liquid fallbacks, your Jekyll site can stay reliable and predictable — even when your data isn't.

Next Steps

• Add validations to every external data source
• Wrap your Liquid templates in defaults and conditionals
• Use GitHub Actions or Netlify logs to monitor for build errors

In the next article, we’ll explore **multi-language content using Jekyll, data files, and custom Ruby plugins** — perfect for building multilingual sites without complex CMS setups.

Creating JSON Feeds with Jekyll to Power External Tools

While Jekyll is a static site generator, it is fully capable of outputting structured data formats like JSON. This enables powerful integrations without requiring a traditional CMS or backend server. By exposing content in JSON, you can feed your blog posts into JavaScript apps, search engines, or third-party tools.

Why JSON Feeds Matter for Modern Digital Marketing

Marketing today is omnichannel. You may want to:

• Send the latest posts to a custom email newsletter tool.
• Index posts for client-side search (e.g., Lunr.js or Algolia).
• Build a progressive web app (PWA) or mobile frontend that consumes blog data.
• Use your Jekyll blog as a lightweight headless CMS.

All of these require one thing: structured data—usually in the form of JSON.

Generating a JSON Feed in Jekyll

Jekyll can create any type of file, not just HTML. By creating a custom layout with a .json extension, you can output posts in structured JSON format.

Step 1: Create a Feed File

In your root directory, create a new file called feed.json:

---
layout: jsonfeed
permalink: /feed.json
---

Step 2: Create the JSON Layout

Inside your _layouts/ folder, create a new layout file: jsonfeed.html. This layout will define the structure of your JSON feed:

{
  "version": "https://jsonfeed.org/version/1",
  "title": "{{ site.title | escape }}",
  "home_page_url": "{{ site.url }}",
  "feed_url": "{{ site.url }}/feed.json",
  "description": "{{ site.description | escape }}",
  "items": [
    {% for post in site.posts %}
    {
      "id": "{{ site.url }}{{ post.url }}",
      "url": "{{ site.url }}{{ post.url }}",
      "title": {{ post.title | jsonify }},
      "content_text": {{ post.excerpt | strip_html | strip_newlines | jsonify }},
      "date_published": "{{ post.date | date_to_xmlschema }}"
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ]
}

This outputs a valid JSON Feed (v1 spec) that can be consumed by any JSON parser.

Use Cases for JSON Feeds in Jekyll Mediumish

1. Build a Custom JavaScript Search Engine

You can use the JSON feed to index your posts with Lunr.js or Algolia. Simply fetch /feed.json and process the items array. Here’s a simplified example:

fetch('/feed.json')
  .then(response => response.json())
  .then(data => {
    data.items.forEach(post => {
      console.log(post.title, post.url);
    });
  });

This allows real-time search on the frontend without relying on plugins or server processing.

2. Populate a Newsletter Tool Automatically

If you use an email service that supports RSS/JSON feeds (like Mailchimp, EmailOctopus, or Buttondown), you can automate sending new blog posts. Just point the service to your /feed.json URL.

3. Serve JSON to a JavaScript Frontend

You can use the JSON output as the "API" for your blog, and build a modern frontend with React, Vue, or Svelte. Even if your blog is static, your frontend can feel dynamic, pulling in content and rendering it client-side.

4. Enable External App Integration

For marketers running automation tools, the JSON feed provides a stable, machine-readable entry point for services like:

• Zapier (via Webhooks)
• IFTTT
• Headless CMS integrations

Creating JSON per Post for Granular Access

Beyond a global /feed.json, you can also expose each post as individual JSON. To do this:

Step 1: Create a New Layout

Make a layout file named jsonpost.html inside _layouts/:

{
  "id": "{{ page.url }}",
  "title": {{ page.title | jsonify }},
  "content": {{ content | strip_newlines | jsonify }},
  "date": "{{ page.date | date_to_xmlschema }}"
}

Step 2: Use a New Permalink Style

In your post front matter, set a permalink to generate a JSON version:

---
layout: jsonpost
permalink: /posts/my-post.json
---

Now you can access each post in JSON via /posts/my-post.json.

Tips for Clean and Valid JSON Output

• Always use the jsonify filter to escape characters properly.
• Use strip_newlines to prevent unwanted line breaks.
• Test your output in a JSON linter like JSONLint.

Final Thoughts: Using Jekyll as a Lightweight API

Even though Jekyll doesn’t run on a server, it’s powerful enough to expose structured data for many use cases. With JSON feeds, your Mediumish-based blog becomes much more than a publishing tool—it becomes a data source that can integrate with virtually any modern platform or frontend.

From automating marketing campaigns to building dynamic interfaces, JSON opens up your content for reuse, remixing, and reach far beyond a static site.

Why Is My Jekyll Theme Broken on GitHub Pages

Common Reasons Jekyll Themes Fail on GitHub Pages

You’ve installed a Jekyll theme like Mediumish, committed it to your GitHub repository, and enabled GitHub Pages—only to see a broken layout, missing styles, and 404 errors. This is a common frustration that new users experience when working with GitHub Pages.

Understanding the Root Causes

The most common reasons for a broken Jekyll theme on GitHub Pages boil down to:

• Incorrect baseurl configuration
• Wrong asset paths (CSS, JS, images)
• Theme assets not included or not found
• Missing plugin support (GitHub Pages safe mode restrictions)
• Using a custom domain without path adjustments

The Role of Baseurl in Project Sites

When deploying a Jekyll site as a project site (not a user site), your site will live in a subdirectory like /your-repo-name. Every asset must therefore be prepended with that subdirectory path using baseurl.

Symptoms of Incorrect Baseurl

• Your homepage loads, but no CSS styling is applied.
• Links to blog posts or pages return 404 errors.
• Images appear broken or not at all.

Solution:

Edit your _config.yml file and add:

baseurl: "/your-repo-name"
url: "https://yourusername.github.io"

In your layout and includes, always use:

<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/main.css">

Why Themes Like Mediumish Break Easily Without Adjustments

The Mediumish theme, like many Jekyll themes, assumes a base path of `/`, meaning it works perfectly only in user sites unless modified. This becomes an issue when deployed as a project site.

Checklist for Making Mediumish Theme Work on GitHub Pages

• Set baseurl in _config.yml
• Update all asset links to include {{ site.baseurl }}
• Use {{ site.url }}{{ site.baseurl }} for absolute URLs in meta tags
• Do not use hardcoded paths like /assets/

Asset Path Troubleshooting

If your fonts, logos, images, or stylesheets don’t show up, double check your theme files for hardcoded asset paths.

How to Fix Them

Replace all occurrences of paths like:

/assets/css/style.css

With:

{{ site.baseurl }}/assets/css/style.css

Using Themes with GitHub Pages-Safe Plugins

GitHub Pages runs Jekyll in a “safe mode,” which means certain plugins won’t work unless you're building the site locally and pushing the compiled site.

What This Means

• Custom plugins like pagination or tag generators may not run
• You must pre-build locally with bundle exec jekyll build
• Then push the _site folder to a separate branch like gh-pages

Alternative:

Use GitHub Actions to build the site on push. This allows full plugin support and a cleaner CI/CD workflow.

How to Verify Your Theme Build Locally

Always test your site locally with the correct baseurl before pushing to GitHub:

bundle exec jekyll serve --baseurl "/your-repo-name"

This emulates the GitHub Pages environment for a project site. Navigate to http://localhost:4000/your-repo-name/ to check if all links and styles work correctly.

How GitHub Pages Deployment Branch Affects Output

Make sure you are deploying the correct branch. For user sites, this is usually main. For project sites, you can choose main, gh-pages, or even /docs folder.

How to Set It

Go to your repository → Settings → Pages and configure:

• Source: main or gh-pages
• Folder: / (root) or /docs

Using Mediumish Without Breaking URLs

Many Mediumish users experience broken links because of hardcoded slugs or incorrect permalink structures. Double check your permalink settings in _config.yml:

permalink: /:categories/:title/

Also verify that your post filenames are in this format:

YYYY-MM-DD-title.md

Recap: Steps to Fix a Broken Jekyll Theme on GitHub Pages

1. Set baseurl Properly

Use the correct baseurl value in _config.yml and apply it in all links, assets, and internal paths.

2. Replace Hardcoded Paths

Search your theme’s layout and include files for paths that start with a slash and replace them with {{ site.baseurl }}/.

3. Test Locally with Baseurl

Use the --baseurl flag to simulate deployment behavior before pushing to GitHub.

4. Set the Correct Deployment Branch

For project sites, choose either the gh-pages branch or the /docs folder, then verify the result.

5. Use GitHub Actions for Full Plugin Support

If your theme uses unsupported plugins, set up GitHub Actions to build and deploy the site automatically.

Conclusion

If your Jekyll theme looks broken on GitHub Pages, it’s almost always due to misconfigured baseurl, broken paths, or GitHub’s plugin limitations. Understanding how GitHub Pages works and how your theme expects to be deployed makes all the difference between a broken blog and a beautiful one.

With the right setup, you can take full advantage of modern Jekyll themes like Mediumish and enjoy a free, elegant blogging experience powered by GitHub Pages.

What Settings Should You Configure After Creating a GitHub Repository

Why Are Post-Creation Settings Important in a GitHub Repository

Once you've created a new GitHub repository for your Jekyll-based blog, especially using the Mediumish theme, you're only halfway done. Most beginners overlook the vital configuration settings that determine whether your blog will render properly, be indexed by search engines, or even deploy at all. Understanding and optimizing your repository settings ensures smooth integration with GitHub Pages, secure access, and faster setup.

What Are the Key Areas You Need to Configure

After the repository is created, the following areas must be reviewed:

• Repository visibility
• Branch configuration
• GitHub Pages source setting
• Web URL preview
• Repository metadata
• Collaborator and access control
• License and readme verification

How to Set the Correct GitHub Pages Branch and Folder

For Jekyll to work with GitHub Pages, you must set the correct deployment source. This can be configured under the repository’s Settings → Pages tab.

Steps to Set GitHub Pages Source Correctly

1. Go to your repository
2. Click Settings
3. Scroll down to the Pages section
4. Under Source, choose:
   • Deploy from a branch
   • Select the branch: usually main
   • Folder: select / (root) if your Jekyll files are directly in the root
5. Click Save

After setting this, GitHub will trigger a build and assign a live site URL (e.g. https://yourusername.github.io/repositoryname/).

What Visibility Setting Should You Use for a Jekyll Blog

By default, new repositories are public, which is required if you’re using GitHub Pages to host your blog without a paid plan. Private repositories will not work with GitHub Pages unless you have a GitHub Pro subscription and use custom workflows. Therefore, ensure your repo is set to public:

How to Check and Change Repository Visibility

1. Go to your repository Settings
2. Scroll to Danger Zone
3. Look for “Change repository visibility”
4. If it’s private, click Make public

Always double-check this after creation, especially if you plan to link the blog publicly.

Should You Enable GitHub Pages Build Logs

Yes. GitHub now provides better logging and error messages when your Pages site fails to deploy. Enabling this helps troubleshoot YAML errors, missing theme files, or Jekyll configuration problems.

How to Access Build Logs

Once GitHub Pages is set up:

• Go to the Actions tab
• Filter for the Pages build workflow
• Click the most recent run to see logs and failure reasons

Do You Need to Add a Custom Domain at This Stage

Not yet. For now, use the default GitHub Pages subdomain. Once your site is live and working properly, you can assign a custom domain later. However, if you do want to use one:

How to Add a Custom Domain (Optional)

1. Buy a domain from a registrar like Namecheap or Google Domains
2. Point its DNS to GitHub Pages IPs
3. In GitHub, go to Settings → Pages
4. Add your domain under the “Custom domain” field

Make sure to check the box “Enforce HTTPS” if using a custom domain.

How to Write an Accurate Repository Description and Tags

Descriptions help both GitHub’s internal search and external users understand what your repo is about. Here’s how to write them effectively:

Tips for a Good Repository Description

• Keep it short but descriptive, e.g. A minimalist blog using Jekyll and Mediumish theme
• Use relevant topics/tags like jekyll, blog, theme, github-pages
• Avoid vague descriptions like “My website”

Should You Add a License and README File

Yes, especially if you're using an open-source theme like Mediumish. A license clarifies usage rights, while a README file documents how to use or modify the blog. GitHub even provides templates for both.

How to Add These Files

• Go to the main repository page
• Click Add file → Create new file
• For license, name it LICENSE and choose from available templates
• For README, create README.md and write a brief guide

How to Invite Collaborators or Set Permissions

If you're working with others, set access roles to avoid accidental changes.

Steps to Add Collaborators

1. Go to Settings → Collaborators & teams
2. Click Add people
3. Type the GitHub username and choose their role:
   • Admin: full access
   • Write: can push commits
   • Read: view only

How to Ensure the Repository is Ready for Theme Installation

Once you’ve configured all the above settings, the repository is now ready to install the Mediumish Jekyll theme. Make sure the following is true:

• Public visibility is set
• GitHub Pages is pointing to the right branch and folder
• A README exists for clarity
• Build logs are working and error-free

Conclusion

Setting up a GitHub repository correctly after creation is a foundational step to successfully launching a Jekyll blog, particularly with more complex themes like Mediumish. Neglecting these steps can lead to confusing errors, deployment failures, or broken websites. By following this guide, your repository will be fully optimized, clean, and ready for the next stage: installing the Jekyll theme and customizing your site.