Setup Guide

This guide walks you through deploying the Open Source Guidelines template to your organization's GitHub Pages in under 15 minutes.

Prerequisites

Before you begin, ensure you have:

GitHub Account with permissions to create repositories in your organization
Git installed locally (for local testing)
Ruby 2.7+ and Bundler (only needed for local testing)
Text Editor for editing YAML configuration files

Quick Deployment (15 minutes)

Step 1: Create Your Repository (2 minutes)

Click the "Use this template" button at the top of this repository
Choose your organization as the owner
Name your repository (e.g., os-guidelines, open-source-docs)
Set visibility to Public (required for GitHub Pages on free plans)
Click "Create repository from template"

Step 2: Configure Your Organization (5 minutes)

Navigate to docs/_config.yml in your new repository
Click the pencil icon to edit the file
First, configure the site URL settings (see URL Configuration below for details):

# For GitHub Pages project site (username.github.io/repo-name/)
baseurl: "/your-repo-name"              # Replace with YOUR repository name
url: "https://username.github.io"       # Replace with YOUR GitHub username/org

# For custom domain at root, use:
# baseurl: ""
# url: "https://yourdomain.com"

Update the organization block with your details:

organization:
  name: "Acme Corporation"                    # Your full organization name
  shortname: "acme"                           # Used in package names (lowercase, no spaces)
  email: "opensource@acme.com"                # Your OSS program contact email
  github_org: "acme-corp"                     # Your GitHub organization slug
  website: "https://acme.com"                 # Your main company website
  docs_url: "https://docs.acme.com"           # (Optional) Product documentation URL

Update the branding block:

branding:
  logo_path: "assets/logo.svg"                # Path to your logo (see Step 3)
  favicon_path: "assets/favicon.svg"          # Path to your favicon (see Step 3)
  color_scheme: "custom_dark"                 # Options: custom_dark, custom_light
  primary_color: "#FF6B35"                    # Your main brand color (hex)
  secondary_color: "#004E89"                  # Your accent color (hex)
  accent_color: "#1A1A1D"                     # Dark backgrounds/borders (hex)

(Optional) Update the social block:

social:
  twitter: "acmecorp"                         # Twitter/X handle (without @)
  discord_url: "https://discord.gg/abc123"    # Discord server invite URL
  stackoverflow_tag: "acme"                   # Stack Overflow tag

Commit changes directly to the main branch

Step 3: Replace Placeholder Assets (5 minutes)

The template includes placeholder logo and favicon files. Replace them with your organization's branding:

Option A: Upload via GitHub Web Interface

Navigate to docs/assets/ in your repository
Click "Add file" > "Upload files"
Upload your logo file (recommended: SVG format, 200x48px)
Name it logo.svg (or update branding.logo_path in _config.yml)
Upload your favicon file (recommended: SVG format, 48x48px)
Name it favicon.svg (or update branding.favicon_path in _config.yml)
Commit changes

Option B: Using Git Locally

# Clone your repository
git clone https://github.com/your-org/your-repo.git
cd your-repo

# Replace placeholder assets
cp /path/to/your-logo.svg docs/assets/logo.svg
cp /path/to/your-favicon.svg docs/assets/favicon.svg

# Commit and push
git add docs/assets/
git commit -m "Add organization branding assets"
git push origin main

Asset Specifications

Logo: Recommended 200x48px (or 4:1 aspect ratio), SVG or PNG
Favicon: Recommended 48x48px (square), SVG or PNG
See docs/assets/README.md for detailed specifications

Step 4: Enable GitHub Pages (2 minutes)

Go to your repository's Settings tab
Scroll to "Pages" in the left sidebar
Under "Build and deployment":
- Source: Deploy from a branch
- Branch: main
- Folder: /docs
Click "Save"
Wait 1-2 minutes for the initial build

Step 5: Verify Deployment (1 minute)

Refresh the Settings > Pages page
You'll see: "Your site is live at https://[your-org].github.io/[repo-name]"
Click the URL to visit your documentation site
Verify:
- Your organization name appears in the header
- Your logo displays correctly
- Navigation works
- Search functionality works

Congratulations! Your open source guidelines are now live.

URL Configuration

Understanding baseurl

The baseurl setting is critical for GitHub Pages to load assets (CSS, JavaScript, images) correctly. Different deployment scenarios require different configurations:

