thoughtbot Guides - Deploy & Usage Guide

A comprehensive guide for deploying and using the thoughtbot programming style guides, whether you're reading them locally, contributing back, or hosting your own version.

Prerequisites

• Git (2.0+)
• Ruby (3.0+ recommended) - required only if running local Jekyll preview
• Bundler (gem install bundler) - for dependency management
• GitHub Account - required for contributing or deploying to GitHub Pages

Installation

Clone the repository to your local machine:

git clone https://github.com/thoughtbot/guides.git
cd guides

If you plan to preview the site locally (optional), install dependencies:

bundle install

Configuration

For Local Development

Create a _config.yml file in the root directory if you want to customize the Jekyll build:

title: thoughtbot Guides
description: Guides for programming in style
baseurl: "" # change if hosting in a subdirectory
url: "https://yourusername.github.io"

For Contributing

Configure your Git user (if not already set):

git config user.name "Your Name"
git config user.email "your.email@example.com"

No API keys or environment variables are required for basic usage.

Build & Run

Option 1: Direct File Access (Reading Only)

Since this is a static documentation repository, you can simply open the Markdown files directly:

# Open a specific guide
open ruby/sample_1.rb        # macOS
xdg-open ruby/sample_1.rb    # Linux

Or browse the guides in your preferred text editor/IDE.

Option 2: Local Jekyll Server (Full Site Preview)

If you want to preview how the guides render as a website (requires Ruby/Bundler):

# Start the Jekyll development server
bundle exec jekyll serve

# Access at http://localhost:4000

The site will auto-regenerate when you save changes to any Markdown files.

Option 3: Using as Reference in Your Projects

Copy specific guide files into your project:

# Example: Copy Ruby style guide to your project
cp guides/ruby/sample_1.rb my-project/docs/styleguide.rb

Deployment

GitHub Pages (Recommended)

This repository is designed to work with GitHub Pages:

1. Fork the repository on GitHub
2. Go to Settings > Pages in your fork
3. Select source: Deploy from a branch
4. Choose branch: main (or master) and folder: / (root)
5. Your guides will be available at https://yourusername.github.io/guides/

Alternative: Netlify/Vercel

For custom domains or additional features:

Netlify:

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod --dir=.

Vercel:

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

Organization Internal Usage

To deploy as internal documentation:

1. Clone to your organization's GitHub/GitLab
2. Enable Pages in repository settings
3. Add your organization-specific guides to the appropriate directories (/ruby/, /rails/, etc.)
4. Update README.md links to reflect your internal structure

Troubleshooting

Jekyll Build Failures

Issue: bundle exec jekyll serve fails with dependency errors

# Solution: Update gems
bundle update

# If specific gem issues:
bundle install --redownload

Ruby Version Mismatches

Issue: Bundler complains about Ruby version

# Check your Ruby version
ruby -v

# Use rbenv or rvm to install correct version
rbenv install 3.1.0
rbenv local 3.1.0
bundle install

Git Contribution Issues

Issue: Permission denied when pushing changes

# Ensure you're pushing to your fork, not the original repo
git remote -v
git remote set-url origin https://github.com/YOUR_USERNAME/guides.git

Markdown Rendering Issues

Issue: Links like /ruby/ don't work locally

• These paths are designed for GitHub Pages web serving
• For local browsing, navigate to ruby/README.md directly
• Or use bundle exec jekyll serve to resolve paths correctly

File Path Errors

Issue: Sample files not found when referenced in guides

• Ensure you maintain the directory structure: /ruby/, /rails/, /javascript-typescript/, etc.
• The repository relies on relative paths matching the GitHub repository structure

Note: This is a documentation repository containing style guidelines and best practices. No runtime server or database is required for usage—simply read the guides and apply them to your projects.