Getting Started

This guide will help you set up and run the johnoct.github.io website locally for development.

Prerequisites

Before you begin, ensure you have the following installed:

• Ruby 2.7+ (recommended: use Homebrew on macOS)
• Bundler gem for managing Ruby dependencies
• Git for version control
• GitHub CLI (optional, for GitHub stars automation)

Installation

1. Install Ruby (macOS with Homebrew)

# Install Ruby via Homebrew
brew install ruby

# Add Ruby to your PATH (add to ~/.zshrc or ~/.bash_profile)
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
export PATH="/opt/homebrew/lib/ruby/gems/3.4.0/bin:$PATH"

# Reload your shell profile
source ~/.zshrc  # or source ~/.bash_profile

2. Clone the Repository

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

3. Install Dependencies

# Install Ruby gems
bundle install

4. Build the Site

# Build the static site to verify configuration
bundle exec jekyll build

5. Start Development Server

# Start Jekyll development server
bundle exec jekyll serve --host 0.0.0.0 --port 4000

# Alternative port if 4000 is in use
bundle exec jekyll serve --port 4001

6. View the Site

Open your browser and navigate to:

• http://localhost:4000
• Or http://localhost:4001 if using alternative port

Optional: GitHub Stars Automation Setup

To use the automated GitHub stars collection:

1. Install GitHub CLI

# Install via Homebrew
brew install gh

2. Authenticate with GitHub

gh auth login

Follow the prompts to authenticate with your GitHub account.

3. Test the Automation

# Run daily stars script manually
./scripts/daily-stars.sh

Verify Installation

After setup, you should see:

• The homepage loading at localhost:4000
• Blog posts accessible via the “Blog” link
• GitHub stars page showing repository collections
• No errors in the terminal output

Common Issues

Jekyll Not Found

# Add Ruby gems to PATH
export PATH="/opt/homebrew/opt/ruby/bin:/opt/homebrew/lib/ruby/gems/3.4.0/bin:$PATH"

Bundle Install Fails

# Install to local vendor directory
bundle install --path vendor/bundle

Port Already in Use

# Use alternative port
bundle exec jekyll serve --port 4001

Site Not Updating

• Clear browser cache
• Stop and restart the Jekyll server
• Check terminal for error messages

Next Steps

Once your development environment is running:

1. Review the Architecture Overview to understand the site structure
2. Read the Content Management guide to learn about creating posts
3. Check the Style Guide for writing guidelines
4. Explore the GitHub Stars Automation for repository tracking

Development Workflow

1. Make changes to files (posts, layouts, styles)
2. Jekyll automatically rebuilds the site
3. Refresh your browser to see changes
4. Commit changes when ready
5. Push to GitHub for automatic deployment

Need Help? Check the other documentation files or refer to the Jekyll documentation.