Scenario 1: GitHub Pages Project Site (Most Common)

Your site URL: https://username.github.io/repo-name/

Configuration:

baseurl: "/repo-name"                    # Your repository name with leading slash
url: "https://username.github.io"        # Your GitHub Pages domain

Example:

Repository: acme-corp/os-guidelines
Site URL: https://acme-corp.github.io/os-guidelines/

Configuration:

baseurl: "/os-guidelines"
url: "https://acme-corp.github.io"

Scenario 2: GitHub Pages User/Organization Site

Your site URL: https://username.github.io/ (repository named username.github.io)

Configuration:

baseurl: ""                              # Empty for root deployment
url: "https://username.github.io"        # Your GitHub Pages domain

Scenario 3: Custom Domain at Root

Your site URL: https://opensource.acme.com/

Configuration:

baseurl: ""                              # Empty for root deployment
url: "https://opensource.acme.com"       # Your custom domain

Scenario 4: Custom Domain with Path

Your site URL: https://acme.com/docs/

Configuration:

baseurl: "/docs"                         # Path with leading slash
url: "https://acme.com"                  # Domain without path

Why baseurl Matters

The Jekyll theme uses /os-guidelines to generate URLs for assets:

CSS files: /os-guidelines/assets/css/...
JavaScript: /os-guidelines/assets/js/...
Images: /os-guidelines/assets/...

Incorrect baseurl causes 404 errors for these assets, breaking styling and functionality.

Verifying Your Configuration

After deploying, check your browser console (F12):

✅ No 404 errors: Configuration is correct
❌ 404 errors for CSS/JS: Check your baseurl setting

Common mistake: Empty baseurl on a project site causes assets to load from wrong location:

Wrong: https://username.github.io/assets/... (404)
Correct: https://username.github.io/repo-name/assets/... (200)

Local Testing (Optional)

Local Development with baseurl

When testing locally, you have two options:

Option A: Override baseurl for Local Testing (Recommended)

cd docs
bundle install

# Override baseurl to empty for local development
bundle exec jekyll serve --baseurl ""

# Site available at: http://localhost:4000/

This works because localhost serves from root, not a subdirectory.

Option B: Test with Production baseurl

cd docs
bundle install

# Use production baseurl (from _config.yml)
bundle exec jekyll serve

# Site available at: http://localhost:4000/your-repo-name/

This simulates production environment and helps catch URL issues before deployment.

Option C: Use Development Config File

Create docs/_config_dev.yml:

# Development overrides
baseurl: ""
url: "http://localhost:4000"

Then serve with both configs:

bundle exec jekyll serve --config _config.yml,_config_dev.yml

# Site available at: http://localhost:4000/

The second config file overrides settings from the first.

Local Testing (Detailed)

To preview changes locally before pushing to GitHub:

Install Dependencies

# Navigate to the docs directory
cd docs

# Install Ruby dependencies
bundle install

Run Jekyll Locally

# Start the Jekyll development server
bundle exec jekyll serve

# Site will be available at http://localhost:4000

Jekyll will watch for file changes and automatically rebuild. Press Ctrl+C to stop the server.

Common Local Testing Issues

Issue: bundle: command not found Solution: Install Bundler: gem install bundler

Issue: Ruby version too old Solution: Install Ruby 2.7+ using rbenv or RVM

Issue: Could not find gem 'github-pages' Solution: Run bundle install in the docs/ directory

Configuration Reference

Organization Block

Field	Required	Description	Example
`name`	Yes	Full organization name	`"Acme Corporation"`
`shortname`	Yes	Lowercase identifier for package names	`"acme"`
`email`	Yes	Open source program contact email	`"opensource@acme.com"`
`github_org`	Yes	GitHub organization slug	`"acme-corp"`
`website`	Yes	Main company website	`"https://acme.com"`
`docs_url`	No	Product documentation URL	`"https://docs.acme.com"`

Branding Block

Field	Required	Description	Example
`logo_path`	Yes	Path to logo (relative to `docs/`)	`"assets/logo.svg"`
`favicon_path`	Yes	Path to favicon (relative to `docs/`)	`"assets/favicon.svg"`
`color_scheme`	Yes	Theme to use	`"custom_dark"` or `"custom_light"`
`primary_color`	Yes	Main brand color (hex)	`"#FF6B35"`
`secondary_color`	Yes	Accent color (hex)	`"#004E89"`
`accent_color`	Yes	Dark UI elements (hex)	`"#1A1A1D"`

