How to customize the appearance of an Open edX instance?

Posted on by

Customizing the Appearance of an Open edX Instance

To tailor the look and feel of your Open edX platform, you can modify themes, branding elements, and front-end templates. Below is a step-by-step guide on how to customize your Open edX instance.

1. Enable Theming in Open edX

Before making customizations, ensure that theming is enabled in your Open edX instance.

  1. SSH into your Open edX server.
  2. Open the lms.env.json and cms.env.json configuration files.
  3. Set the following values: "ENABLE_COMPREHENSIVE_THEMING": true,
  4. Restart your Open edX services: sudo /edx/bin/supervisorctl restart all

2. Create a Custom Theme

To apply a custom theme, follow these steps:

Step 1: Set Up the Theme Directory

  1. Navigate to the Open edX themes directory: cd /edx/app/edxapp/themes
  2. Create a new theme folder: mkdir my_custom_theme cd my_custom_theme

Step 2: Add Theme Components

Inside the my_custom_theme directory, create the following folders:

my_custom_theme/
│── lms/
│   ├── static/
│   ├── templates/
│   ├── sass/
│── cms/
│   ├── static/
│   ├── templates/
│   ├── sass/
│── images/
│── fonts/
│── logo.png
│── theme.conf

Step 3: Configure the Theme

Inside my_custom_theme, create a theme.conf file:

[theme]
base = default

Modify it to use your custom styles.

3. Customize Logos and Branding

  1. Replace the Open edX logo:
    • LMS Logo: Place your logo in my_custom_theme/lms/static/images/logo.png
    • CMS Logo: Place your logo in my_custom_theme/cms/static/images/logo.png
  2. Update favicon:
    • Add a new favicon in static/images/favicon.ico
  3. Modify footer and header:
    • Edit the my_custom_theme/lms/templates/footer.html
    • Edit the my_custom_theme/lms/templates/header.html

4. Modify CSS for Custom Styling

  1. Navigate to your theme’s Sass folder: cd my_custom_theme/lms/static/sass
  2. Edit the main.scss file to change colors, fonts, and layout.

Example (to change background color):

body {
    background-color: #f4f4f4;
}
  1. Compile the CSS: paver update_assets lms --settings=production

5. Apply the Theme

  1. Open /edx/app/edxapp/lms.env.json and add: "DEFAULT_SITE_THEME": "my_custom_theme"
  2. Restart Open edX: sudo /edx/bin/supervisorctl restart all

6. Customize the Homepage

  1. Modify the homepage template:
    • LMS: my_custom_theme/lms/templates/index.html
    • CMS: my_custom_theme/cms/templates/index.html
  2. Restart Open edX to apply changes.

7. Advanced Customization (React & JavaScript)

  • Modify JavaScript for interactive elements in static/js
  • Override React components for new UI designs

Conclusion

By using comprehensive theming, CSS/Sass overrides, and custom templates, you can fully personalize Open edX’s appearance. 🚀