Pedagogical Pattern

Morea implements a simple pedagogical pattern along with a combination of technologies (git, GitHub, Jekyll) that facilitiate development, maintenance, and collaboration. Here are some of the key features of the pattern.

Morea defines five "entity types": module, outcome, reading, experience, and assessment.

A module is a container that holds a set of outcomes, readings, experiences, and assessments related to course content. Modules have a sort order, which allows you to organize modules into a sequence. Most courses consist of 6 to 30+ modules. A module can contain zero to many instances of outcomes, readings, experiences, and assessments. It is possible to define a module without zero outcomes, zero readings, zero experiences, and zero assessments, though we're not sure of the utility of such a module.

An outcome represents some kind of knowledge or capability that the student should acquire as a result of the readings and experiences in the associated module. A module can have multiple outcomes. Conversely, the same outcome can be associated with multiple modules. We find that a useful way to organize and express learning outcomes is through Bloom's revised taxonomy, which classifies outcomes into six categories: remembering, understanding, applying, analyzing, evaluating, and creating. The latter outcomes (analyzing, evaluating, and creating) are supposed to represent "high-order" cognitive skills.

A reading is an artifact that the student studies: it represents "passive" learning. Readings are typically chapters in a book, online web pages, and so forth.

In contrast to a reading, an experience represents a more "active" form of learning in which the student solves problems or performs other activities in order to acquire understanding and capability. Morea distinguishes between readings and experiences because modules that contain only readings without experiences will tend to have outcomes associated with lower levels of Bloom's taxonomy, while modules containing a mixture of readings and experiences are more likely to support outcomes at higher levels of Bloom's taxonomy.

An assessment is an activity that evaluates the success of the student in achieving the educational goals of the module. In the best case, the educational goals of the module are adequately expressed by learning outcomes, in which case each assessment should relate to one or more outcomes. The graphic Applying Bloom's Taxonomy in your Classroom provides various examples of how outcomes and assessments can be linked together. While Morea can help make linkages between outcomes and assessments clear, it is common to assess skills not encapsulated by outcomes, or desire outcomes that are not assessed.

Morea generates five "views" of the content, each organized according to an entity.

Morea sites contain a navigation bar at the top of the page with links to pages that organize the content according to each of the five entities: modules, outcomes, readings, experiences, and assessments. For example, here is an example of the Readings page:

And here is an example of the Outcomes page:

You can see that the two pages highlight a single entity type but provide links to other entities for context.

We believe that presenting the content organized according to different entity types makes it easier for students and educators to understand the conceptual structure of the course. For educators, it also provides a useful way to see if the course is structurally coherent. For example, when the learning objectives are examined together, do they create a coherent set? For another example, are there assessments for each module, and if not, is that appropriate?

Every Morea entity has its own markdown file.

Every instance of a Morea entity (module, outcome, reading, experience, assessment) is represented by a single markdown file. There can also be other markdown files and other non-markdown files (such as the logo image file associated with each module).

All of your course content is located in the src/morea/ directory.

When you first clone a Morea site, you will find a potentially bewildering number of files and directories. For example:

This organization exists because the Morea framework is basically just a Jekyll site with a custom plugin to process the Morea markdown files.

Fortunately, the only files you will typically need to manage are all located in the src/morea directory. Here is an example of the src/morea directory from the basic-template system:

This folder contains all of the files you will want to manage as part of your course content.

You can organize the src/morea/ directory any way you like.

The Morea framework does not care how you organize the files within the src/morea directory. For example, you can place all of your files at the top level of this directory. Alternatively, and more typically, you can create subdirectories within the src/morea directory, one per module, as shown in the previous screenshot.

Morea makes a "mirror image" of the src/morea directory in the published HTML site.

Because we want you to provide course content in the src/morea directory, and because course content can include (for example) image files, Morea creates a kind of "mirror image" of the src/morea directory in the published site so that your content can include links within itself as well as to external sites.

The basic rule is that markdown files are converted to HTML in the published site, and all other files get copied over without change. So, for example, here is the src/morea directory (on the left) and the site's published morea directory (on the right):

As you can see, the markdown files have become HTML, and the sole non-markdown file (logo.png) has been copied over unchanged. The directory structure below the morea/ directory is unchanged.

Related systems

Another way to understand Morea is by contrasting it with other tools used by educators to create course content.

GitBook, like Morea, creates educational websites using Markdown and Git. If you want to write a textbook, GitBook is a better choice. Morea is preferred when you want to create a course curriculum from a variety of sources including your own and/or other sources, and when you want to make learning objectives and assessments explicit.

Blackboard is one instance of an "enterprise learning management system (LMS)" that provides comprehensive support for all aspects of course management: content management, testing, grading, etc. (Others include eFront, Moodle, Ilias, Dokeos, Sakai, Claroline, Atutor, and Olat).
Morea provides a small subset of the capabilities of these systems, but is oriented toward the needs of institutions rather than individual teachers.

Metacademy is a site for community curated educational content. Unlike Morea, Metacademy supports a single version of curriculum material for any given topic. In contrast, Morea tries to make it as easy as possible for each educator to have their own, slightly (or radically) different version of curriculum material for any given topic. It's much like the difference between centralized version control (i.e. SVN) where there is always a single "golden" version of a system, and distributed version control (i.e. git) where there can be many "different but equal" versions of a system.

If you know of a related system, please let us know and we'll include it here.

Anatomy of a Module

This section overviews the structure of the module Foo in the basic-template system. Here is a graphic to help illustrate the various components:

The top row illustrates various "source" files, and the bottom row illustrates various "output" HTML pages produced from these files.

The top right window shows the contents of the src/morea/foo directory. This directory defines the content associated with the Foo module. Note that the directory contains two files that are not associated with the Foo module. This is unusual but permissible in Morea.

The second window on the top row shows the content of module.md. The content of this file is mostly Front Matter, and provides the definition of the Foo module. The outcomes, readings, experiences, and assessments associated with the Foo module are all referenced by unique IDs.

The third and fourth windows on the top row show the content of two files that define a reading and an experience entity.These entities have unique IDs that are referenced in the definition of the Foo module, and that is the way that Morea connects them together.

