Skip to main content
The ESP Website uses a theming system to control the visual appearance and navigation structure of your site. Themes provide pre-designed layouts that you can customize with your own colors, logos, and content.

​
Accessing the Themes App

The themes configuration interface is available at: 
https://[yoursite].learningu.org/themes/
Behind the scenes, the themes app generates template overrides and CSS stylesheets based on your configuration.

​
Three-Step Setup Process

Theming involves three main steps:
1

Select a Theme

Choose from pre-defined layouts at /themes/select/
2

Set Up the Theme

Provide required information at /themes/setup/
3

Customize Appearance

Define colors and styles at /themes/customize/

​
Step 1: Selecting a Theme

Navigate to /themes/select/ to choose from available themes. Each theme offers different navigation structures and visual styles suited to different types of organizations.

​
Available Themes

Best for: Simple sites needing minimal setupThe simplest available theme with no fancy design elements. Requires little configuration and provides a clean, functional interface.Features:
  • Minimal navigation
  • No theme images required
  • Fast to set up
  • Good for new chapters or testing
Best for: Modern, mobile-friendly sitesThe newest theme with the most modern appearance and reactive design.Features:
  • Uses screen width better than bigpicture
  • Mobile-friendly responsive design
  • Requires setup (header image, navigation)
  • Great for new chapters wanting a polished look
Example: Splash at Yale
Best for: Sites wanting visual impactPopular modern theme based on Splash at Berkeley’s design.Features:
  • Large header image
  • Foreground logo overlay
  • Modern aesthetic
  • Requires setup (images, navigation)
  • Still great for new chapters
Example: Splash at BerkeleyAuthor: Sean Zhu
Best for: Small chapters with simple needsHistorically popular for small chapters. Simple navigation with customizable appearance.Features:
  • Logo slot
  • Fairly simple navigation structure
  • Several customization options
  • Good for small to medium sites
Original use: Chicago SplashExample: BC Splash
Best for: Large organizations with multiple programsMost complex navigation options, designed for MIT ESP’s many programs.Navigation levels:
  1. Top tabs (“learn”, “teach”)
  2. Side tabs (programs or pages)
  3. Navbar below page title (within sections)
Features:
  • Logo and optional “bubbles” front page
  • Supports complex site structures
  • Can be overly complicated for simpler sites
Best for: Organizations running several different programs simultaneously
Best for: Sites wanting middle-ground complexityFancier than barebones, more modern than circles, with moderate navigation complexity.Features:
  • Logo slot
  • Moderate navigation structure
  • Somewhat modern design
Note: Least common and least well-maintained theme

​
Switching Themes

Before switching themes:
  1. Save your logo: Download from the filebrowser
  2. Save template overrides: Back up modifications to main.html and index.html
  3. Switching will overwrite these files
If you don’t know what template overrides are, you probably don’t have any modifications to worry about.
After loading a new theme:
Force-refresh the page (Shift + refresh) to retrieve updated stylesheets and see the new design.
If there’s a problem loading a theme, contact web support.

​
Step 2: Theme Setup

Navigate to /themes/setup/ to provide information required by your selected theme.

​
Common Setup Fields

Most themes require:
  • Page title: Your organization name (appears in browser tab and header)
  • Group name: Your chapter or organization name
  • Contact information: Email, phone, address for footer
  • Tagline or description: Brief text about your organization

​
Theme-Specific Requirements

Each theme may request different information:
  • barebones: Minimal (just basic site info)
  • circles/floaty: Logo, basic navigation
  • bigpicture/droplets: Header image, logo, navigation structure
  • fruitsalad: Multi-level navigation configuration
Complete all required fields to ensure your theme displays properly.

​
Step 3: Customize Appearance

Navigate to /themes/customize/ to personalize your theme’s visual appearance without affecting functionality.

​
Color Customization

The customization form has multiple sections:
1

Define Palette

In the “Palette” section, define your base colors:
  • Primary color
  • Secondary color
  • Accent colors
  • Background colors
  • Text colors
2

Apply to Elements

