Indigo, a cool blue theme for Open edX

Indigo is an elegant, customizable theme for Open edX.

You can view the theme in action at https://sandbox.openedx.edly.io.

Installation

Indigo was specially developed to be used with Tutor (at least v14.0.0). If you have not installed Open edX with Tutor, then installation instructions will vary.

Install and enable Indigo plugin:

tutor plugins install indigo
tutor plugins enable indigo
tutor local launch

The Indigo theme will be automatically enabled if you have not previously defined a theme. To override an existing theme, use the settheme command:

tutor local do settheme indigo

Configuration

• INDIGO_WELCOME_MESSAGE (default: "The place for all your online learning")
• INDIGO_PRIMARY_COLOR (default: "#3b85ff")
• INDIGO_FOOTER_NAV_LINKS (default: [{"title": "About", "url": "/about"}, {"title": "Contact", "url": "/contact"}])
• INDIGO_ENABLE_DARK_TOGGLE (default: True)
• INDIGO_BRAND_CSS_BASE_URL (default: "https://cdn.jsdelivr.net/gh/edly-io/brand-openedx@<version>/dist"): base URL of the compiled brand-openedx CSS loaded by the MFEs (see Using your own brand in production)
• INDIGO_BRAND_OPENEDX_PATH (default: ""): path to a local checkout of your brand-openedx repository, used in development mode only (see Developing the brand-openedx theme)
• INDIGO_BRAND_OPENEDX_DEV_PORT (default: 3000)
• INDIGO_BRAND_OPENEDX_DEV_DOCKER_IMAGE (default: "docker.io/node:22")

The INDIGO_* settings listed above may be modified by running tutor config save --set INDIGO_...=.... For instance, to remove all links from the footer, run:

tutor config save --set "INDIGO_FOOTER_NAV_LINKS=[]"

Or, to set the primary color to forest green, run:

# Note: The nested quotes are needed in order to handle the hash (#) correctly.
tutor config save --set 'INDIGO_PRIMARY_COLOR="#225522"'

Theme Toggle Button

The theme toggle button is enabled by default when Tutor Indigo is installed. The theme can be switched from light to dark and vice versa. To disable it, run:

tutor config save --set INDIGO_ENABLE_DARK_TOGGLE=false
tutor images build openedx
tutor local start -d

Developing the brand-openedx theme

The MFE styles (Paragon design tokens and SCSS overrides) live in a brand-openedx repository. By default, Indigo uses a tagged version of edly-io/brand-openedx and the MFEs load its compiled CSS from jsDelivr. To customize the styles, fork that repository (or use your own brand package with the same structure).

To work on a local checkout, point Indigo to it and launch the development environment:

git clone <brand-openedx-repository-url> /path/to/brand-openedx
tutor config save --set INDIGO_BRAND_OPENEDX_PATH=/path/to/brand-openedx
tutor dev launch

In development mode, this:

• starts an indigo-brand container that builds the brand-openedx CSS and serves it at http://localhost:3000 (see INDIGO_BRAND_OPENEDX_DEV_PORT);
• rebuilds core.css within a few seconds when you edit the SCSS files in paragon/ or themes/, and rebuilds all the CSS (about 2 minutes) when you edit the design tokens in paragon/tokens/;
• makes all MFEs load the theme CSS from http://localhost:3000 instead of INDIGO_BRAND_CSS_BASE_URL.

Refresh the page in your browser to see your changes. Build logs are available with tutor dev logs -f indigo-brand. Note that the builds update the dist/ and paragon/build/ folders of your checkout.

Note

Before committing your brand-openedx changes, wait for the build to finish so that the dist/ folder reflects your edits: a few seconds after editing SCSS files, and around 2 minutes after editing design tokens. You can follow the build progress with tutor dev logs -f indigo-brand.

Production (tutor local, tutor k8s) is not affected by this setting and always loads the CSS from INDIGO_BRAND_CSS_BASE_URL. To go back to the remote CSS in development, run:

tutor config save --unset INDIGO_BRAND_OPENEDX_PATH
tutor dev launch

If the paragon plugin (tutor-contrib-paragon) is enabled, the local brand-openedx CSS takes precedence over its themes in development mode.

Using your own brand in production

The MFEs load the compiled core.min.css, light.min.css and dark.min.css files from INDIGO_BRAND_CSS_BASE_URL. To use your own brand-openedx fork in production, build it, publish its dist/ folder, and point Indigo to it. For instance, after committing dist/ to your fork and pushing a tag:

tutor config save --set INDIGO_BRAND_CSS_BASE_URL=https://cdn.jsdelivr.net/gh/<your-org>/<your-brand-repo>@<your-tag>/dist
tutor local restart lms

Any server that serves these files with the text/css content type and CORS headers works too, such as your own CDN or object storage. Prefer tags over branch names in jsDelivr URLs: jsDelivr caches branches for up to 12 hours, but tags are served immediately and never change.

Customization

This plugin can serve as a starting point to create your own themes. Just fork this repository and modify the files as you see fit.

You will have to start by installing indigo from source:

git clone https://github.com/overhangio/tutor-indigo.git
pip install -e ./tutor-indigo
tutor plugins enable indigo

Any change you make to the theme can be viewed immediately in development mode (with tutor dev ... commands) after you run:

tutor config save

To deploy your changes to production, you will have to rebuild the "openedx" Docker image and restart your containers:

tutor images build openedx
tutor local start -d

Changing the Styling in Sass files

To customize the theme stylesheets, modify the files in the tutorindigo/templates/indigo/lms/static/sass/ and tutorindigo/templates/indigo/cms/static/sass/ directories. In particular, the _extras.scss files should contain most styling rules.

Changing the default logo and other images

The theme images are stored in tutorindigo/templates/indigo/lms/static/images for the LMS, and in tutorindigo/templates/indigo/cms/static/images for the CMS. To use custom images in your theme, just replace the files stored in these folders with your own.

Overriding the default "about", "contact", etc. static pages

By default, the /about and /contact pages contain a simple line of text: "This page left intentionally blank. Feel free to add your own content". This is of course unusable in production. In the following, we detail how to override just any of the static templates used in Open edX.

The static templates used by Open edX to render those pages are all stored in the edx-platform/lms/templates/static_templates folder. To override those templates, you should add your own in the following folder:

ls tutorindigo/templates/indigo/lms/templates/static_templates"

For instance, edit the "donate.html" file in this directory. We can derive the content of this file from the contents of the donate.html static template in edx-platform:

<%page expression_filter="h"/>
<%! from django.utils.translation import gettext as _ %>
<%inherit file="../main.html" />

<%block name="pagetitle">${_("Donate")}</%block>

<main id="main" aria-label="Content" tabindex="-1">
    <section class="container about">
        <h1>
            <%block name="pageheader">${page_header or _("Donate")}</%block>
        </h1>
        <p>
            <%block name="pagecontent">Add a compelling message here, asking for donations.</%block>
        </p>
    </section>
</main>

This new template will then be used to render the /donate url.

Troubleshooting

Changes to the MFE styles are not applied

Indigo styles the LMS/CMS pages and the MFEs in two different ways:

• The LMS and CMS pages are styled by the Indigo theme itself (see Customization), including INDIGO_PRIMARY_COLOR. Changes to these files require rebuilding the "openedx" image.
• The MFEs are styled by the compiled CSS of a brand-openedx repository, which they load at runtime from INDIGO_BRAND_CSS_BASE_URL. Changes to the Indigo theme files and to INDIGO_PRIMARY_COLOR do not affect the MFEs.

To change the MFE styles, edit your brand-openedx fork and preview your changes with INDIGO_BRAND_OPENEDX_PATH (see Developing the brand-openedx theme). Then publish it and point INDIGO_BRAND_CSS_BASE_URL to it (see Using your own brand in production). There is no need to rebuild the "mfe" image.

Earlier versions of this documentation recommended installing a custom @edx/brand package in the MFE image with the mfe-dockerfile-post-npm-install patch. You should remove this patch: the MFE styles now come from INDIGO_BRAND_CSS_BASE_URL. With the default MFEs, the @edx/brand package installed in the image is only used as a fallback, when the CSS from INDIGO_BRAND_CSS_BASE_URL cannot be loaded. However, if you build MFEs from forks or older versions whose stylesheets still import @edx/brand, that package is compiled into the MFE bundles, and the CSS from INDIGO_BRAND_CSS_BASE_URL only overrides the rules that it also defines: rules from a custom package may then still apply.

If your changes still do not show up, reload the page without the browser cache, and check in the "Network" tab of your browser's developer tools that the core.min.css, light.min.css and dark.min.css files are loaded from the URL that you expect. jsDelivr may serve files from a branch URL from its cache for up to 12 hours, so prefer tags.

This Tutor plugin is maintained by Muhammad Faraz Maqsood and Hammad Yousaf from Edly. Community support is available from the official Open edX forum. Do you need help with this plugin? See the troubleshooting section from the Tutor documentation.

License

This work is licensed under the terms of the GNU Affero General Public License (AGPL).