The bottom row shows a variety of pages produced by Morea. Because a module was defined in the module.md file, it will show up in the modules/ page. Clicking on the link in the modules page takes you to a page which details the contents of that module. As you can see, the content associated with each of the unique IDs referenced in the module.md file shows up in this page. The other pages illustrate the content (such as a Reading) will not only appear in the module (or modules) with which it is associated, but also in the Readings page.

In summary, Morea markdown files create a set of entities, each of which are identified by a unique ID. The contents of a module (outcomes, readings, experiences, and assessments) are specified by providing unique IDs. The relationship between modules and its content entities is many-to-many. First, a module can refer to multiple outcomes, readings, experiences, and assessments. Conversely, any given outcome, reading, experiences, and assessment can appear in multiple modules.

Morea entity types

This section documents the structure and behavior of the five Morea entity types.

Module

Modules are represented by a markdown file where the Front Matter defines the structure of the module and the body of the file (typically a sentence or two) summarizes the module contents.

Sample module markdown file contents

---
title: "Learn to Foo"
published: true
morea_id: foo
morea_outcomes:
- outcome1
morea_experiences:
- experience1
morea_assessments:
- assessment1
morea_type: module
morea_icon_url: /morea/foo/logo.png
morea_labels:
- required
- intro
morea_sort_order: 1
morea_start_date: "2015-06-15"
morea_end_date: "2015-06-22"
---

Provides everything you need to know to learn to Foo.


Module Front Matter keywords and values

KeywordRequired?Value
morea_type required module
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title required A string indicating the title of the module. The module title appears in all of the top-level pages whereever the module is referenced.
published optional If true, the module will appear in the output. If false, the module will not appear. Default: true
morea_coming_soon optional If true, the module name will appear in the Modules page with a "Coming soon" button that does not link anywhere. Any outcomes, readings, experiences, and assessments defined for the module will not appear in the associated top-level pages. However, the module page can still be retrieved by entering its URL manually. This parameter is useful during early course deployment where you want to indicate to students the set of topics in the course and their sequence but have not yet finished the internal structure of certain modules. Default: false
morea_prerequisites optional If present, a list of Morea IDs indicating the Prerequisites associated with this module.
morea_outcomes optional If present, a list of Morea IDs indicating the Outcomes associated with this module.
morea_readings optional If present, a list of Morea IDs indicating the Readings associated with this module.
morea_experiences optional If present, a list of Morea IDs indicating the Experiences associated with this module.
morea_assessments optional If present, a list of Morea IDs indicating the Assessments associated with this module.
morea_icon_url optional If present, the URL of the icon appearing with this module in the modules/ page. For best effect, the icon image should be square. Defaults to modules/default-icon.png.
morea_summary optional If present, a short string that will appear in the tile representing the module in the Modules page. If absent, then the module body text (see below) will be used in the tile.
morea_labels optional If present, a list of strings that appear as badges in the module's thumbnail on the modules/ page.
morea_sort_order optional If present, an integer used to sort the set of published modules for presentation from low to high. Defaults to zero.
morea_start_date optional If present, a string that indicates the date (and potentially the time) where this module should be placed on the calendar on the Schedule page. Example: "2015-06-25" indicates June 25, 2015, and "2015-06-15T18:30" indicates 6:30pm on June 15, 2015. You can specify a start date without an end date.
morea_end_date optional If present, a string that indicates (along with the start date) the duration associated with this module on the calendar on the Schedule page. Example: "2015-06-25" indicates June 25, 2015, and "2015-06-15T18:30" indicates 6:30pm on June 15, 2015. If you specify an end date, you should specify the start date as well.

Module body text

If morea_summary does not appear in the module's Front Matter, then the module body text will appear both in the tile and at the top of the page describing the module in full.

Alternatively, you can provide a short string as the morea_summary, and significantly more text as the module body text. In this case, the summary string will appear in the tile and the module body text will appear at the top of the page describing the module.

Outcome

Each outcome represents knowledge or capability that the educator hopes the students will acquire as a result of the module or modules in which this outcome appears.

Sample outcome markdown file contents

---
title: "Remember concepts of asymptotic growth."
published: true
morea_id: outcome-growth
morea_type: outcome
morea_sort_order: 30
morea_labels:
- "Bloom: Remember"
---

Learn the concepts of asymptotic growth and recognize them in context.


Outcome Front Matter keywords and values

KeywordRequired?Value
morea_type required outcome
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title required A string indicating the title of this outcome. The outcome title appears in all of the top-level pages whereever the outcome is referenced.
published optional If true, the outcome will appear in the output. If false, the outcome will not appear. Default: true. Note: if an outcome is not referenced by at least one module, it will not appear in the output even if published is true.
morea_labels optional If present, a list of strings that appear as badges in this outcome's description.
morea_sort_order optional If present, an integer used to sort the set of published outcomes for presentation from low to high in the outcomes/ page. Defaults to zero.

Outcome body text

In an outcome definition, the text following the Front Matter describes the outcome. This text appears both in all of the Module pages referring to this outcome, as well as on the Outcomes page.

Each reading represents a "passive" learning opportunity associated with the module. There are two types of readings:

1. Readings in which the material is "inline", as the body text associated with the file.
2. Readings in which the material is "online", and the Front Matter provides a link to that material.

Whether or not the reading is "inline" or "online" depends upon whether the keyword morea_url appears in the Front Matter. Here are examples of each:

Sample "inline" reading markdown file contents

---
title: "Chapter 3 Notes"
published: true
morea_summary: "Introduction to asymptotic analysis"
morea_start_date: "2015-06-15T18:30"
morea_sort_order: 9
morea_labels:
- Notes
---

## Outline

1. Intro to Asymptotic Analysis
2. Big-O
3. Omega
4. Theta



Sample "online" reading markdown file contents

---
title: "CLRS 3 - Growth of functions"
published: true
morea_summary: "Asymptotic notation, standard notation, and common functions."
morea_sort_order: 8
morea_url: http://mitpress.mit.edu/books/introduction-algorithms
morea_start_date: "2015-06-15T18:30"
morea_labels:
- Textbook
- 22 pages
----


Reading Front Matter keywords and values

