Welcome to your personal blog repository! This README will guide you through setting up Jekyll, integrating the Carbon Design System, deploying to GitHub Pages, and writing blog posts.
Jekyll requires Ruby. On macOS, you can install Jekyll with:
# Install Ruby (if not already installed)
brew install ruby
# Add Ruby to your PATH (if needed)
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
# Install Jekyll and Bundler
gem install jekyll bundlerJekyll uses these folders:
_layouts(HTML templates)_includes(reusable HTML)_posts(your blog posts)index.mdorindex.html(homepage)
To scaffold a new site:
jekyll new .Add Carbon CSS/JS to your main layout (_layouts/default.html):
<!-- In the <head> section -->
<link rel="stylesheet" href="https://unpkg.com/carbon-components/css/carbon-components.min.css">
<script src="https://unpkg.com/carbon-components/scripts/carbon-components.min.js"></script>Use Carbon classes in your HTML for strict dark theme compatibility. Example:
<section class="bx--grid bx--grid--condensed bx--grid--full-width bx--theme--g100">
<!-- ... -->
</section>Create a new file in _posts with this format:
YYYY-MM-DD-title.md
Example:
2025-09-14-my-first-post.md
Inside, use:
---
layout: default
title: My First Post
---
<section class="bx--grid bx--theme--g100">
<article class="bx--card bx--card--dark">
<h2>{{ page.title }}</h2>
<p>Welcome to my blog!</p>
</article>
</section>
Run Jekyll locally to preview your site:
bundle exec jekyll serveVisit http://localhost:4000 in your browser.
- Push your code to a GitHub repository (e.g.,
selim.github.io). - In your repo settings, enable GitHub Pages (choose branch:
masterormain). - GitHub will build and deploy your site automatically.
Create a new file in the _posts directory with this naming format:
_posts/YYYY-MM-DD-title-with-hyphens.md
Example: _posts/2025-09-14-my-awesome-new-post.md
Start your post with YAML front matter:
---
layout: post
title: "My Awesome New Post"
date: 2025-09-14 15:30:00 -0400
categories: [technology, tutorial]
tags: [jekyll, carbon, web-development]
author: Selim
---Write your post content in Markdown below the front matter:
# This is a heading
This is a paragraph with **bold** and *italic* text.
- List item 1
- List item 2
```code blocks are supported```
[Links work too](https://example.com)Test your post locally before publishing:
bundle exec jekyll serveVisit http://localhost:4000 to see your changes.
-
Stage your changes:
git add . -
Commit your post:
git commit -m "Add new post: My Awesome New Post" -
Push to GitHub:
git push origin master
-
Automatic deployment: GitHub Pages will automatically build and deploy your site within 1-2 minutes.
-
Enable GitHub Pages:
- Go to your repository on GitHub
- Click "Settings" tab
- Scroll down to "Pages" section
- Under "Source", select "Deploy from a branch"
- Choose "master" branch and "/ (root)" folder
- Click "Save"
-
Custom Domain (Optional):
- Add a
CNAMEfile with your domain name - Configure your DNS to point to GitHub Pages
- Add a
Any changes you push to the master branch will automatically trigger a rebuild:
- Make your changes (new posts, design updates, etc.)
- Commit and push:
git add . git commit -m "Description of changes" git push origin master
- GitHub automatically builds and deploys your site
- Check deployment status in the "Actions" tab of your repository
- Build time: Usually 1-2 minutes
- Check status: Repository → Actions tab
- View live site:
https://yourusername.github.io - Troubleshooting: Check the Actions tab for build errors
If you need help, open an issue or ask for guidance!