Jekyll Site Guide

This site is built with Jekyll and hosted on GitHub Pages. This guide will help you manage and update the site.

Getting Started
Writing Blog Posts
Site Structure
Local Development
Deployment
Customization

Getting Started

Prerequisites

Ruby (2.7.0 or higher)
Bundler
Git

Installation

Clone the repository:

git clone https://github.com/stu-jc/stu-jc.github.io.git
cd stu-jc.github.io

Install dependencies:
```
bundle install
```
Run the site locally:
```
bundle exec jekyll serve
```
Visit http://localhost:4000 in your browser

Writing Blog Posts

Creating a New Post

Create a new file in the _posts/ directory
Use the naming convention: YYYY-MM-DD-title.md
Add front matter at the top of the file

Post Template

---
layout: post
title: "Your Post Title"
date: 2024-11-16
author: Joshua Chelashaw
tags: [tag1, tag2, tag3]
categories: [category]
description: "A brief description for SEO (160 chars max)"
reading_time: 5
---

Your post content starts here. You can use Markdown formatting.

## Headings

Use `##` for main sections within your post.

### Subheadings

Use `###` for subsections.

## Code Blocks

\`\`\`python
def hello_world():
    print("Hello, World!")
\`\`\`

## Images

![Alt text](/path/to/image.jpg)

## Links

[Link text](https://example.com)

Front Matter Fields

layout: Always use post for blog posts
title: The post title (required)
date: Publication date in YYYY-MM-DD format (required)
author: Your name
tags: Array of tags for categorization
categories: Array of categories
description: SEO description (recommended)
reading_time: Estimated minutes to read

Tags vs Categories

Tags: Specific topics (e.g., python, tutorial, finance)
Categories: Broader groupings (e.g., technical, personal, projects)

Site Structure

.
├── _config.yml           # Site configuration
├── _includes/            # Reusable components
│   ├── head.html         # <head> section with SEO
│   ├── header.html       # Site header
│   ├── footer.html       # Site footer
│   └── navigation.html   # Navigation menu
├── _layouts/             # Page templates
│   ├── default.html      # Base template
│   ├── home.html         # Homepage template
│   ├── page.html         # Standard page template
│   ├── post.html         # Blog post template
│   └── project.html      # Project detail template
├── _posts/               # Blog posts
├── _projects/            # Project collection (optional)
├── blog/                 # Blog index page
├── assets/               # Static assets
├── style.css             # Main stylesheet
├── index.md              # Homepage
└── Gemfile               # Ruby dependencies

Local Development

Start the development server:

bundle exec jekyll serve

With live reload:

bundle exec jekyll serve --livereload

With drafts visible:

bundle exec jekyll serve --drafts

Build for production:

bundle exec jekyll build

The built site will be in the _site/ directory.

Deployment

Automatic Deployment (Recommended)

Commit your changes:

git add .
git commit -m "Your commit message"

Push to GitHub:
```
git push origin main
```
GitHub Pages automatically builds and deploys your site!

Manual Build

If needed, you can build locally and push the _site/ directory, but automatic deployment is preferred.

Customization

Changing Site Information

Edit _config.yml:

title: Your Name
email: your@email.com
description: Your site description

Edit _includes/navigation.html to add or remove navigation items.

Modifying Styles

The main stylesheet is style.css. It uses CSS custom properties (variables) for easy theming:

:root {
    --color-accent: #0066cc;
    --color-background: #fafafa;
    /* ... more variables */
}

Adding Pages

Create a new .md or .html file in the root directory with front matter:

---
layout: page
title: About
---

Your content here...

SEO & Analytics

The site includes jekyll-seo-tag for automatic SEO optimization. To add Google Analytics:

Uncomment in _config.yml:
```
google_analytics: UA-XXXXXXXX-X
```
Add your tracking ID

Tips & Best Practices

Always test locally before pushing to production
Use descriptive commit messages for version control
Optimize images before adding them to your site
Write SEO descriptions for all posts and pages
Use tags consistently to help readers find related content
Preview your posts in both light and dark mode
Check mobile responsiveness before publishing

Troubleshooting

Dependency Issues

bundle update
bundle install

Clear Cache

bundle exec jekyll clean

Rebuild Everything

bundle exec jekyll build --force

Port Already in Use

bundle exec jekyll serve --port 4001

Resources

Need Help?

If you encounter issues:

Check the Jekyll Documentation
Search Stack Overflow
Check GitHub Pages status

Happy blogging! 🚀