KeywordRequired?Value
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title required A string indicating the title of this reading. The title appears in all of the top-level pages where ever this entity is referenced.
published optional If true, this reading will appear in the output. If false, the reading will not appear. Default: true. Note: if a reading is not referenced by at least one module, it will not appear in the output even if published is true.
morea_url optional If present, specifies the URL of a reading. To refer to internal pages, the string must start with '/morea/' and continue with the path to the page. To refer to external pages, the string should start with 'http'. If this parameter is absent, then the body text of this file is the reading.
morea_labels optional If present, a list of strings that appear as badges in this reading's description.
morea_sort_order optional If present, an integer used to sort the set of published readings for presentation from low to high when listed as part of the module. Defaults to zero.
morea_start_date optional If present, a string that indicates the date (and potentially the time) where this reading should be placed on the calendar on the Schedule page. Example: "2015-06-25" indicates June 25, 2015, and "2015-06-15T18:30" indicates 6:30pm on June 15, 2015. You can specify a start date without an end date, and this typically indicates the "Due date" for this reading.
morea_end_date optional If present, a string that indicates (along with the start date) the duration associated with this reading on the calendar on the Schedule page. Example: "2015-06-25" indicates June 25, 2015, and "2015-06-15T18:30" indicates 6:30pm on June 15, 2015. If you specify an end date, you should specify the start date as well.

When the morea_url keyword is provided to specify the URL, then no body text need appear. When the morea_url keyword is absent, then the body text should be the intended reading.

Experience

Each experience represents an active learning opportunity associated with the module. Experiences appear as the body text of the file.

Sample experience markdown file contents

---
title: "Asymptotic concepts"
published: true
morea_id: experience-asymptotic-concepts
morea_type: experience
morea_summary: "Practice analysis of functions"
morea_start_date: "2015-06-15T18:30"
morea_sort_order: 1
morea_labels:
- In class
---

## Asymptotic Concepts

#### 5 points

**1\. (1 pt)** We can extend asymptotic notation to the case of two parameters n and m that can go to infinity independently at different rates. For example, we denote by O(g(n,m)) the set of functions:

> O(_g_(_n_,_m_)) = {_f_(_n_,_m_) : there exists positive constants _c_, _n_0
and _m_0 such that 0 ≤ _f_(_n_,_m_) ≤ _c__g_(_n_,_m_) for all _n_ ≥ _ _n0 or
_m_ ≥ _m_0}

Give a corresponding definition for Θ(_g_(_n_,_m_)).
---

(remaining experience material deleted)


Experience Front Matter keywords and values

KeywordRequired?Value
morea_type required experience
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title required A string indicating the title of this experience. The title appears in all of the top-level pages where ever this entity is referenced.
published optional If true, this experience will appear in the output. If false, the experience will not appear. Default: true. Note: if an experience is not referenced by at least one module, it will not appear in the output even if published is true.
morea_labels optional If present, a list of strings that appear as badges in this experience's description.
morea_sort_order optional If present, an integer used to sort the set of published experiences for presentation from low to high when listed as part of the module. Defaults to zero.
morea_start_date optional If present, a string that indicates the date (and potentially the time) where this experience should be placed on the calendar on the Schedule page. Example: "2015-06-25" indicates June 25, 2015, and "2015-06-15T18:30" indicates 6:30pm on June 15, 2015. You can specify a start date without an end date, and this typically indicates the "Due date" for this experience.
morea_end_date optional If present, a string that indicates (along with the start date) the duration associated with this experience on the calendar on the Schedule page. Example: "2015-06-25" indicates June 25, 2015, and "2015-06-15T18:30" indicates 6:30pm on June 15, 2015. If you specify an end date, you should specify the start date as well.

Experience body text

The body text should describe the experience in markdown format.

Assessment

Each assessment represents the results of some activity intended to determine whether or not the students have acquired the knowledge and/or capabilities intended by the module's readings and experiences.

Assessments appear as the body text of the file, typically as charts. We recommend that you publish the assessment results in a manner that preserves student anonymity.

For each assessment, you can provide a list of outcomes that the assessment checked. This list of outcomes will be listed with the assessment, and the assessment will appear with the outcome.

Publishing assessment results has a number of benefits:

• Students get a sense for both how they are performing relative to others during the course.
• Students understand how the educator is attempting to assess the learning associated with the module.
• Assessment results become part of the "public record" associated with the module, facilitating future modification and improvement of the assessment technique.

To present assessment results as charts, you can include Javascript directly in the markdown file, as illustrated in the following example:

Sample assessment markdown file contents

---
title: "Ability to recall asymptotic concepts"
published: true
morea_id: assessment-asymptotic-concepts
morea_type: assessment
morea_sort_order: 1
morea_outcomes_assessed:
- outcome-technical-writing
morea_labels:
- "Bloom: Remember"
---

Assessed ability to remember asymptotic concepts through an in-class multiple choice exam:

<script src="//cdnjs.cloudflare.com/ajax/libs/raphael/2.1.0/raphael-min.js"></script>
<script src="http://cdn.oesmith.co.uk/morris-0.4.3.min.js"></script>

<div class="well">
<div id="assessment" style="height: 250px;"></div>
</div>

<script>
Morris.Bar({
element: 'assessment',
hideHover: false,
data: [
{ y: 'Very satisfactory (%)', num: 15 },
{ y: 'Satisfactory (%)', num: 55 },
{ y: 'Unsatisfactory (%)', num: 25 },
{ y: 'Absent (%)', num: 5 },
],
xkey: 'y',
ykeys: ['num'],
resize: true,
labels: ['Students']
});
</script>


Assessment Front Matter keywords and values

KeywordRequired?Value
morea_type required assessment
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title required A string indicating the title of this assessment. The title appears in all of the top-level pages where ever this entity is referenced.
published optional If true, this assessment will appear in the output. If false, the assessment will not appear. Default: true. Note: if an assessment is not referenced by at least one module, it will not appear in the output even if published is true.
morea_labels optional If present, a list of strings that appear as badges in this assessment's description.
morea_sort_order optional If present, an integer used to sort the set of published assessment for presentation from low to high when listed as part of the module. Defaults to zero.
morea_outcomes_assessed optional If present, a list of outcome morea_ids which are checked by this assessment.