In subsequent sections, assign colors to specific elements:
  • Headers and navigation
  • Buttons and links
  • Backgrounds and borders
  • Hover states
3

Set Shapes

Configure visual properties:
  • Border radius (rounded corners)
  • Spacing
  • Font sizes
  • Shadow effects

​
Saving Customizations

You can save and load collections of customizations:
  • Save your color scheme with a name
  • Load saved schemes later
  • Useful for seasonal changes or different programs
  • Switch between multiple saved styles easily
After saving changes, force-refresh (Shift + refresh) the page to see the updated color scheme.

​
Theme Images

Each theme has standard image slots:
No theme images required.
  • Background picture: Large header image
  • Logo: Foreground overlay on background
  • Logo: Site logo
  • Header image: Top banner
  • Logo: Site branding
  • Logo: Site branding
  • Bubbles (optional): Front page graphic

​
Uploading Theme Images

1

Access Filebrowser

Click “Manage Media Files” in the admin toolbar (left side of screen)
2

Navigate to Theme Folder

  1. Click the “images” folder
  2. Click the “theme” folder
  3. Find the current image (usually logo.png)
3

Note Dimensions

Check the size of the existing image. Your new image should have similar dimensions to avoid layout issues.
4

Delete Old Image

  1. Click “Change” next to the file
  2. Click “Delete” in the bottom left corner
5

Upload New Image

Upload your image to the same folder
6

Rename to Match

  1. Click “Change” next to your uploaded image
  2. Set the “name” field to match the original (e.g., logo.png)
7

Force Refresh

Force-refresh (Shift + refresh) the page to see the new image
Images should not differ dramatically in size or shape from the originals. This can break the theme layout.

​
Manual Theming

You’re not required to use the themes app. You can manually:
  • Edit template overrides directly
  • Upload custom media files
  • Write custom CSS
  • Control appearance however you prefer
Before experimenting with manual theming:Loading a theme through the themes app will delete or overwrite your manual template overrides. Keep backups of any customizations.
The themes app provides a simplified alternative. The goal is for all sites to eventually use it as their designs are added to the repository as themes.

​
Template Overrides

Key templates you might override:
  • main.html: Overall page structure
  • index.html: Homepage layout
  • Theme-specific templates in /templates/themes/[theme_name]/
Template overrides go in your site’s custom templates directory.

​
Custom CSS

Add custom styles by:
  1. Creating a CSS file in /media/styles/
  2. Including it in your template overrides
  3. Or using the themes customization to generate CSS

​
Best Practices

​
For New Chapters

1

Start with droplets or bigpicture

Modern, well-maintained themes that look professional
2

Prepare images in advance

  • Logo: PNG with transparent background
  • Header/background: High resolution, appropriate dimensions
3

Use simple navigation initially

Add complexity as your site grows
4

Save your customization

Create a saved color scheme so you can restore it if needed

​
For Established Sites

If you’re currently using manual template overrides:
  1. Contact web support about creating a theme from your current design
  2. Or transition gradually by backing up current templates first
  3. Consider whether a standard theme might simplify maintenance

​
Seasonal or Event-Based Changes

  1. Create and save multiple color schemes
  2. Keep multiple versions of theme images
  3. Switch between saved configurations easily
  4. Change colors for holidays, special programs, etc.

​
Troubleshooting

Solution: Force-refresh the page (Shift + refresh) to clear cached CSS and images.
Fix:
  • Replace with image of correct dimensions
  • Check original image size before deleting
  • Ensure image file is named correctly
Try:
  • Save customization changes
  • Force-refresh browser
  • Clear browser cache completely
  • Check if manual CSS is overriding theme CSS
Contact: [email protected] with:
  • Which theme you’re trying to load
  • Error message (if any)
  • Your site URL

​
Getting Help

For theme customization assistance, contact:[email protected]Provide:
  • Your site URL
  • Current theme
  • What you’re trying to achieve
  • Screenshots if helpful

​
Next Steps

Creating Programs

Set up programs after configuring your theme

Admin Overview

Learn about managing your programs

Build docs developers (and LLMs) love

Get started for freeTalk to us