Development Setup

Development Setup

This document explains how to set up and run the portfolio site locally for development.

Prerequisites

  • Ruby (version 3.0+)
  • Bundler gem
  • Git

Quick Start

The easiest way to start development:

./dev-server.sh

This script will:

  • Check if dependencies are installed
  • Install gems if needed
  • Start Jekyll with live reload and development settings
  • Serve the site at http://localhost:4000

Option 2: Using VS Code Tasks

If you’re using VS Code:

  1. Open the Command Palette (Cmd+Shift+P)
  2. Type “Tasks: Run Task”
  3. Select “Jekyll Serve (Development)”

Available tasks:

  • Jekyll Serve (Development): Full development server with live reload
  • Jekyll Serve (Basic): Basic server without extra features
  • Jekyll Build: Build the site without serving
  • Bundle Install: Install/update gem dependencies

Option 3: Manual Commands

# Install dependencies
bundle install

# Start development server
bundle exec jekyll serve --config _config.yml,_config_dev.yml --livereload --drafts --incremental

# Or basic server
bundle exec jekyll serve

# Build only (no server)
bundle exec jekyll build

Development Features

The development setup includes:

  • Live Reload: Browser automatically refreshes when files change
  • Draft Posts: Include posts marked as drafts
  • Incremental Build: Faster builds by only processing changed files
  • Development Config: Overrides production settings
  • Verbose Output: More detailed build information

Configuration

Development vs Production

  • Production (_config.yml): Used for GitHub Pages deployment
  • Development (_config_dev.yml): Extends production config with dev-specific settings

Development URLs

  • Local site: http://localhost:4000
  • Live reload: http://localhost:35729 (automatic)

File Structure

├── _config.yml           # Production configuration
├── _config_dev.yml       # Development configuration overrides
├── dev-server.sh         # Quick start script
├── .vscode/
│   └── tasks.json        # VS Code development tasks
└── .github/workflows/
    ├── deploy.yml        # Production deployment
    └── dev-build.yml     # Development build testing

Troubleshooting

Port Already in Use

If port 4000 is busy:

bundle exec jekyll serve --port 4001

Gem Installation Issues

Update RubyGems and Bundler:

gem update --system
gem install bundler
bundle update

Live Reload Not Working

  1. Check if the browser supports WebSockets
  2. Disable browser extensions that might block WebSockets
  3. Try running without live reload: 
    bundle exec jekyll serve --no-livereload

GitHub Actions Development Testing

You can test the build process in GitHub Actions:

  1. Go to Actions tab in your repository
  2. Run “Development Build Test” workflow
  3. Optionally specify how long to run the test server
  4. Download the built site artifact to inspect

Making Changes

  • Content: Edit Markdown files in _posts/, _projects/, or pages
  • Styles: Edit SCSS files in _sass/ or assets/css/
  • Layout: Edit HTML files in _layouts/ and _includes/
  • Configuration: Edit _config.yml for production or _config_dev.yml for development

The development server will automatically rebuild and refresh the browser when you save changes.