Code Guide Deployment & Usage Guide

Standards for developing consistent, flexible, and sustainable HTML and CSS.

Prerequisites

• Ruby 2.5.0 or higher (required for Jekyll 4.x)
• RubyGems (included with Ruby)
• Bundler gem (gem install bundler)
• Git
• GCC and Make (for compiling native extensions on macOS/Linux)

Installation

1. Clone the repository:

   git clone https://github.com/mdo/code-guide.git
   cd code-guide
   

2. Install Jekyll and dependencies:

   gem install jekyll
   bundle install
   

Configuration

Configuration is managed in _config.yml:

# Site settings
title: "Code Guide"
description: "Standards for developing consistent, flexible, and sustainable HTML and CSS."
url: "https://codeguide.co"

# Build settings
markdown: kramdown
highlighter: rouge
sass:
  style: compressed

Optional environment variables:

• JEKYLL_ENV=production — Enables production optimizations (asset compression, analytics)

Build & Run

Development Server

Start the local development server:

jekyll serve

Or using Bundler (recommended):

bundle exec jekyll serve

Access the site at: http://localhost:4000

Production Build

Generate the static site for deployment:

JEKYLL_ENV=production bundle exec jekyll build

Output is generated in the _site/ directory.

SCSS Compilation

The project uses SCSS (Sass) for styling. Jekyll automatically compiles files in _sass/ and css/ during the build process. For manual compilation:

sass --watch _sass:css --style compressed

Deployment

GitHub Pages (Recommended)

This project is optimized for GitHub Pages hosting:

1. Push code to a GitHub repository
2. Enable GitHub Pages in repository settings
3. Select source branch (usually main or master)
4. Site deploys automatically to https://username.github.io/code-guide

Custom domain: Add a CNAME file to the repository root with your domain name.

Netlify

1. Connect your GitHub repository to Netlify
2. Build command: jekyll build
3. Publish directory: _site/
4. Deploy environment: Set JEKYLL_ENV=production

Vercel

Use the Jekyll preset or manual configuration:

• Framework Preset: Jekyll
• Build Command: jekyll build
• Output Directory: _site

Manual Deployment (Any Static Host)

# Build the site
JEKYLL_ENV=production bundle exec jekyll build

# Deploy _site/ contents to your web server
rsync -avz _site/ user@server:/var/www/html/

Troubleshooting

Jekyll Installation Fails

Issue: Native extension build errors
Solution: Install Ruby development headers

• macOS: xcode-select --install
• Ubuntu/Debian: sudo apt-get install ruby-dev build-essential
• Fedora: sudo dnf install ruby-devel gcc make

Bundle Install Permission Errors

Issue: Gem::FilePermissionError
Solution: Use user-level gem installation

bundle config set --local path 'vendor/bundle'
bundle install

Port 4000 Already in Use

Issue: Address already in use - bind(2) for 127.0.0.1:4000
Solution: Use alternative port

jekyll serve --port 4001

SCSS Compilation Errors

Issue: Sass syntax errors or missing partials
Solution:

• Check file naming: Partials must start with underscore (e.g., _base.scss)
• Verify import paths in css/main.scss
• Check for missing semicolons or braces

Changes Not Reflecting

Issue: Browser shows cached version
Solution:

• Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
• Disable caching in DevTools Network tab
• Check _config.yml for future: true if posts aren't showing

GitHub Pages Build Failures

Issue: Site builds locally but fails on GitHub Pages
Solution:

• Check GitHub email for build error messages
• Ensure all plugins are in GitHub Pages whitelist
• Verify no hardcoded localhost:4000 URLs in templates
• Check case sensitivity in file names (Linux vs macOS)