Assessment body text

The body text should describe the assessment in markdown format.

Prerequisite

As of Morea 2.0, it is possible to define Prerequisite modules, or modules from another Morea site whose material should be mastered prior to starting this module.

The following image illustrates the top part of a Module definition page specifying three prerequisite modules from three prior courses:

As with all other "tiles" in Morea sites, these can be clicked to go to the corresponding module from the external site.

There are two steps to using Prerequisite modules. First, you must define them, and second, you must reference them in another module as a Prerequisite.

Sample prerequisite markdown file contents

Prerequisite Front Matter keywords and values

KeywordRequired?Value
morea_type required prerequisite
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title required A string indicating the title of this prerequisite. The title appears whereever this entity is referenced.
morea_url required The URL to the location where this module page can be retrieved.
morea_icon_url required The URL to the location where the icon associated with this module page can be retrieved.
published optional If true, this prequisite will be defined. If false, it will not exist. Default: true.
morea_labels optional If present, a list of strings that appear as badges in this assessment's description.

Prequisite body text

The body text should describe the prerequisite in markdown format. It will appear in the tile, so should be relatively concise.

Content development

The material in this section assumes that you have set up your local environment according to the instructions in the QuickStart page.

Develop by duplicating modules

Development of curriculum content seems to be easiest by organizing module material by directories. Then, to create a new module, just:

1. Duplicate an existing module directory using your operating system commands.
2. Edit the module definition markdown file. Define a new unique ID for that module, and change the references to outcome IDs, reading IDs, experience IDs, and assessment IDs appropriately.
3. Edit the markdown files within the new directory files to define the outcomes, readings, experiences, and assessments associated with the new module.
4. Check to make sure the new module displays correctly in your local browser and that the sort order numbers result in the correct ordering on all pages.

Edit>Compile>Review>Publish

Development of course content with Morea follows this general sequence:

1. Edit: Modify the files in the morea/ directory.
2. Compile: Invoke the "Morea compiler" (i.e. jekyll) using the morea-run-local.sh script
3. Review: Fix any errors that occur, or if no errors occur, then review the results at http://localhost:4000.
4. Publish: When satisfied with your content, publish it using the morea-publish.sh script.

Edit phase

Just edit the files using any programming text editor (vi, emacs, sublime, etc.) Don't use a word processor such as Word.

Compile phase

The morea-run-local script invokes the Jekyll compiler in "watch" mode, which means it will automatically recompile the markdown files whenever it notices that they have been edited. So, for example, this is what happens when morea-run-local is invoked in the basic-template system:

[~/projecthosting/github/morea-framework/basic-template]-> ./morea-run-local.sh
+ jekyll serve --source /Users/johnson/projecthosting/github/morea-framework/basic-template/master/src --destination /Users/johnson/projecthosting/github/morea-framework/basic-template/master/src/_site --baseurl '' --watch
Configuration file: /Users/johnson/projecthosting/github/morea-framework/basic-template/master/src/_config.yml
Source: /Users/johnson/projecthosting/github/morea-framework/basic-template/master/src
Destination: /Users/johnson/projecthosting/github/morea-framework/basic-template/master/src/_site
Generating...
Starting Morea page processing...
Processing file:     assessment.md
Processing file:     experience.md
Processing file:     module.md
Processing file:     outcome.md
Processing file:     assessment.md
Processing file:     experience.md
Processing file:     module.md
Processing file:     assessment.md
Processing file:     experience.md
Processing file:     logo.png
Processing file:     module.md
Processing file:     outcome-1.md
Processing file:     outcome-2.md
Processing file:     footer.md
Processing file:     home.md
Processing file:     module.md
Warning: module.md missing optional front matter: morea_icon_url (set to /modules/default-icon.png)
Warning: module.md missing optional front matter: morea_icon_url (set to /modules/default-icon.png)
Warning: module.md missing optional front matter: morea_outcomes, morea_readings, morea_experiences, morea_assessments, morea_icon_url (set to /modules/default-icon.png)
Summary:
20 total, 19 published, 0 unpublished, 19 markdown, 1 other
4 modules, 3 outcomes, 4 readings, 3 experiences, 3 assessments
0 errors, 7 warnings
done.
Auto-regeneration: enabled
Server running... press ctrl-c to stop.


This normal output shows the markdown files found by Morea, followed by any "warnings" (non-fatal issues) discovered during processing of the markdown, followed by a summary of processing. At the very end, it indicates that the server is running and that you can retrieve the site at http://localhost:4000.

If you edit the content associated with a file and save it out, then the compiler will be automatically invoked and you will see more output appear similar to the above. If you decide to install a browser plugin like LiveReload, then the browser page displaying your output will be refreshed automatically each time you save your source files. This is highly recommended.

Now let's see what happens when we make an error creating our content. For example, let's put a typo into the Foo module definition file so that we reference "outcome12" rather than "outcome1". Here's what results:

Starting Morea page processing...
Processing file:     assessment.md
Processing file:     experience.md
Processing file:     module.md
Processing file:     outcome.md
Processing file:     assessment.md
Processing file:     experience.md
Processing file:     module.md
Processing file:     assessment.md
Processing file:     experience.md
Processing file:     logo.png
Processing file:     module.md
Processing file:     outcome-1.md
Processing file:     outcome-2.md
Processing file:     footer.md
Processing file:     home.md
Processing file:     module.md
Warning: module.md missing optional front matter: morea_icon_url (set to /modules/default-icon.png)
Warning: module.md missing optional front matter: morea_icon_url (set to /modules/default-icon.png)
Warning: module.md missing optional front matter: morea_outcomes, morea_readings, morea_experiences, morea_assessments, morea_icon_url (set to /modules/default-icon.png)
Error: module.md references undefined morea_id: outcome12
Warning: module.md missing optional front matter: morea_outcomes, morea_readings, morea_experiences, morea_assessments, morea_icon_url (set to /modules/default-icon.png)
Summary:
20 total, 19 published, 0 unpublished, 19 markdown, 1 other
4 modules, 3 outcomes, 4 readings, 3 experiences, 3 assessments
1 errors, 7 warnings
Errors found. Exiting.
>


