Local Development Guide

Local Development Guide

This guide will help you set up and run Jordan Matelsky’s blog locally for development.

Prerequisites

Before you begin, ensure you have the following installed on your macOS system:

  • Ruby (2.5 or higher)
  • Bundler gem
  • Git
  • Jekyll

Initial Setup

1. Install Ruby and Dependencies

If you don’t have Ruby installed or need a newer version, we recommend using rbenv:

# Install rbenv
brew install rbenv ruby-build

# Install latest stable Ruby
rbenv install 3.1.0
rbenv global 3.1.0

# Add rbenv to your shell profile
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

2. Install Bundler and Jekyll

gem install bundler jekyll

3. Clone the Repository

git clone https://github.com/j6k4m8/j6k4m8.github.io.git
cd j6k4m8.github.io

4. Create a Gemfile

Since this project doesn’t have a Gemfile, create one for local development:

cat > Gemfile << 'EOF'
source "https://rubygems.org"

gem "jekyll", "~> 4.3"
gem "kramdown-parser-gfm"

group :jekyll_plugins do
  gem "jekyll-sitemap"
end

# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
  gem "tzinfo", ">= 1", "< 3"
  gem "tzinfo-data"
end

# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]

# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
# do not have a Java counterpart.
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
EOF

5. Install Dependencies

bundle install

Running the Site Locally

Development Server

To start the Jekyll development server:

bundle exec jekyll serve

Your site will be available at: http://localhost:4000

Development Server with Live Reload

For automatic reloading when files change:

bundle exec jekyll serve --livereload

Development Server with Drafts

To include draft posts in your local build:

bundle exec jekyll serve --drafts

Development Server on a Different Port

If port 4000 is in use:

bundle exec jekyll serve --port 4001

Site Structure

Understanding the project structure:

├── _config.yml          # Main configuration file
├── _posts/              # Published blog posts
├── _drafts/             # Draft posts (not published)
├── _layouts/            # HTML templates
├── _includes/           # Reusable HTML snippets
├── _sass/               # Sass/SCSS stylesheets
├── assets/              # Images and other static files
├── playlists/           # Custom playlist pages
├── style.scss           # Main stylesheet
├── index.html           # Homepage
├── about.md             # About page
└── 404.md              # 404 error page

Writing Content

Creating a New Post

  1. Create a new file in _posts/ with the format: YYYY-MM-DD-title.md
touch _posts/$(date +%Y-%m-%d)-my-new-post.md
  1. Add front matter to your post:
---
layout: post
title: Your Post Title
tags:
    - tag1
    - tag2
    - tag3
---
Your post content goes here...

Creating a Draft

  1. Create a file in _drafts/ without a date prefix:
touch _drafts/my-draft-post.md
  1. Add front matter similar to posts
  2. View drafts locally using --drafts flag

Adding Images

  1. Place images in assets/img/
  2. Reference them in posts using:
![Alt text](https://blog.jordan.matelsky.com/assets/img/your-image.jpg)

Configuration

Key Configuration Options

The main configuration is in _config.yml. Important settings:

  • Site Information: Name, description, avatar
  • Social Links: Footer links configuration
  • Analytics: Google Analytics tracking code
  • URL Settings: Base URL and site URL
  • Markdown: Uses Kramdown with GFM input
  • Syntax Highlighting: Rouge highlighter

Local vs Production URLs

For local development, the site uses:

  • Local URL: http://localhost:4000
  • Production URL: https://blog.jordan.matelsky.com

Styling and Customization

SCSS Files

The site uses Sass for styling:

  • style.scss - Main stylesheet that imports partials
  • _sass/_variables.scss - Color and font variables
  • _sass/_reset.scss - CSS reset rules
  • _sass/_highlights.scss - Syntax highlighting styles
  • _sass/_svg-icons.scss - Social media icon styles

Fonts

The site uses Google Fonts:

  • Body Font: Inter (sans-serif)
  • Header Font: Roboto Slab (serif)

Common Development Tasks

Building the Site

To build the site without serving:

bundle exec jekyll build

Output will be in _site/ directory.

Cleaning Build Files

bundle exec jekyll clean

Checking for Issues

bundle exec jekyll doctor

Troubleshooting

Common Issues

  1. Ruby Version Issues: Ensure you’re using Ruby 2.5+
  2. Gem Conflicts: Try bundle clean then bundle install
  3. Port Already in Use: Use --port flag with different port number
  4. Syntax Errors: Check your Markdown and YAML front matter syntax

Checking Ruby Version

ruby --version

Updating Dependencies

bundle update

Deployment

This site is deployed to GitHub Pages. When you push to the main branch, GitHub automatically builds and deploys the site.

For local testing before pushing:

# Build and serve locally
bundle exec jekyll serve

# Build for production
JEKYLL_ENV=production bundle exec jekyll build

Additional Resources

Quick Reference

Essential Commands

# Start development server
bundle exec jekyll serve

# Start with drafts and live reload
bundle exec jekyll serve --drafts --livereload

# Build site
bundle exec jekyll build

# Clean build files
bundle exec jekyll clean

# Install/update dependencies
bundle install
bundle update

File Naming Conventions

  • Posts: YYYY-MM-DD-title.md
  • Drafts: title.md (no date prefix)
  • Pages: filename.md or filename.html
  • Images: Place in assets/img/

Happy blogging! 🚀