The contents of the properties.yaml file
This is a YAML formatted file containing course-wide parameters. It defines the following aspects:
In addition, two (optional) supporting files :
allow additional aspects to be specified.
The credits entry will be presented as a subtitle on the course home page:
credits: Tutors Team
This can be any suitable string.
A course image/ icon will be displayed in the title bar when on the course home page. The image/icon also appears occasionally on other areas on the course web. It can be specified as a single image file in the root folder:
Alternatively, you can specify an actual SVG Icon. Select an icon from this service:
Specify the Icon in properties.yaml like this:
icon :
type: fa-solid:code-branch
color: FFD601
This icon is drawn from this resource on Iconfy:
Any course can also have (optionally) a single parent course
parent : course/wit-hdip-comp-sci-2021.netlify.app
This can be an absolute link, or a relative link to another tutors course (as shown above). The parent will appear in the breadcrumbs toolbar, represented as a home icon. Clicking this link will load that course into the current window (if a relative link as shown in the snippet above is used).
The companions toolbar hosts a set of links to external services. These can include:
These can be specified as follows:
slack : https://wit-hdip-comp-sci-21.slack.com/
moodle : https://moodle.wit.ie/course/view.php?id=176625
youtube : https://www.youtube.com/playlist?list=PLEuhMaR29LyDMF2m4kSS9gVRCuimgo3GU
zoom : https://wit-ie.zoom.us/j/96265735671
teams : https://www.microsoft.com/microsoft-teams/join-a-meeting
You may choose to have a single companion, or none as approprioate. If you have a commpanion not in the above list, then the link, + icon can be specified like this:
companions:
piazza:
link: https://piazza.com/
title: Piazza Q & A for this course
icon:
type: academicons:piazza
color: info
The above defines a companion icon to a Piazza service.
If your course in on GitHub, and you decide to make repo the course public, then you may like to have tutors include an “Edit this page” button on the main header. To enable this, include a github property in properties.yaml. E.g:
github: https://github.com/tutors-sdk/tutors-reference-course/blob/main
Note that we append /blob/main to the github url - indicating you published from the main branch. You can change this as appropriate.
You can see it in action here:
It can be particularly useful for labs - with the edit button opening the markdown page in edit mode when selected:
On GitHub, when an (non-owner) attempts to edit a page then GitHub will prompt the user to fork the repo, and edits will then be proposed as PRs, which the course author can choose to accept or reject.
When publishing a course, you may wish hide some topics, but have access to them to check formatting or layout aspects. Also, you may have an entire course already laid out, and wish to just publish a subset of the topics.
Consider the following example:
ignorepin : 4019
ignore :
- topic-01-navigation
- topic-02-templating
- topic-03-semantic-code
# - topic-04-starting-play
# - topic-05-introducing-mvc
If the above course had 5 topics, then topics 04 and 05 will be ‘ignored’, i.e. not displayed. Effectively, we are ‘commenting out’ - via the # symbol, the first three topics - which means they will be visible to all students.
The instructor however, who will make up the ignorepin, can see all topics by entering the PIN code anywhere on the course canvas. In this way the instuctor can publish a topic per week (by commenting out an entry), but will be able to inspect unpublished topics by entering the PIN code.
Occasionally, you may like to remove all videos from your course. This might be as the academic year rolls over perhaps, and you wish to leave the course online, but remove all videos.
hideVideos : true
This does not delete the video, or remove the video ids, that may be threaded through the content. It merely hides the videos, leaving all the assets in place.
By default, tutors courses are public. You can force users to authenticate before they have access to the course (apart from the landing page) via this setting:
auth : 1
With this enabled, then entering a topic will trigger an authentication event. Users will only be permitted further by Signing in with a valid Github account. Any Github account will be accepted. When a user is logged in, a new Profile menu will appear, enabling access to additional course contextual information:
Tutors Time: Some usage data is being gathered for authenticated users - which is now accessible via this menu. This is largely focussed on labs - specifically the time, in minutes, that a lab is active in the users browser. An instructor can use the PIN code they have set up (ignorepin) to reveal data for all students
Tutors Live: This will show a card for each user currently logged in. It will take approx 1 minute to ‘warm up’ - and then as users come and go to the course web cards will appear and disappear. Students might use this to get in touch which whomsoever is currently online. The card for each student will display useful context information concerning the current activity of the student:
See TutorsTime for a more detail on data gathering and usage.
For some courses, you may not wish to have any topics at all, just units and links perhaps to other courses. For example this course here. Notice that this course does not have:
This is enabled with the ‘portfolio’ property:
portfolio : true
This is the source for a course using this property.
You may choose to prominently display an academic calendar - with the current week number highlighted. To set it up, include a file called calendar.yaml into your course folder. Here is an example:
title: Semester 1
weeks:
- 2021-08-30:
title: 1
type: tuition
- 2021-09-06:
title: 2
type: tuition
- 2021-09-13:
title: 3
type: tuition
- 2021-09-20:
title: reading 1
type: reading
- 2021-09-27:
title: 4
type: tuition
- 2021-10-04:
title: 5
type: tuition
The title of the semester followed by a specification for each week:
in the format shown in the example above.
Using a calendar in conjunction with authentication adds another dimension to TutorsTime, showng estimates of the time online across the semester specified in the calendar file. An instructor can use the PIN code they have set up (ignorepin) to reveal data for all students.
If authentication is enabled, then any user with a GitHub account can sign in to a course. In some circumstances that can make interpreting the TutorsTime data difficult, as it may include data from users not strictly students on the course. To this issue you can (optionally) provide an enrolment file - enrollment.yaml. If present, then the TutorsTime reports will be limited to the students listed.
- github-student-id-1
- github-student-id-2
- github-student-id-3
- github-student-id-4
- github-student-id-5
How to get the IDs? The simplest method is to wait for a few sessions, and all students have logged in. Then, in TutorsTime enter the ignore pin to reveal Labs for All Students. The green export icon (a small disk) will allow you to export all data to an Excel file.
By default, the contents of the enrollment file is not a Whitelist as such - ie. non-students can still access the module. If you would like to only permit the students listed in the enrolment file to access the course, then include the following:
whitelist : 1
Remember, authentication must also be enabled for this to work:
auth : 1
… and you must, of course, have an accompanying enrollment file.
You may prefer all steps in all your labs to be autonumbered. This will preppend a number, starting at 01, to all steps
labStepsAutoNumber: true
This is independent of the ‘sort-key’ segment in the lab step name.
Tutors provides the following services:
Gallery: a selection of 50 or so unique modules
Catalogue: a general listing of all known Tutors courses
Live: live view of which course are active live (all users are anonymous on this view)
If you wish your course to be excluded from all of the above, then you can mark it private with the following entry in properties.yaml:
private: 1
In addition to withdrawing a private course from the above services, the course will also remove the Log in / Profile menus from the header, disabling the dashboard and any sign in capabilities.
The tutors reader will render talks using the Adobe PDF Embed API. An alternative reader based on the Mozilla pdf.js project is also available.
To use Mozilla by default in all Talks:
defaultPdfReader: mozilla
To use Adobe:
defaultPdfReader: adobe
Adobe is also the default.
Your course can be made available in a format suitable for processing by Large Language Models (LLMs). Include the following entry in properties.yaml to enable this:
llms: true
This will provide a link in the Navigator (next to the search button) to and Llm page for your course. This is an example here. The LLMs links page will look like this:
We support the llms.txt convention for making documentation available to large language models and the applications that make use of them. Currently, we have the following files…
- llms-full.txt — the complete course
- llms-labs.txt — just the labs
- llms-notes.txt — just the notes
The content of these files can be saved and uploaded to ChatGPT, Claude or one of the other LLMs.
Text in Talks (pdfs) is currently not represented (yet).
Some images you mau choose to use may be hi-resolution, appearing to be super sized on the canvas. This can be a particular issue with screen shots. This service here:
Allows you to resize the image to a suitable ‘canvas’ size.
A reference course is located here:
and is published here:
This course illustrates all Tutors featues. It can be downloaded here: