Start Your Blog with Jekyll

What is Jekyll?

Jekyll is a static website generator that transforms plain text into static websites and blogs. It’s perfect for developers who want a simple, fast, and customizable blogging platform.

---

Installation

To get started with Jekyll, visit the official Jekyll website for installation instructions and documentation.

---

Initialization

1. Create a New Jekyll Site

Run the following command to create a new site:

jekyll new my-jekyll-site

This creates a folder named my-jekyll-site with the default Jekyll structure.

2. Navigate to the Site Folder

cd my-jekyll-site

3. Install Dependencies

Install any required dependencies using Bundler:

bundle install

4. Preview Your Site Locally

Run the site on a local development server:

bundle exec jekyll serve

Open your browser and go to http://127.0.0.1:4000 to view the site.

5. Customize Your Site

Open _config.yml to set your site’s title, description, author, etc. Example:

title: My Jekyll Site
description: A blog about my journey
author: Fengyi

6 . Add Content

Blog Posts: Add Markdown files to _posts/ following the format YYYY-MM-DD-title.md. Example content for a post:

---
layout: post
title: "My First Post"
date: 2025-01-18
---

Welcome to my first blog post! Pages: Create .html or .md files in the root directory (e.g., about.md).

7. Use Themes

• Find themes at Jekyll Themes or the official directory.
• Add a theme to your _config.yml:

  theme: minima
  

• Install it via Bundler:

  bundle install
  

8. Build the Site

To generate the static site files (output to _site/):

bundle exec jekyll build

9. Deploy Your Site

• GitHub Pages: Push your repository to GitHub, and it will be hosted automatically. Update _config.yml for GitHub Pages:

  baseurl: "/my-repo-name"
  url: "https://username.github.io"
  

File Structure

The Jekyll file structure organizes your project in a way that separates content, layouts, and configurations for building a static site. Here’s an overview of the default structure:

├── _config.yml
├── _includes/
├── _layouts/
├── _posts/
├── _data/
├── _drafts/
├── _site/
├── assets/
│   ├── css/
│   ├── js/
│   ├── images/
├── _sass/
├── collections/
├── Gemfile
├── Gemfile.lock
├── index.html

1. _config.yml
   • The main configuration file for your site.
   • Contains settings such as site title, description, base URL, and theme options.
   • Example:

     title: My Jekyll Site
     description: A simple blog
     baseurl: "/blog"
     

2. _includes/
   • Stores reusable snippets of HTML, such as headers, footers, or navigation bars.
   • Use {\% include filename.html \%} to embed these snippets in other files.
3. _layouts/
   • Contains HTML templates that define the structure of your site.
   • Files like default.html or post.html go here and can be applied to pages or posts.
4. _posts/
   • Contains your blog posts or articles.
   • Files must be named in the format YYYY-MM-DD-title.md or .html.
   • Example: 2025-01-18-my-first-post.md.
5. _data/
   • Holds YAML, JSON, or CSV files that store data for your site, such as menus or project lists.
   • Access this data with the site.data object in Liquid templates.
6. _drafts/
   • Unpublished posts. These won’t appear on your live site until published.
   • Use jekyll serve --drafts to preview them locally.
7. _site/
   • The output folder where Jekyll generates your static site.
   • Don’t edit files here; they are overwritten during builds.
8. assets/
   • Contains static files like CSS, JavaScript, and images.
   • Organize subdirectories for better management (css/, js/, images/).
9. _sass/
   • Contains partial .scss files for managing styles in a modular way.
   • Combine these in your main .scss file, which should be placed in the assets/ directory.
10. collections/
    • Optional folder for custom content types (e.g., portfolios, tutorials).
    • Define collections in _config.yml to use this feature.
11. Gemfile & Gemfile.lock
    • Manage Ruby gems for Jekyll and its plugins.
    • Run bundle install to install dependencies.
12. index.html or index.md
    • The homepage of your site.
    • This can be customized to display content dynamically or statically.

PermaLink

permalink: /:categories/:year/:month/:day/:title

Create a page

Create a markdown file name contact at root using yml format

---
layout: page
title: contact
---
Contact me

Theme

Go to rubygems.org to serach for jekyll-theme

Try localhost:4000/contact to access the page. Find a theme and click homepage link in Github and view the theme.

I found midnight theme look pretty asowme. in the Gemfile, add the following line

gem "midnight"

remote_theme: pages-themes/midnight@v0.2.0
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one

Intall the theme

boundle install

In the config.yml

change theme midnihgt

theme: midnight

Remote theme

To use the Midnight theme:

Add the following to your site’s _config.yml:

remote_theme: pages-themes/midnight@v0.2.0
plugins:
- jekyll-remote-theme # add this line to the plugins list if you already have one

Execute and run server

bundle exec jekyll serve

Alternative remote theme

1. Add the following to your Gemfile

   jekyll-remote-theme
   

   and run bundle install to install the plugin

2. Add the following to your site’s _config.yml to activate the plugin

   plugins:
     - jekyll-remote-theme
   

   Note: If you are using a Jekyll version less than 3.5.0, use the gems key instead of plugins.

3. Add the following to your site’s _config.yml to choose your theme

   remote_theme: benbalter/retlab
   

   or

   remote_theme: http[s]://github.<Enterprise>.com/benbalter/retlab
   

   However, if the page does not show up, make sure we change layout to default since some theme has no page and home layout.

In the theme you like, check layouts if will find what layout it support

Troubleshooting

-Port occupied: Try Ctrl+c or use the following command to kill the process:

ps aux |grep jekyll |awk '{print $2}' | xargs kill -9

• Post Not Showing Up Jekyll only shows posts with dates up to the current date.