Field	Required	Description	Example
`twitter`	No	Twitter/X handle (without @)	`"acmecorp"`
`discord_url`	No	Discord server invite URL	`"https://discord.gg/abc123"`
`stackoverflow_tag`	No	Stack Overflow tag	`"acme"`

Custom Domain (Optional)

To use a custom domain (e.g., opensource.acme.com):

Add a CNAME file to docs/ containing your custom domain:
```
opensource.acme.com
```
In your DNS provider, add a CNAME record:
- Name: opensource (or your subdomain)
- Value: [your-org].github.io
- TTL: 3600 (or default)
In GitHub Settings > Pages:
- Enter your custom domain in the "Custom domain" field
- Wait for DNS check to complete
- Enable "Enforce HTTPS" (recommended)

Note: DNS propagation can take 24-48 hours.

Troubleshooting

Site Not Building

Symptom: GitHub Pages shows "Build failed" or site doesn't update

Solutions:

Check the Actions tab for build errors
Verify _config.yml syntax (use a YAML validator)
Ensure /docs folder exists and contains _config.yml
Check that branch is set to main in Settings > Pages

Logo/Favicon Not Displaying

Symptom: Broken image icons or 404 errors

Solutions:

Verify files exist at the paths specified in _config.yml
Check file names match exactly (case-sensitive)
Ensure image files are committed to the repository
Clear browser cache and hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

Colors Not Updating

Symptom: Changes to primary_color don't appear on site

Solutions:

Ensure you're editing docs/_config.yml (not root _config.yml)
Wait 2-3 minutes for GitHub Pages to rebuild
Clear browser cache
Check that color_scheme matches an existing scheme file

Search Not Working

Symptom: Search box doesn't return results

Solutions:

Wait for initial site build to complete (search index generation)
Verify search_enabled: true in _config.yml
Check browser console for JavaScript errors
Try rebuilding site (push a small change to trigger rebuild)

Liquid Syntax Errors

Symptom: {{ site.organization.name }} appears as literal text

Solutions:

Ensure you're using double curly braces: {{ }} (not single { })
Check variable name matches _config.yml exactly
Verify indentation in YAML (spaces, not tabs)

Next Steps

Now that your site is deployed:

Review Content: Read through all pages and remove/customize sections that don't apply to your organization
Add Custom Pages: See CUSTOMIZATION.md for instructions on adding organization-specific guidelines
Customize Styling: Learn how to adjust colors and themes in CUSTOMIZATION.md
Set Up Spellchecking: Configure cSpell.json to include your organization's technical terms
Invite Contributors: Add maintainers to your repository to keep documentation updated

Support

Documentation Issues: Report on GitHub
Feature Requests: GitHub Discussions
Template Questions: See TEMPLATE_GUIDE.md
Jekyll Help: Jekyll Documentation
Just the Docs Theme: Theme Documentation

Setup Guide

Prerequisites

Quick Deployment (15 minutes)

Step 1: Create Your Repository (2 minutes)

Step 2: Configure Your Organization (5 minutes)

Step 3: Replace Placeholder Assets (5 minutes)

Option A: Upload via GitHub Web Interface

Option B: Using Git Locally

Asset Specifications

Step 4: Enable GitHub Pages (2 minutes)

Step 5: Verify Deployment (1 minute)

URL Configuration

Understanding baseurl

Scenario 1: GitHub Pages Project Site (Most Common)

Scenario 2: GitHub Pages User/Organization Site

Scenario 3: Custom Domain at Root

Scenario 4: Custom Domain with Path

Why baseurl Matters

Verifying Your Configuration

Local Testing (Optional)

Local Development with baseurl

Option A: Override baseurl for Local Testing (Recommended)

Option B: Test with Production baseurl

Option C: Use Development Config File

Local Testing (Detailed)

Install Dependencies

Run Jekyll Locally

Common Local Testing Issues

Configuration Reference

Organization Block

Branding Block

Social Block

Custom Domain (Optional)

Troubleshooting

Site Not Building

Logo/Favicon Not Displaying

Colors Not Updating

Search Not Working

Liquid Syntax Errors

Next Steps

Support