Instead of "0 errors, 7 warnings", the compiler reports "1 errors, 7 warnings" and exits back to the command line. At this point, find the place(s) in the output where the error is reported. In this case, you'll find:

  Error: module.md references undefined morea_id: outcome12


This tells you name of the file with the error and the problem: in this case, a reference to an undefined Morea ID. Fix the problem and reinvoke morea-run-local.sh to see if the error goes away.

Publish phase

When you are ready to publish your content to GitHub so it can be seen publicly, invoke the morea-publish.sh script, providing it with a commit message. For example:

[~/projecthosting/github/morea-framework/morea-github-io]-> ./morea-publish.sh "Latest content updates"
Generating HTML site into master directory
+ jekyll build --source ./src/src --destination ./master
Configuration file: ./src/src/_config.yml
Source: ./src/src
Destination: ./master
Generating... done.
Committing the master branch.
+ cd ./master
+ git commit -a -m 'Latest content updates'
5 files changed, 617 insertions(+), 19 deletions(-)
create mode 100644 images/module-anatomy.jpg
delete mode 100644 images/module-anatomy.png
+ git push origin master
Counting objects: 12, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 248.63 KiB, done.
Total 7 (delta 4), reused 0 (delta 0)
To git@github.com:morea-framework/morea-framework.github.io.git
57a32b3..9d767b6  master -> master
Committing the src branch
+ cd ./src
+ git commit -a -m 'Latest content updates'
7 files changed, 627 insertions(+), 20 deletions(-)
create mode 100644 src/images/module-anatomy.jpg
delete mode 100644 src/images/module-anatomy.png
+ git push origin src
Counting objects: 20, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (11/11), done.
Writing objects: 100% (11/11), 247.83 KiB, done.
Total 11 (delta 8), reused 0 (delta 0)
To git@github.com:morea-framework/morea-framework.github.io.git
0cd10d5..4fabb97  src -> src
[~/projecthosting/github/morea-framework/morea-github-io]->


This should typically run without errors. If there are errors, use manual git commands to resolve them.

Equation support

MathJax is a popular package for rendering LaTeX-style equations in HTML. Morea provides built-in support for MathJax, so that you can write LaTeX equations in your Markdown files and have it render appropriately.

Here is a screen image illustrating this support:

Overview files

Morea allows the instructor to define "overview files" whose content is inserted at the top of the six standard pages (Prerequisites, Modules, Outcomes, Readings, Experiences, Assessments).

Example overview files are available here.

One use case occurs when the instructor wants to provide course-level outcomes in the site. One reasonable place for this information is at the top of the "Outcomes" page, followed by the module-level outcomes. Here is an example:

In other cases, the overview file can simply provide documentation on the contents of the page.

Sample overview markdown file contents

Overview Front Matter keywords and values

KeywordRequired?Value
morea_type required One of: overview_modules, overview_outcomes, overview_readings, overview_experiences, overview_assessments, overview_schedule
morea_id required A symbol (letters, numbers, hyphens, underscores) identifying this Morea entity. Morea IDs must be unique. The Morea compiler will terminate with an error if it encounters two markdown files containing the same Morea ID.
title optional Ignored.
published optional If true, this overview will appear at the top of its associated page.

Overview body text

The body of the overview file will be placed at the beginning of its associated page.

NavBar configuration

The six standard menu items can be enabled or disabled through the top-level _config.yml file. Here is an example:

name: Review ICS 311
baseurl: /ReviewICS311
exclude: [morea]
morea_theme: cerulean
morea_navbar_items:
- Prerequisites
- Modules
- Outcomes
- Experiences
# - Schedule


In this example, the site has enabled five of the standard nav bar items (Prerequisites, Modules, Outcomes, Readings, and Experiences), but has commented out the Schedule nav bar item and thus it will not be displayed.

You may wish to reference one Morea page from another. For example, you might want to link to one Readings page from another Readings page, or to an Experience from an Assessment.

Linking in Morea is complicated by the fact that Modules, Outcomes, Readings, Experiences, and Assessments are implemented in different ways. Modules, Readings, and Experiences are implemented as standalone pages, while Outcomes and Assessments are implemented as page "fragments" that are integrated into other pages.

A second complication is the fact that the URL required to show the page locally is slightly different from the URL required to show the page when published: a parameter called "site.baseurl" is needed to be included in the URL.

A third complication is that some files (readings, experiences) are located within a morea/ subdirectory, while others (modules, outcomes, and assessments) are not.

The following table documents the structure of absolute links to each of the five Morea entity types:

Module {{ site.baseurl }}/modules/<module ID>
Outcome {{ site.baseurl }}/outcomes/#<outcome ID>
Experience {{ site.baseurl }}/morea/<path-to-experience-file>/<experience file name>.html
Assessment {{ site.baseurl }}/assessments/#<assessment ID>

For example, let's say you have created a module with morea_id "foo" in a directory called "01.foo/" that contains files module.md, outcome.md (with morea_id outcome-foo), reading.md, experience.md, and assessment.md (with morea_id assessment-foo). Here is how you would create absolute links to each of these entities:

module.md {{ site.baseurl }}/modules/foo
outcome.md {{ site.baseurl }}/outcomes/#outcome-foo
experience.md {{ site.baseurl }}/morea/01.foo/experience.html
assessment.md {{ site.baseurl}}/assessments/#assessment-foo

You will typically use Markdown syntax, so an actual link might look like

[Readings about Foo]({{ site.baseurl }}/morea/01.foo/reading.html)


There is a shortcut that you can use when linking between reading and experience files that are located in the same directory. In this case, you can use a relative link:

[the readings for this experience](reading.html)


Formatted code options

Jekyll highlight tag

To put code into your pages, one option is to use Jekyll code snippet highlighting.

For example,

{% highlight java %}
public static void main(String args[]) {
System.out.println("Hello world");
}
{% endhighlight %}


produces:

Don't forget to include syntax.css in your page, or else the code won't be shown with colors.

Jekyll gist tag

For larger code samples, you might prefer to use the Jekyll gist tag.

For example,

{% gist philipmjohnson/5288814 %}


