Quick start

This quick start takes you through the steps necessary to set up and publish a new Morea course site with "default" content.

Join GitHub

If you haven't already, sign up for GitHub. There are two common types of GitHub accounts:

• Free Accounts. You can use a GitHub "Free" account to create Morea sites, but with one important restriction: you cannot make your repository private and publish the site with GitHub Pages. If your Morea source code is in a public GitHub repo, then you should not store private information (such as tests) in your repo. If you are OK with anyone (including students) seeing every file stored in your Morea repo, then a Free Account is fine.

• Education Accounts. If you are approved for a GitHub "Educator" account, then you can upgrade the organisation containing your Morea site repo to "Team" status for free. Organizations under the "Team" plan can have private GitHub repos that are published with GitHub Pages. This is quite useful, because it means you can store tests and other confidential information in your repo using Morea's private files mechanism. If you are associated with an educational institution, you can apply for an educator or researcher discount. Once you have been approved for the GitHub Educator Plan, you can go to the Upgrade Organization page to upgrade the organization containing your Morea site repo to the Team plan for free.

Create your course repository

Login to GitHub and go to https://github.com/morea-framework/morea:

Next, click "Use this template" and fill out the page:

• Provide a repository name (typically the course number and semester).
• Make the repo private (if the organization associated with this repo is on the Team plan). Otherwise, you must keep the repo public so that you can publish your site using GitHub Pages.
• Include all branches.

It should look like this:

When you are done, click on "Create repository from template". After the repo is created, you should be at a page in your own GitHub account with a copy of the Morea files:

Configure the config.yml file

Next, scroll down the list of files until you see "_config.yml", and click it:

Click on the pencil icon to edit this file within your browser:

Make the following changes to this file:

• Edit the "name:" field to specify your course name. (Example: "CS 299 Fall 2021")
• Edit the "baseurl:" field to specify your repository name. (Example: "/cs299fall21").

Here's what it might look like:

Now scroll down to the bottom of the page, write in a commit comment (i.e. "Update _config.yml"), and click "Commit changes".

Verify that GitHub built the site

Next, click on the "Actions" tab. You will see a workflow running. This task is building your site and deploying the HTML pages to the gh-pages branch of your repository. When it has completed, you should see a green checkbox next to your commit:

tip

If the site does not build correctly, first check to make sure the baseurl field matches the repository name. If it doesn't, then just edit the file, commit the change, and wait for the build to conclude.

If that doesn't fix it, please contact a Morea developer (i.e. Philip Johnson (johnson@hawaii.edu)).

The first couple of workflow runs could take several minutes, but these runs result in caching that should decrease subsequent build times substantially. After this initial setup, your site should typically build in less than a minute.

Verify that the site is published

Now click on the Settings tab, then click "Pages". You should see the following:

Please click the "Enforce HTTPS" checkbox.

Display your published course website

Now click on the link in the GitHub Pages page to see your newly published Morea site. It should look similar to this:

Unfortunately, apart from the site name in the menubar ("CS 299 Fall 2021"), none of this content is appropriate for your course!

Before proceeding, you might want to spend a few minutes clicking around your newly site. This site illustrates many (though not all) of the features of a Morea site.

The next two sections guide you through the tools you need to install to develop a Morea site on your computer as well as some simple examples of modifications to your sample site.