Andy Armstrong edited this page Sep 7, 2017 · 13 revisions

Note: edX is adopting Bootstrap 4, and so the edX Pattern Library should be considered deprecated. To find out more, see Bootstrap 4 (Open edX wiki).

Welcome to the edX Pattern Library wiki. We are using this space to communicate working standards, how-tos, and configuration for the static Pattern Library work.


How to Work/Develop on the Pattern Library Package

If you add or edit any patterns in this repo (found in /pattern-library/) or change any package-centric settings (e.g. package.json or bower.json), please do the following:

  1. test that the change you've made will not negatively affect the node package manager (npm) or Bower packages other apps and codebases are relying on
  2. talk to the UX Team about any bumps (based on semantic versioning) in the npm or Bower packages' version number that are needed.

How to Work and Develop on Documentation Site (PLDOC)

To work on the code of the documentation site portion of this repo, you'll need recent versions of the following things installed on your local machine.

Library Version Purpose
Bundler 1.10 Used to install jekyll and its dependencies
Node.js 0.12.x or 4.0.x Third-party dependency package management
GulpJS + other gulp-based packages 3.9.0 Task runner for build process

Step 1: Install Jekyll

The Pattern Library is managed through Jekyll, a static website generator, so you'll need to install that.

Mac Users

We use a Ruby gem called Bundler to install Jekyll, as that allows us to track the version of Jekyll running on github pages easily.

We assume you have ruby 2.0.0 or later installed. If you don't, an easy way to do that is to use RVM.

With that out of the way, next step is to install bundler, and then to use that to install Jekyll:

$ gem install bundler
$ bundle install

Windows users

Windows users have a bit more work to do, but luckily @juthilo has provided some instructions with his Run Jekyll on Windows guide.

You may also need to install Pygments, the Python syntax highlighter for code snippets that plays nicely with Jekyll (which we use to highlight Front End source code). Read more about this in the Jekyll docs.

Step 2: Install Node.js and Node Package Manager (npm)

The npm command-line tool is bundled with Node.js. If you have it installed, then you already have npm too. If not, go download Node.js.

Step 3: Install Project Dependencies & Gulp Task Flow

From the directory you've checked out this repo into locally, run:

npm install

This runs through all dependencies listed in package.json and downloads them to a node_modules folder in your project directory.

NOTE: You may need to run this more than just once (if encountering errors when running the gulp command) as new dependencies may have been added.

To run the version of gulp installed local to the project, in the root of your this project, run:


Step 4: Run Locally (w/ Gulp Workflow)

To view the Pattern Library locally (and to watch for any local changes to content/assets), run the default gulp task with:


This will run the default gulp task defined in gulpfile.js, which includes the general local development set-up task (build-development) and file/asset watching (watch).

After running the default task, your local instance of the Pattern Library can be viewable at http://localhost:3000. There are additional views:

  • http://localhost:3000/examples/**/* - where full page examples and demos are kept
  • http://localhost:3000/patterns/**/* - permalinks for individually documented pattern library patterns

Committing Code to PLDOC

When developing changes or new work within the PLDOC, please make sure to:

  1. leave the Pattern Library Source Code (contained in pattern-library) unedited (or edit in a separate branch/commit)
  2. run the production preparation-focused gulp task gulp build-production, which will optimize any checked in production assets (styles, images, and scripts), if you've added or heavily edited new PLDOC assets.

How to Use and Deploy the UXPL in your Project

The Pattern Library is meant to be a starting UI Framework to support edX and Open edX applications and sites. To start using the Pattern Library in an edX/Open edX app, please read this guide:

[](How to add the edX Pattern Library to a front end project)

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.