produces:

true

Code repo

For documenting executable systems, as opposed to code samples, your best bet is to create a GitHub repo containing the system and provide links to it in your markdown.

Schedule page

The Module, Reading, and Experience entity types support the morea_start_date and morea_end_date parameters in their Front Matter. This information is read when the files are processed, and used to generate a page containing a calendar that displays these dates and durations. For example:

Clicking on one of these events in a live calendar will take you to the corresponding Module, Reading, or Experience definition page.

In order to display a link to this Schedule page in the NavBar, you must edit your _config.yml file and uncomment the Schedule entry in morea_navbar_items:

Note that whenever you modify _config.yml, you must re-run morea_run_local.sh to see the change.

Include files and charts

Jekyll allows you to create small page fragments that you can include in multiple places on your site using the include file syntax. Include files can be passed parameters, which enables a simple kind of macro language that you can use to simplify your Morea content.

The ICS 314 site illustrates the use of include files through its implementation of assessments. To show how, here is part of its assessments page:

The ICS 314 assessments page contains approximately 40 assessments, where each assessment has a chart on the left side and some explanatory text on the right side. The implementation of this capability involves several steps:

First, the ICS 314 master branch contains a copy of ChartJS in a js/ directory. ChartJS is an open source Javascript charting library.

Second, the ICS 314 master branch contains a directory called _includes/ containing the file assessment-chartjs.html. Let's look at this file in more detail:

This include file begins by loading the Chart.js system. Then it uses Twitter Bootstrap classes to create a single row containing two equal width columms. The left side contains a <canvas> element where the chart is displayed, and the right side contains a textual explanation for the chart. The file references several parameters:

• page.morea_id is a parameter containing the id for the canvas element, and passed to ChartJS to identify where to draw the chart;
• page.morea_chartjs_caption is a parameter containing the textual explanation to be displayed beside the chart;
• page.morea_chartjs_labels is a parameter containing an array of strings displayed on the X-axis of the chart;
• page.morea_chartjs_data is a parameter containing an array of integers indicating the bar height.

Let's now look at assessment-environment-configuration.md, one of the 40 assessments that invokes this include file:

Note the following:

• The include file parameters are defined and given values in the YAML front matter section.
• The body of the file contains only the include statement.
• Front matter variables must be prefaced by "page." in the include file (so the front matter morea_id is referenced in the include file as {{ page.morea_id }}.

As this example illustrates, include files can greatly simplify your Morea content. In this case, the include file contains all of the Twitter Bootstrap markup, as well as the ChartJS scripts. The actual assessment file contains only the content specific to that assessment. This separation of concerns makes it possible to change the layout or change the Chart in a single file and have all of the assessments instances updated as a result.

Embedding slides

Rather than include a link to a .ppt or .pdf file, you might find it more user-friendly to embed your slides in a page. The easiest way to do this is by using a cloud-based presentation hosting service, such as SlideShare. In the following example, we will use a similar service, Speaker Deck, which provides a responsive HTML5 embedded player. If you prefer SlideShare, the same general procedure will work.

First, create a Speaker Deck account by going to the Speaker Deck signup page. You can use your GitHub account to simplify signup.

Second, upload your slides. The upload file must be PDF, so you must export your slides in that format. Note the size limit. Once uploaded, you will have a page like the following for your presentation:

Third, add the embed code to your Morea page. To do this, notice the "Embed" button on the right side of the page displayed above. Clicking this button will pop up a dialog box with the HTML <script> element you must place in your Morea page to embed this presentation. For example, here is what a readings page might look like with the <script> code

That's it! Here is what this Readings page looks like:

The embedded image is responsive, so it works nicely on a mobile device. Your students can study on the bus:

If you are interesting in tracking usage of your pages, Morea supports Google Analytics.

To use, first read the Google Analytics Get Started and set up an account and tracking ID.

Then, edit your _config.yml file to provide the tracking ID. For example:

name: Review ICS 241
markdown: kramdown
kramdown:
input: GFM
syntax_highlighter: rouge
mathjax: true
baseurl: /ReviewICS241
exclude: [morea]
morea_theme: cerulean
morea_navbar_items:
- Prerequisites
- Modules
- Outcomes
- Experiences
morea_course: ics241
morea_domain: http://courses.ics.hawaii.edu/


Themes

Because variety is the spice of life, Morea provides a set of pre-built themes that you can use to modify the look (colors and fonts) for your site. These themes are based upon the Bootswatch themes for Bootstrap.

To select a theme for your site, edit the morea_theme parameter in the _config.yml file in the src/ directory of your site:

morea_theme: cerulean


The default value (i.e. the value that comes with the basic-template) is "cerulean". The theme in use appears in the footer area of your site. After changing the value of the theme, you must restart Jekyll (i.e. control-c and re-invoke morea-run-local.sh) to see the change.

It is possible to modify these themes or define new ones of your own. This process will be documented in the developer guide later.

The following sections show a sample page for each of the pre-installed themes in alphabetical order. Click image to see full-size.

Scripts

Because Morea development involves the management of two branches (master, gh-pages) of your repo, we provide a set of Unix/Mac scripts to simplify various development actions. These scripts are maintained in the morea-framework/scripts repository.

All of these scripts run from the top-level directory of your local Morea site (in other words, the directory containing the master/ and gh-pages/ subdirectories).

After downloading the scripts, you must make them executable by running the chmod command. For example:

% chmod 775 morea-publish.sh


Once they are made executable, you can invoke them. For example:

% ./morea-publish.sh "Added module on Java"


Here is an overview of the scripts we currently provide.

morea-vanilla-install

The morea-vanilla-install.sh script implements the recommended approach to setting up a Morea site which does not require forking. To use this script:

• Create a new, empty repo on GitHub using the browser-based mechanisms.
• Create a new, empty local directory in which you will develop your site.
• Download the morea-vanilla-install.sh script and set its permissions using chmod 755 morea-vanilla-install.sh.
• Invoke the morea-vanilla-install.sh script.

This script requires two arguments: your github account and your new repo to initialize. For example:

% ./morea-vanilla-install.sh philipmjohnson ics314f13


The script performs the following actions:

• Creates master/ and gh-pages directories.
• Clones the master branch of your repo into the master/ directory.
• Creates a new, orphan gh-pages branch of your repo and checks out that branch into the gh-pages/ directory.
• Sets 'upstream' to the core repo.
• Merges the upstream branch into your new master branch in the master/ directory.

When completed, your master/ branch should contain a copy of the core repo. If you encounter merge conflicts during the execution of this script, you will need to fix the files in the master/ directory, and recommit them. Some helpful documentation is resolving a merge conflict from the command line.

It is a good idea after running morea-vanilla-install to run morea-run-local.sh to see that the new site can be created successfully, then morea-publish.sh to commit your initialized site to your GitHub repo.

morea-merge-upstream

The Morea Framework is still under active development, and the changes and improvements are generally reflected in updates to the basic-template system.

The morea-merge-upstream.sh script incorporates updates to the core system into your local site. The script defines the core repo as an "upstream" repo, then fetches and merges changes in the master branch of core into your local repo.

This script requires no arguments. For example:

% ./morea-merge-upstream.sh


In some cases merge conflicts can result from this merge. Don't worry, they are generally very easy to resolve. The GitHub documentation on merge conflicts probably provides everything you need to know. If you're still confused, contact the Morea developers for help.

morea-publish

The morea-publish.sh script pushes your local version of your Morea site to GitHub so that it will now be publicly accessable at http://<username>.github.io/<repo>.

It does this by first running Jekyll over your source files, placing the generated HTML into your gh-pages subdirectory, then commiting this branch and the master branch to your GitHub repo.

This script requires a string containing the commit message. For example:

% ./morea-publish.sh "Adding the Intro to CSS module."


morea-pull

The default workflow when working in a team is for each member to commit their changes to the master and gh-pages branches of the GitHub repository as they complete enhancements. Thus, when starting a work session, you will want to first perform a git pull to update your local repository on your laptop to the latest version available on GitHub.

The morea-pull.sh script simply performs a git pull in both the master/ and gh-pages/ subdirectories so that they contain the latest version available from GitHub.

This script requires no arguments. For example:

% ./morea-pull.sh


If merge errors occur, you will need to resolve them. Contact the Morea framework development team if you need assistance with this process.

morea-run-local

When doing development, it is convenient to be able to review your work in a browser without publishing the changes to GitHub.

The morea-run-local.sh script runs the Jekyll compiler and displays the results at http://localhost:4000.

This script requires no arguments. For example:

% ./morea-run-local.sh


We recommend that you install a browser plugin such as LiveReload, which will automatically refresh your browser page when changes are detected to underlying directory files. Using LiveReload in combination with morea-run-local results in your browser instantly reflecting the changes to your source files as soon as you save them. This makes Morea site development significantly more fluid and enjoyable.

Note that when you make changes to your source file, you must stop the morea-run-local.sh script with control-c and restart it in order to see the changes rendered into HTML. (For those familiar with Jekyll: the --watch command will not work in Morea because the directory in which most work is done (/morea), is ignored by the Jekyll run-time for the purposes of auto-recompilation. See the next script, morea-watch, for a workaround.)

morea-watch

One of the downsides of morea-run-local is that when you make changes to your source files, you must manually stop and restart the morea-run-local script.

To address this usability problem, the morea-watch.rb script is a wrapper around morea-run-local which monitors the state of your morea/ directory and when it detects changes, will kill the Jekyll server process and restart it automatically.

To use it, just invoke morea-watch.rb instead of morea-run-local.sh.

Note: morea-watch.rb does not currently work on Windows.

morea-install

The morea-install.sh script downloads a GitHub repository containing a previously initialized Morea site. It assumes that the GitHub repo contains both a master and gh-pages branch.

This script requires two arguments: a github user and the Morea site repo to download. For example:

% ./morea-install.sh philipmjohnson ics314f13


morea-module-status

The morea-module-status.py script provides a way to globally inspect and change the "visibility" of modules. Running the script brings up an ncurses user interface for automagically updating the "published", "morea_coming_soon", and "morea_highlighted" parameters in a module definition file:

The morea-module-status UI is an homage to the days when programmers had the Right Stuff and the focus was on getting the job done with 6K RAM, not on fancy-pants bells and whistles like "reactive" or "responsive" UIs.

Beyond Morea

As the name implies, "Morea" provides you with mechanisms to define modules, outcomes, readings, experiences, and assessments.

However, most course web sites need to also provide other kinds information to students. For example, many instructors want a top-level "Schedule" page containing a calendar showing due dates and other class events. Others may wish to have a "News" page containing announcements. Still others may wish to store exams and other course data files in their site. This chapter provides documentation on how to enhance your Morea site with all of these other kinds of information.

To effectively go "beyond Morea", you need to have a basic conceptual understanding of the organization of your repository and the locus of control for the three fundamental tools: GitHub, Jekyll, and Morea. This organization is illustrated by the following graphic, which shows the master branch of the basic-template repository:

This graphic shows that a Morea site is organized like an onion with three layers, each "managed" by a different combination of tools.

Morea managed. In the center is the "Morea layer", which consists of all the files in the morea/ directory. It is here where you define the modules, outcomes, readings, experiences, and assessments for your course. There is a Morea plugin to Jekyll that looks for the contents of this directory and parses all the files inside to create the Modules, Outcomes, Readings, Experiences, and Assessments pages.

Jekyll managed. However, Morea is also just a Jekyll static website which builds a site based upon the contents of the src/ directory. As a result, you can customize your site by making any valid Jekyll enhancements in this directory.

GitHub managed. If we go up one more level of abstraction, your Morea site is just a GitHub-managed repository. The outermost level, above the src/ directory, contains files and directories that are not touched by Jekyll but are still part of your repository. You can put files or directories here that you do not want to be processed by Jekyll but that you wish to be associated with the course.

Up to now in this User Guide, we've focused almost exclusively on the contents of the morea/ directory. In this section, we'll now start making enhancements outside this directory in order to leverage additional capabilities of Jekyll and GitHub.

One of the most simple enhancements you can make to a basic Morea site is to add a new link to the navbar. To accomplish this, simply edit the navbar definition code found in your master/src/_layouts/default.html file. For example, here is an enhanced version of the navbar code within the default.html file with a link to a Google Group:

Essentially, you just add a new <li> tag containing your link.

An equally easy enhancement is a dropdown menu containing a list of links. Here's an example:

As before, you edit the navbar code in your default.html file, this time with the Twitter Bootstrap dropdown menu code. Here is the section implementing the dropdown menu from the above screenshot:

You'll need to edit this code by replacing the contents of the <li> elements with your own links.

See the above code in context here.

A common desire for a course website is a navbar element containing a link to a page containing a calendar of events. There are at least three approaches:

2. Use just a third-party Javascript Library such as Full Calendar. These libraries produce nicely formatted calendars, but used alone you have to manually add events using their local data structures.

3. Combine Google Calendar with Full Calendar. The best of both worlds! This is the approach documented in this section.

For example, here's the ICS 314 Schedule Page:

Here are the steps:

Step 1. Create your Google Calendar. Using the Google Calendar application, create a new calendar to hold the events associated with your course. Create a test event for today so that something shows up when you display the calendar for testing.

Step 2. Create a Google API key. See the FullCalendar Google Calendar API key documentation for the steps you need to take to do this. For the referrers field, a good approach is to restrict the websites to your github.io sites. For example, if your github username is 'philipmjohnson', then the referrers field should be: 'philipmjohnson.github.io/*'. That means that you can use the same API key for all your Morea sites, and also that others can't use your API key.

Step 3. Create the schedule page files. In the src/ directory, create a new subdirectory called schedule/ containing an index.html page.

You can copy the contents of the ICS314 schedule/index.html to use as a template. Here is a snapshot of the code:

You will need to modify this code in a few places to display your own calendar appropriately:

Third, modify the googleCalendarId to the calendar ID for your calendar. This is found on the settings page for your course's Google Calendar. It typically has the suffix 'group.calendar.google.com'.

Fourth, you may want to change the "eventColor" parameter value to be more compatible with your theme.

Finally, you will probably want to delete the line containing the 'gotoDate' command so that your calendar defaults to displaying the current month. But this code also shows how you can make the calendar default to displaying a month of your choosing.

Step 4. Extend the navbar with a link to this page. Once you've created the index.html file, you will want to add a link to this page to the navbar. The navbar code is available in your master/src/_layouts/default.html file. For example, here is the ICS 314 schedule navbar code. Essentially, all you need to do is add a single line:

<li><a href="{{ site.baseurl }}/schedule/">Schedule</a></li>


Step 5. Test your calendar. Now commit your changes to GitHub, and retrieve your site's Schedule page from the GitHub site. You should see your calendar and the test event. Note that calendar events will not be displayed when you run the site locally. They will only display once you publish your site on GitHub and display the page there.

Another common desire is a page containing news and announcements. For this feature, we can exploit Jekyll's built-in blogging support. We will write each news item following the conventions for a Jekyll blog post, then create a page that displays these posts using the Morea look-and-feel. For example, here is the ICS 311 News Page:

Adding this feature to your own site requires the following steps: create one or more news items, create the page to display them, add a link to this page to your navbar, and update your _config.yml file so RSS feeds work correctly.

Step 1. Write some example news items. To start, you should write a couple of sample Jekyll blog posts representing course news items. This means updating the _posts directory with your news items. For example, here is what the ICS 311 _posts directory looks like:

Here is an example of one news item in Jekyll blog posting format:

Step 2. Add a page to display your news items. Now that you have some sample news items, you should create the page that displays them. There are many ways to format news items, and you can do it whatever way you want, but the following instructions show how to duplicate the format illustrated above for the ICS 311 site.

First, create a new directory called news/, and add an index.html file within it with the following contents:

This code in context is available here.

This code in context is available here.

Step 4. Update _config.yml file with a url parameter. The final step is to add a url parameter to your _config.yml file so that that site.url variable can be referenced correctly in the feed.xml file. Here's an example line:

Notice that there's no ending slash.

Non-Morea markdown files

In certain situations, you may wish to have a markdown file within your module's directory that is not listed as an outcome, reading, experience, or assessment. A common example is a quiz page. Of course, you could create a directory called quizzes/ outside the morea/ directory and put the quiz files there, but then they would not be in the same directory as the module.

To support this situation, Morea processes markdown files in different ways depending upon their extension. If the extension is .md, then the file is processed as a Morea file and various YAML parameters are required (such as morea_id).

If the extension is .markdown, the file is processed as a regular Jekyll file and converted to HTML. This allows you to create markdown files in a module directory that are not modules, outcomes, readings, experiences, or assessments.

Here is an example from the ICS 311 site:

The actual page is available here.

Here is a portion of the source page to illustrate how it was created:

This code in context is available here.

When creating these pages, please be aware of the following:

• To have the page appear with the site header and footer, include the YAML front matter layout: default.
• To provide the standard left and right margins, include the YAML front matter topdiv: container.
• The HTML page is generated in the same directory path as the path where the source file is located.

Most importantly, if you are using this mechanism to create quizzes, be sure to make your repository private so that students do not have access to the source file for the quiz. In addition, the file should be named something that is not easily guessed by students (i.e. "security through obscurity").

In many cases, you might want to keep files in your repository that are not made a part of the published website. There are two ways to do that: either inside or outside the morea/ directory.

The _ignore directory

The Morea processor ignores any directories inside the morea/ directory that are named _ignore. So, if you create a directory called java/ to hold the contents of the Java module, and then put a subdirectory inside java/ called _ignore, the contents of that directory will not appear in the published site. This is a nice way to keep tests associated with a module but not make them available on the site.

Go outside src/

A second way manage private data is to create a directory outside the src/ directory, named something like private/, and place your private files inside that directory. All files and directories outside the src/ directory will not be touched by Jekyll or Morea.

For example, the following screenshot shows a private/ directory in the ICS 311 master branch containing a file called midterm.doc:

Since this private/ directory occurs outside the src/ directory, Jekyll will leave this directory unprocessed and its contents will not appear in the (public) gh-pages branch of your repository.

Note that if you do not want the public (i.e. your students) to be able to access this directory in the master branch, you must make your repository private!