This is the Tutors course Tutors Reference Manual by The Tutors Team, SETU, Ireland # Tutors Reference Manual Tutors Reference Manual A reference manual for tutors course creators. # Course : Tutors Reference Manual A reference manual for tutors course creators. ## Unit : Getting Started ### Note : Getting Started *The basic model of Tutors* --- [[toc]] --- Tutors is a collection of open source components and services supporting the creation of transformative learning experiences using open web standards. It consists of two key components: - *Generator:* transforms a [folder of learning content](https://github.com/tutors-sdk/tutors-reference-course) into a Tutors course - *Reader*: presents a Tutors course as an intuitive, discoverable and attractive [Web experience](https://tutors.dev/course/reference-course) These components are [developed in the open](https://github.com/tutors-sdk/tutors) by an active and friendly community, based on a clear [set of values](https://tutors.dev/note/tutors-reference-manual/unit-0/note-12). # First Course Visit [this course](https://tutors.dev/course/tutors-starter-course) to become familiar with the general structure of the learning experience. [Download the source](https://github.com/tutors-sdk/tutors-starter/archive/refs/heads/master.zip) for the course and unzip to a local folder. Spend a few minutes exploring the content of the folder using a good editor, for example [Sublime Text](https://www.sublimetext.com/). Install [Deno](https://deno.com/), a modern, secure runtime javascript engine. On Windows/Linux, this is the Deno install command: ~~~ irm https://deno.land/install.ps1 | iex ~~~ On Mac: ~~~ curl -fsSL https://deno.land/install.sh | sh ~~~ You can also create a free account on the [Netlify](https://www.netlify.com/) service. # Publish to Netlify Open a [command prompt/terminal at the course folder](https://www.groovypost.com/howto/open-command-window-terminal-window-specific-folder-windows-mac-linux/) you created above and enter the following command: ~~~bash deno run -A jsr:@tutors/tutors ~~~ This should generate a response like this (shortened here): ~~~text : tutors-starter : Tutors Starter --: topic-01 : Simple Units ----: unit-1 : Main Lesson ------: book-a : Objectives ------: talk-1-intro : Lecture 1 ------: talk-2-explore : Lecture 2 ----: unit-2 : Supporting Resources ------: archive : Resource 1 ------: note-1 : Note 1 ------: web-1 : Web Site 1 ... ----: unit-2 : Unit 6 Title ------: talk-1 : Lecture 10 ------: web-1 : Zoom Morning Room ------: web-2 : Podcast tutors-publish: 4.1.0 ~~~ A new folder called **json** will be generated by the above command. Drag & Drop this **json folder** to Netlify using this [drop target site](https://app.netlify.com/drop/) (assuming you are logged in to Netlify) . This will publish the course on the web, generating a unique url which you can verify almost immediately. You can [customise the free domain name](https://stevemats.medium.com/how-to-rename-netlifys-default-subdomain-name-e2d493e40d6e) directly on Netlify. If you make any changes to the course source folder, then you must proceed through the generation (*deno run -A jsr:@tutors/tutors*) and publishing (drag & drop) to redeploy the course. Be sure to overwrite the existing course on Netlify, unless you want a new course. In this case, locate the deployment panel for the newly created project on Netlify and drag & drop the json folder there. If you wish to set up a publication pipeline from a GitHub repo, then you can link the Netlify project to your course repo such that Netlify will automatically re publish the course whenever you update on Github. This will require you to import the project into Netlify: ![](img/netlify-1.png) Once imported, the **Build Command** should be: ~~~ deno run -A jsr:@tutors/tutors ~~~ Then **Publish directory**: ~~~ json ~~~ ![](img/netlify-3.png) Any push to the repo will trigger a rebuild of the site. # Publish to Vercel Create an account on [Vercel](https://vercel.com). Once logged in, create a new project. You will need to link the project to a github repo containing the tutors course. Include the following file in your courese: ## vercel.json ~~~json { "version": 2, "buildCommand": "npx -y deno-bin@latest run -A jsr:@tutors/tutors", "outputDirectory": "json", "framework": null } ~~~ Whenever you push an update to the repo, it will build and deploy on Vercel. For the hobby (free) account, your course repo must be public. # Alternative Static Site Publish There is secondary publication mechanism, which is invoked as above, but with a different command: ~~~bash deno run -A jsr:@tutors/tutors-lite ~~~ This will also generate a folder of content in the course folder - this time in a **html** subfolder. You can open this folder and load the **index.html** therein in a browser (generally just double click). This will open a local version of the course offline (on your workstation only). This is an example here: - [Tutors Reference Course](https://tutors-reference-course-html.netlify.app/index.html) This does not provide the complete Tutors user experience, but can be a useful as a backup, an alternative UX and also perhaps as the basis for an archive of the course that can be distributed as a zip file (compress and distribute the html folder only) when a course concludes. The archive can be opened by the students independently, with all course assets held locally, except for videos. The **html** folder can also be published to any web server, including Netlify using the same process as outlined above. # More Course Examples The first course example above is a typicaly tutors course, with a basic structure. This example: - [Alternative Layouts](https://tutors.dev/course/layout-reference-course) ... incorporates different layouts + nesting of learning objects in various confurations. Download the source [here](https://github.com/tutors-sdk/layout-reference-course/archive/refs/heads/main.zip) This example is a complete reference course illustrating all Tutors features: - [Reference Course](https://tutors.dev/course/reference-course) Download the source [here](https://github.com/tutors-sdk/tutors-reference-course/archive/refs/heads/main.zip) ### Note : Cards & Resources *What Cards represent in Tutors* --- [[toc]] --- # Cards The card metaphor is used throughout tutors as a simple visual feature to represent a variety of learning resources. In general the contents of a card are extracted from the following: - A Markdown file, containing resource title + short summary - An image, in png, jpg, gif or svg formats. The title, image and summary will be presented on the card, along with a suitable icon. The Learning resources are typically named to match the context, and are contained in a folder whose name is structured to encode the type of learning resource. ## Resource Names Folder names convey the type of learning resource contained in the folder, with the first letters determining its type. Folders starting with the following names have a significance in Tutors: | Example | Source | | -------------------------------------------------------------------------------------------- | ------------------------------------------ | | [topic](https://tutors.dev/topic/reference-course/topic-01-typical) | [Top level course topic ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical)| | [unit](https://tutors.dev/topic/reference-course/topic-01-typical) | [Group of learning objects within a topic ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1)| | [side](https://tutors.dev/topic/reference-course/topic-02-side) | [Group of learning objects framed in a sidebar ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-02-side/side-unit)| | [archive](https://tutors.dev/wall/archive/reference-course) | [Downloadable zip file of resources ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/archive)| | [book](https://tutors.dev/lab/reference-course/topic-01-typical/unit-1/book-a) | [Step by step lab instructions, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1/book-a)| | [PDF book](https://tutors.dev/lab/reference-course/topic-02-side/side-unit/book-c) | [Problem or exercises sheet, authored as a PDF ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-02-side/side-unit/book-c)| | [github](https://tutors.dev/wall/github/reference-course) | [Link to a GitHub repository ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical)| | [note](https://tutors.dev/note/reference-course/topic-01-typical/unit-2/note-1) | [Single web page, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-2/note-1)| | [tutorial](https://tutors.dev/tutorial/reference-course/topic-07-reference/tutorial-2) | [Single web page, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/tutorial-2)| | [PDF tutorial](https://tutors.dev/tutorial/reference-course/topic-07-reference/tutorial-1) | [Portrait oriented PDF ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/tutorial-1)| | [panelvideo](https://tutors.dev/topic/reference-course/topic-03-media) | [A full screen width video, hosted in YouTube or HEANet](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/panelvideo-1)| | [paneltalk](https://tutors.dev/topic/reference-course/topic-05-panel-talk) | [Full screen width presentation in pdf format ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-05-panel-talk/paneltalk)| | [panelnote](https://tutors.dev/topic/reference-course/topic-04-panel-note) | [Full screen width note](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-04-panel-note/panelnote) | | [talk](https://tutors.dev/talk/reference-course/topic-01-typical/unit-1/talk-1-intro) | [Standard presentation in pdf format ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1/talk-1-intro)| | [web](https://tutors.dev/wall/web/reference-course.netlify.app) | [Link to an external web site ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-2/web-1) | | [podcast](https://tutors.dev/topic/reference-course/topic-09-podcasts) | [Podcast episode](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-09-podcasts/side-unit/podcast) | To sort the name alphabetically you may append numerals. To enhance meaning, append contextual keywords. For example: | Folder Name | | ---------------------- | | topic-01-introduction | | topic-02-learning-html | For all file & folder names, avoid spaces within a file name. | Do | Don't | ---------------------- | -------------------- | | topic-01-introduction | Topic 01 Introduction | topic-02-learning-html | Topic 02 Learning HTML ## File Names Each resource will typically have the following files: | File | Purpose | | ---------------------- | ------------------------------------------------------------ | | some-resource-name.md | A markdown file, typically containing title + short summary for the resource | | some-resource-name.png | Image to he used for the resource. Name must be the same as the .md file, image can be .png, .jpg. .jpeg, .gif | The following filenames are reserved: | File name | Description | | --------------- | ----------------------------- | | course.md | Title for course (mandatory) | | properties.yaml | Course properties (mandatory) | | course.png | Course image | | calendar.yaml | Course calendar | | enrolment.yaml | Student enrolment file | | weburl | link to external web site | | videoid | id of external video | | githubid | link to github repo | # Image resizing 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. ### Note : Course Structure *The structure of a tutors course* --- [[toc]] --- # Course Structure A Tutors course is a folder of learning resources, named according to the conventions described in this manual. | Example Resource | Display | | ---------------- | ------- | | [reference-course](https://github.com/tutors-sdk/tutors-reference-course) | [Reference Course](https://tutors.dev/course/reference-course) | The minimum requirements for a course are a folder containing these three files: | File name | Purpose | | -------------- | ------------ | | course.md | Course title + general course information | course.png | Course image | properies.yaml | Course properties ## course.md A markdown file, structured as follows: ~~~markdown Course Title Course information - a course outline, description or any other information. ~~~ ## properties.yaml Course metadata in yaml format. At a minimum, this must contain the following: ~~~yaml credits: The course author(s) or organisation ~~~ The credits property will appear as a subtitle in the course title bar. There are a range of other optional properties. See [later in this document]( https://tutors.dev/note/tutors-reference-manual/unit-0/note-10)for a complete list of valid properties. A course folder will typically contain topics (see below). Occasionally you may choose to place units directly in a course folder. Courses typically contain topics, represented as folders with *topic* as the first 5 letters in the folder name. These topics can units (described below) ## Topic Top level learning resource for a course. Typically encapsulating a session or week of learning material. | Example Resource | Display | | ---------------- | ------- | | [topic-01-typical](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical) | [Typical Topic](https://tutors.dev/topic/reference-course/topic-01-typical) | Two files are required: | Files | Purpose | | --------------- | ------------ | | topic.md | Topic title + summary. Any file name, file type must be .md file type | | topic.png | Image for topic. File name must be same as .md file. File type can be .png, .jpg, or .jpeg| ## topic.md The title and subtitle are extracted from the .md file, for example: ~~~~markdown Simple Units with presentations, labs + resources ~~~~ In addition to the title, subtitle + image files specified above, the topic can contain any number of units (see below) or other learning resources. ## Unit A unit will encapsulate learning resources, framed by a title. Units can be within topics, or can appear directly in a course folder. | Example Resource | Display | | ---------------- | ------- | | [unit-1](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1) | [Main Lesson](https://tutors.dev/topic/reference-course/topic-01-typical) | One .md file is required: | Files | Purpose | | ------- | ------------------------------------------------------------ | | unit.md | Title for the unit. The file can have any suitable name, but must be .md file type | The title is specified in a single markdown file: ## unit.md ~~~markdown Main Lesson ~~~ Units contain any number of learning resources. ## Side A side will encapsulate learning resources, framed by a title. It is equivalent to a Unit (see above), but framed within a side bar. | Example Resource | Display | | ---------------- | ------- | | [side-unit](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-02-side/side-unit) | [Labs for this Topic](https://tutors.dev/topic/reference-course/topic-02-side) | On .md file is required: | File name | Purpose | | --------- | ------------------------------------------------------------ | | side.md | Title for the side bar. The file can have any suitable name, but must be .md file type | The title is specified in in this file: ## side.md ~~~markdown Labs for this Topic ~~~ Side bar can contain any number of learning resources. # Learning Resources There are 2 broad types of learning resources - Card Resources - Panel Resources Typically card or panel learning resources are child folders within topic, unit or side folders. ### Note : Course Properties *The properties.yaml file* --- [[toc]] This is a [YAML formatted](https://circleci.com/blog/what-is-yaml-a-beginner-s-guide/) file containing course-wide parameters. In addition, two (optional) supporting files : --- # Course attribution/credit The credits entry will be presented as a subtitle on the course home page: ~~~yaml credits: Tutors Team ~~~ This can be any suitable string. # Course Image/Icon 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: - course.png Alternatively, you can specify an actual SVG Icon. Select an icon from this service: - Specify the Icon in `properties.yaml` like this: ~~~yaml icon : type: fa-solid:code-branch color: FFD601 ~~~ This icon is drawn from this resource on Iconfy: - # Course Parent Any course can also have (optionally) a single `parent` course ~~~yaml 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). # Course Companion Sites The companions toolbar hosts a set of links to external services. These can include: - Slack Channel - Moodle Course Web - Youtube Playlist/Channel - Zoom Meeting Room - Teams These can be specified as follows: ~~~yaml 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: ~~~yaml 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. # Edit Course Button 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: ~~~yaml 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. # Topic show/hide settings for instructors 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: ~~~yaml 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. # Global Video Hide 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. ~~~yaml 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. # Authentication 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: ~~~yaml 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. # Portfolio 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](https://tutors.dev/course/wit-hdip-comp-sci-2023). Notice that this course does not have: - Breadcrumbs navigation - Table of Contents This is enabled with the 'portfolio' property: ~~~ portfolio : true ~~~ This is the [source for a course](https://github.com/wit-hdip-comp-sci-2023/programme-home-page) using this property. # Calendar 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: ~~~yaml 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: - start date - title - type 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. # Enrollment 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. ~~~yaml students: - name: Student McStudious github: github-id-1 - name: Tutors McTutorios github: github-id-2 ~~~ ## Whitelisting 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: ~~~yaml whitelist - github-id-1 - github-id-2 ~~~ So a complete enrollment file might look like this: ~~~yaml whitelist: - github-id-1 - github-id-2 students: - name: Student McStudious github: github-id-1 - name: Tutors McTutorios github: github-id-2 ~~~ In the above example, students is optional. Remember, authentication must also be enabled for this to work: ~~~yaml auth : 1 ~~~ # Auto Numbering You may prefer all steps in all your labs to be autonumbered. This will preppend a number, starting at 01, to all steps ~~~yaml labStepsAutoNumber: true ~~~ This is independent of the 'sort-key' segment in the lab step name. # Private Tutors provides the following services: - [Gallery](https://tutors.dev/gallery): a selection of 50 or so unique modules - [Catalogue](https://tutors.dev/catalogue): a general listing of all known Tutors courses - [Live](https://tutors.dev/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: ~~~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. # Default PDF reader The tutors reader will render talks using the [Adobe PDF Embed API](https://developer.adobe.com/document-services/docs/overview/pdf-embed-api/). An alternative reader based on the [Mozilla pdf.js](https://mozilla.github.io/pdf.js/) project is also available. To use Mozilla by default in all Talks: ~~~yaml defaultPdfReader: mozilla ~~~ To use Adobe: ~~~yaml defaultPdfReader: adobe ~~~ Adobe is also the default. If you use Adobe, the default mode will be to display the pdf in "landscape" orientation - displaying a single slide at a time in a 16:9 aspect ratio. This is best for presentations / slides. If you would prefer a portrait style display - perhpas an A4 document, then include the following: ~~~yaml pdfOrientation : portrait ~~~ # Large Language Model support Your course can be made available in a format suitable for processing by Large Language Models (LLMs). This takes the form of a dedicated page on your course. If this is your course url: - https://tutors.dev/course/tutors-starter-course Then this is could be the llm page: - https://tutors.dev/llm/tutors-starter-course *(llm* instead of *course* in the route). Your course may need to re-deployed with the latest tutors-publish for this to be available. This Llm page makes available the following assets: - A link to a markdown version of the entire course, as a singe standalone page - A link to a zip archive of all Talks in the course - Links to the YouTube videos This is followed by a version of the above for each topic only. This will be in the form of links under each topic in your course. See this [example here](https://tutors.dev/llm/tutors-starter-course). You can submit all of the above to many Llms. For Pdfs, you may need to upload pdf files individually. Sometimes it is more useful to submit resources by topic. [Google Notebook LLM](https://notebooklm.google.com/) for instance works well for topic based resources. So you could create a Notebook for each topic - and then generate notes, quizzes, FAQs, and Podcasts! confined to each individual topic. If you would like to advertise the link to these resources, then place this in the properties.yaml: ~~~yaml llm: 2 ~~~ This will place a small 'idea' icon next to the search button in the course navigator. If you would like to keep the page, but not advertise the link then: ~~~yaml llm: 1 ~~~ If you would like the page to be disabled - and no llm content generate then set to 0: ~~~yaml llm: 0 ~~~ llm: 0 is the default behaviour if no setting is found, i.e. no llm content is generated be default. ## Unit : Presentation ### Note : Learning Resources *Enumerating the Tutors Learning Objects* --- [[toc]] --- # Learning Resources There are 2 broad types of learning resources - Card Resources - Panel Resources Typically card or panel learning resources are child folders within topic, unit or side folders. # Card Resources These resources are represented by simple cards that can appear in a topic, unit or side: | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Standard presentation in pdf format](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1/talk-1-intro) | [Lecture 1](https://tutors.dev/talk/reference-course/topic-01-typical/unit-1/talk-1-intro) | [Talks](https://tutors.dev/wall/talk/reference-course) | | [Single web page, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-2/note-1) | [Note 1](https://tutors.dev/note/reference-course/topic-01-typical/unit-2/note-1) | [Notes](https://tutors.dev/wall/note/reference-course) | | [Step by step lab instructions, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1/book-a) | [Lab 1](https://tutors.dev/lab/reference-course/topic-01-typical/unit-1/book-a) | [Labs](https://tutors.dev/wall/lab/reference-course) | | [Link to a web site ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-2/web-1) | [Web Site](https://tutors.dev) | [Web Links](https://tutors.dev/web/talk/reference-course) | | [Downloadable zip file of resources ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/archive) | [Archive 1](https://tutors.dev/wall/archive/reference-course) | [Archives](https://tutors.dev/archive/talk/reference-course) | | [Link to a GitHub repository ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical) | [Github Repo 1](https://github.com/tutors-sdk/tutors) | [Repos](https://tutors.dev/wall/repo/reference-course) | ## Talk A talk is a PDF presentation, document or other pdf formatted resource. | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Standard presentation in pdf format](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1/talk-1-intro) | [Lecture 1](https://tutors.dev/talk/reference-course/topic-01-typical/unit-1/talk-1-intro) | [Talks](https://tutors.dev/wall/talk/reference-course) | The pdf file, markdown description and image file must all have the same file name, which can be whatever you choose. | File name | Purpose | | ---------------- | ------------------------------------------------------------ | | introduction.md | Title + short summary for the talk. The file can have any suitable name, but must be .md file type | | introduction.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | introduction.pdf | Pdf to be rendered if the card is selected. The name must match the .md file name precicely | The .md file provides the card title + subtitle: ~~~markdown Lecture 1 A short summary of the talk, no more than two sentences. ~~~ ## Note A note is a full web page, authored in markdown. | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Single web page, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-2/note-1) | [Note 1](https://tutors.dev/note/reference-course/topic-01-typical/unit-2/note-1) | [Notes](https://tutors.dev/wall/note/reference-course) | Markdown is a simple text format for authoring web content: - If you choose to include local images or links to zipped archives you wish to be distributed with the note, you must include these in the note folder in specific subfolders: | Resource | Purpose | | ---------- | -------- | | note.md | The content of the note. Any suitable name, type must be .md | | note.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | img | A folder containing Images used by the note | | archives | A folder contains any zipped archives referred to in the note | Image links can be structured to in include relative references to the image. E.g: ![](img/img-link.png) The linked images must be included in the img folder in the note resource. Similairly, if you wish to distributed a zipped archive of learning resources, include the zip file(s) in the archives folder, and link like this: ![](img/zip-link.png) Links to external resources can be included with conventional web links. ## Tutorial A note is a full web page, authored in markdown. Is represented in a different category, with a different colour/icon from Notes | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Single web page, authored in markdown](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/tutorial-2) | [Tutorial 2](https://tutors.dev/tutorial/reference-course/topic-07-reference/tutorial-2)|[Tutorials](https://tutors.dev/wall/tutorial/reference-course) Markdown is a simple text format for authoring web content: - If you choose to include local images or links to zipped archives you wish to be distributed with the note, you must include these in the note folder in specific subfolders: | Resource | Purpose | | ---------- | -------- | | tutorial.md | The content of the note. Any suitable name, type must be .md | | tutorial.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | img | A folder containing Images used by the note | | archives | A folder contains any zipped archives referred to in the note | Image links can be structured to in include relative references to the image. E.g: ![](img/img-link.png) The linked images must be included in the img folder in the note resource. Similairly, if you wish to distributed a zipped archive of learning resources, include the zip file(s) in the archives folder, and link like this: ![](img/zip-link.png) Links to external resources can be included with conventional web links. ## PDF Tutorial A pdf presented in portrait orientation, intended for problem sets or worksheets. Is categorised with the Tutorial learning objects (see above). | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Document pdf format](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/tutorial-1) | [Tutorial-1](tutors.dev/tutorial/reference-course/topic-07-reference/tutorial-1)| [Tutorials](https://tutors.dev/wall/tutorial/reference-course) | The pdf file, markdown description and image file must all have the same file name, which can be whatever you choose. | File name | Purpose | | ---------------- | ------------------------------------------------------------ | | tutorial.md | Title + short summary for the talk. The file can have any suitable name, but must be .md file type | | tutorial.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | tutorial.pdf | Pdf to be rendered if the card is selected. The name must match the .md file name precicely | The .md file provides the card title + subtitle: ## TOC If the note content includes heading and subheading, then you can insert an automatic Table of Contents via this text: ~~~markdown [[toc]] ~~~ An example of this can be seen [in action here](https://tutors.dev/note/reference-course/topic-07-reference/note-2), this is [the source](https://github.com/tutors-sdk/tutors-reference-course/blob/main/topic-07-reference/note-2/my-note.md) of that example. Usually you would place this at the top of the note. ## BookLab A series of steps/instructions, authored in Markdown | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Step by step lab instructions, authored in markdown ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-1/book-a) | [Lab 1](https://tutors.dev/lab/reference-course/topic-01-typical/unit-1/book-a) | [Labs](https://tutors.dev/wall/lab/reference-course) | Markdown is a simple text format for authoring web content: - Each step in the lab is held in a separate markdown file. The step will have a full title, extracted from the first line of the step file. It will also have a short title, used for constrained (mobile) screen widths. The step files are named with three dot separated segments as follows: - [sort-key].[short-title].md Where: - [sort-key] ensures the step sequential position, sorted alphabetically/numerically. Typlicaly you might use a sequence like: 01, 02, 03, 04 etc... - [short-title] is a title used for constrained screen widths For example: - 00.Lab-01.md - 01.01.md - 02.02.md - 03.03.md The title + summary for the lab card is extracted from the short title for the first step. In the above example, the lab navigation side bar would be: - Lab-01 - 01 - 02 - 03 Image links can be structured in include relative references to the image. E.g: ![](img/img-link.png) The linked images must be included in the img folder in the lab. Similairly, if you wish to distributed a zipped archive of learning resources, include the zip file(s) in the archives folder, and link like this: ![](img/zip-link.png) ## Links within Labs Links to external resources can be included with conventional web links. If you wish to link to another step in the same lab, identify the url for the step, for instance: ~~~hmtl https://tutors.dev/lab/tutors-test-2/topic-01-typical/unit-1/book-a/04 ~~~ ... and formulate a link, trimming the `https://tutors.dev`, leaving the remaining segments: ~~~ /lab/tutors-test-2/topic-01-typical/unit-1/book-a/04 ~~~ You can then formulate a link using the conventional markdown link syntax: ![](img/lab-step-link.png) ## Auto Numbering You may prefer all steps in all your labs to be autonumbered. This will prepend a number, starting at 01, to all steps ~~~ labStepsAutoNumber: true ~~~ This is independent of the 'sort-key' segment in the lab step name. ## PDFLab Problem or exercises sheet, authored as a PDF. This resources Will be presented and grouped with Books/Labs. They are structured identically to Talks, except the containing folder name starts with `book-*`. | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Problem or exercises sheet, authored as a PDF ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-02-side/side-unit/book-c) | [Problem Sheet 1](https://tutors.dev/lab/reference-course/topic-02-side/side-unit/book-c) | [Labs](https://tutors.dev/wall/lab/reference-course) | ## Web A simple link to an external web resource. | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Link to a web site ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical/unit-2/web-1) | [Web Site](https://tutors.dev) | [Web Links](https://tutors.dev/web/talk/reference-course) | Three files are required: | Resource | Purpose | | ---------- | -------- | | web-link.md | Title + short summary for the link. The file can have any suitable name, but must be .md file type | | web-link.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | weburl | the full url for the resource | ## Podcast A podcast player, currenty provided by Spotify | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Podcast](https://tutors.dev/topic/reference-course/topic-09-podcasts) | [Podcast Player](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-09-podcasts/side-unit/podcast) | [Podcasts](https://tutors.dev/wall/podcast/reference-course) | Three files are required: | Resource | Purpose | | ---------- | -------- | | podcast.md | Title + short summary for the podcast. The file can have any suitable name, but must be .md file type | | episode | the podcast episode identifier| Currently supports the Spotify player, which requires the spotify episode id in this format: ~~~yaml spotify=722LWsc3uWc0zAqUHP8QHs ~~~ You can identify this id by locating the podcast on Spotify and select "Share->Copy link to episode". This should look like: ~~~yaml https://open.spotify.com/episode/3cqFe6wRbaadmPosSwckXh?si=8e60d1b6aa884327 ~~~ For the above, this would be the episode file: ~~~yaml spotify=3cqFe6wRbaadmPosSwckXh ~~~ ## Archive A link to a downloadable archive (zip). | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Downloadable zip file of resources ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-07-reference/archive) | [Archive 1](https://tutors.dev/wall/archive/reference-course) | [Archives](https://tutors.dev/archive/talk/reference-course) | The archive is bundled with the course source and hosted with the course resources. | Resource | Purpose | | ---------- | -------- | | archvive.md | Title + short summary for the archive. The file can have any suitable name, but must be .md file type | | archive.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | archive.zip | The archive that will be downloaded if the card selected | ## Github A link to an GitHub repository. | Example Resource | Display | Cards | | ---------------- | ------- | ----- | | [Link to a GitHub repository ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-01-typical) | [Github Repo 1](https://github.com/tutors-sdk/tutors) | [Repos](https://tutors.dev/wall/repo/reference-course) | Three files are required: | Resource | Purpose | | ---------- | -------- | | github.md | Title + short summary for the GitHib repo. The file can have any suitable name, but must be .md file type | | github.png | Image for card. File name must be same as .md file. File type can be .png, .jpg, or .jpeg | | githubid | Full url of the repo | # Panel Resources Panels appear directly in a unit or topic, and are not represented by a separate card. Instead, their contents are rendered directly onto the parent topic/unit/side. | Example Resource | Display | | ---------------- | ------- | | [A full screen width video, hosted in YouTube or HEANet](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/panelvideo-1) | [Main Video](https://tutors.dev/topic/reference-course/topic-03-media) | | [Full screen width presentation in pdf format ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-05-panel-talk/paneltalk) | [Main Talk](https://tutors.dev/topic/reference-course/topic-05-panel-talk) | | [Full screen width note](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-04-panel-note/panelnote) | [Main Note](https://tutors.dev/topic/reference-course/topic-04-panel-note) | ## Panelvideo A video to be displayed directly on the topic or unit resource. | Example Resource | Display | | ---------------- | ------- | | [A full screen width video, hosted in YouTube or HEANet](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/panelvideo-1) | [Main Video](https://tutors.dev/topic/reference-course/topic-03-media) | Two files are required: | Resource | Purpose | | ---------- | -------- | | video.md | Title for the video. The file can have any suitable name, but must be .md file type | | videoid | id of the video | See video section below for format of this videoid file. ## Paneltalk A PDF document to be displayed directly on the parent resource. | Example Resource | Display | | ---------------- | ------- | | [Full screen width presentation in pdf format ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-05-panel-talk/paneltalk) | [Main Talk](https://tutors.dev/topic/reference-course/topic-05-panel-talk) | Two files are required: | Resource | Purpose | | ---------- | -------- | | talk.md | Title for the document. The file can have any suitable name, but must be .md file type | | talk.pdf | The .PDF to display. Its name must be the same as the .md file | ## Panelnote A panel note is a full web page layed out directly on the parent resource. | Example Resource | Display | | ---------------- | ------- | | [Full screen width note](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-04-panel-note/panelnote) | [Main Note](https://tutors.dev/topic/reference-course/topic-04-panel-note) | The content is authored in markdown using the basic syntax: - The content is in a single file, images and archives may also be included: | Resource | Purpose | | ---------- | -------- | | note.md | The content of the note. Any suitable name, type must be .md | | img | A folder containing Images used by the note | | archives | A folder contains any zipped archives referred to in the note | Image links can be structured in include relative references to the image. E.g: ![](img/img-link.png) The linked images must be included in the img folder in the note resource. Similairly, if you wish to distributed a zipped archive of learning resources, include the zip file(s) in the archives folder, and link like this: ![](img/zip-link.png) Links to external resources can be included with conventional web links. ## Videos Panelvideos above are the primary mechanism for displaying videos prominently. The video is referenced in file always called: - videoid Videos are usually hosted on Youtube - and you will need a link to the video in order to embed in a tutors course. A typical YouTube URL looks like this: ~~~url https://www.youtube.com/watch?v=Hfw1lbErjws ~~~ You will typically use the video id: ~~~ Hfw1lbErjws ~~~ ... which is the last string after the `v=`. This is the contents of the videoid file. However, this videoid file can be dropped into most learning resources. If a resource has this file, then a video play button will feature in the Card for the resource, which will trigger the video player. ## Video Talks | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Video Only Talk](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/unit-1/talk-3) | [Lecture 7](https://tutors.dev/video/reference-course/topic-03-media/unit-1/talk-3/x09E7b2ESE8?start=1068&1370) | For Talk resources only, it is possible to drop the PDF completely and just include the video only. The card will display as with a PDF ## Video Chapters Youtube supports start/end times when linking to a video. This is via appending a start/end in seconds to the videoid file | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Video Chapter](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/unit-1/talk-2) | [Lecture 6](https://tutors.dev/video/reference-course/topic-03-media/unit-1/talk-2/x09E7b2ESE8?start=106&286)) | For example, this id specifies a start time and end time in second (separated by &): ~~~bash x09E7b2ESE8?start=106&286 ~~~ On youtube, this typically works best if the Youtube description also contains chapter information. For example, on YouTube Studio, chapters information can be included by incorporating start / end times into the video description. For example: ~~~bash Introduction 00:00:00 Svelte Core Concepts 00:02:54 Svelte Components 0:19:49 Donation App 00:27:55 Donation-Hapi V1 00:34:24 ~~~ For the above, the associated videoid files for each chapter would look like this: ~~~bash 9Srf_ydMdL0?start=0&174 9Srf_ydMdL0?start=174&1189 9Srf_ydMdL0?start=1189&1675 9Srf_ydMdL0?start=1675&2064 9Srf_ydMdL0?start=2064&6348 ~~~ ## HEANet Hosted Videos If you require an alternative to Youtube, you can use the HEANet service. | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Heanet Video](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/unit-2-heanet) | [HeaNet video example](https://tutors.dev/topic/reference-course/topic-03-media)) | Videos can be uploaded here: - If you wish to use this service, then your videoid file should look like this: ~~~bash heanet=7e4f1e9afedb40d5996d0703702eaaa4 ~~~ The id will be generated when you upload the video to the HEAnet media service. # Latex Notes and Books can have Latex content, implemented using the [Katex](https://katex.org/) component. | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Latex](https://github.com/tutors-sdk/tutors-reference-course/blob/main/topic-01-typical/unit-1/book-a/05.05.md) | [Latex Example](https://tutors.dev/lab/reference-course/topic-01-typical/unit-1/book-a/05) | You can express Latex content between "$" symbols. For example: ~~~latex $ x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a} $ ~~~ Will render as: $ x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a} $ You can also express content inline, so thisL ~~~latex This is an inline example: $c = \pm\sqrt{a^2 + b^2}$ with text before and after ~~~ This will render link this: This is an inline example: $c = \pm\sqrt{a^2 + b^2}$ with text before and after. # Ordering Learning Resources For a topic, unit or side resources, the ordering of the cards is as follows: - talk - lab - note - web - github - archive This can be customised via the introduction of [FrontMatter](https://docs.zettlr.com/en/core/yaml-frontmatter/) sections in the corresponding markdown files. | Example Resource | Display | | ---------------- | ------- | | [Ordering](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-08-ordering)| [Ordering Example](https://tutors.dev/topic/reference-course/topic-08-ordering) | This should contain an "order" number, which dictates the sequencing for the cards. ~~~yaml --- order: 1 --- ~~~ If the resouce is a Lab, then the first step should include the FrontMatter/order paramater. # SVG Icons If no image file is found in a resource, then Tutors will look to display an SVG Icon instead. This Icon is drawn from the Iconify collection: - | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Icon based cards](https://tutors.dev/topic/reference-course/topic-09-svg) | [Iconify](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-09-svg) | You can search for an icon in that collection, locate the reference and include this + a colour in a [FrontMatter](https://docs.zettlr.com/en/core/yaml-frontmatter/) section for the Learning Resource. For example: ~~~markdown --- icon: type: vscode-icons:file-type-pdf2 --- ~~~ The above icon is drawn from this resource: - For monochrome icons, you can also specify the icon colour: ~~~markdown --- icon: type: bi:filetype-pptx color: green --- ~~~ # Image resizing 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. # Reference Course A reference course is located here: - and is published here: - This course illustrates all Tutors featues. It can be downloaded here: - # ### Note : Panels *The Panel Learning Objects* --- [[toc]] --- # Panel Resources Panels appear directly in a unit or topic, and are not represented by a separate card. Instead, their contents are rendered directly onto the parent topic/unit/side. | Example Resource | Display | | ---------------- | ------- | | [A full screen width video, hosted in YouTube or HEANet](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/panelvideo-1) | [Main Video](https://tutors.dev/topic/reference-course/topic-03-media) | | [Full screen width presentation in pdf format ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-05-panel-talk/paneltalk) | [Main Talk](https://tutors.dev/topic/reference-course/topic-05-panel-talk) | | [Full screen width note](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-04-panel-note/panelnote) | [Main Note](https://tutors.dev/topic/reference-course/topic-04-panel-note) | ## Panelvideo A video to be displayed directly on the topic or unit resource. | Example Resource | Display | | ---------------- | ------- | | [A full screen width video, hosted in YouTube or HEANet](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/panelvideo-1) | [Main Video](https://tutors.dev/topic/reference-course/topic-03-media) | Two files are required: | Resource | Purpose | | ---------- | -------- | | video.md | Title for the video. The file can have any suitable name, but must be .md file type | | videoid | id of the video | See video section below for format of this videoid file. ## Paneltalk A PDF document to be displayed directly on the parent resource. | Example Resource | Display | | ---------------- | ------- | | [Full screen width presentation in pdf format ](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-05-panel-talk/paneltalk) | [Main Talk](https://tutors.dev/topic/reference-course/topic-05-panel-talk) | Two files are required: | Resource | Purpose | | ---------- | -------- | | talk.md | Title for the document. The file can have any suitable name, but must be .md file type | | talk.pdf | The .PDF to display. Its name must be the same as the .md file | ## Panelnote A panel note is a full web page layed out directly on the parent resource. | Example Resource | Display | | ---------------- | ------- | | [Full screen width note](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-04-panel-note/panelnote) | [Main Note](https://tutors.dev/topic/reference-course/topic-04-panel-note) | The content is authored in markdown using the basic syntax: - The content is in a single file, images and archives may also be included: | Resource | Purpose | | ---------- | -------- | | note.md | The content of the note. Any suitable name, type must be .md | | img | A folder containing Images used by the note | | archives | A folder contains any zipped archives referred to in the note | Image links can be structured in include relative references to the image. E.g: ![](img/img-link.png) The linked images must be included in the img folder in the note resource. Similairly, if you wish to distributed a zipped archive of learning resources, include the zip file(s) in the archives folder, and link like this: ![](img/zip-link.png) Links to external resources can be included with conventional web links. ### Note : Videos & Podcasts *How to include and configure videos* --- [[toc]] --- # Panelvideos Panelvideos above are the primary mechanism for displaying videos prominently. The video is referenced in file always called: - videoid Videos are usually hosted on Youtube - and you will need a link to the video in order to embed in a tutors course. A typical YouTube URL looks like this: ~~~url https://www.youtube.com/watch?v=Hfw1lbErjws ~~~ You will typically use the video id: ~~~ Hfw1lbErjws ~~~ ... which is the last string after the `v=`. This is the contents of the videoid file. However, this videoid file can be dropped into most learning resources. If a resource has this file, then a video play button will feature in the Card for the resource, which will trigger the video player. # Video Talks | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Video Only Talk](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/unit-1/talk-3) | [Lecture 7](https://tutors.dev/video/reference-course/topic-03-media/unit-1/talk-3/x09E7b2ESE8?start=1068&1370) | For Talk resources only, it is possible to drop the PDF completely and just include the video only. The card will display as with a PDF # Videos in Labs & Notes You can have either short videos, that can be bundled into the img folder, or you can have a youtube player. ## Short Video An example of a short bundled video: ::video[src="./img/video.mov"]:: The above is displayed using a convenient shortcut like this: ![](img/video-1.png) You can also associate a "poster" image, displayed before the image is played: ::video[src="./img/video.mov" poster="img/poster.png"]:: ![](img/video-2.png) The video file and the poster must be in the img folder. ## Embedded Youtube Player You will need the id from Youtube, then include like this: ![](img/video-3.png) This is how it will look: ::video[src="O6Jh_1bxDs4"]:: ## Video Chapters on Youtube Youtube supports start/end times when linking to a video. This is via appending a start/end in seconds to the videoid file | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Video Chapter](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/unit-1/talk-2) | [Lecture 6](https://tutors.dev/video/reference-course/topic-03-media/unit-1/talk-2/x09E7b2ESE8?start=106&286)) | For example, this id specifies a start time and end time in second (separated by &): ~~~bash x09E7b2ESE8?start=106&286 ~~~ On youtube, this typically works best if the Youtube description also contains chapter information. For example, on YouTube Studio, chapters information can be included by incorporating start / end times into the video description. For example: ~~~bash Introduction 00:00:00 Svelte Core Concepts 00:02:54 Svelte Components 0:19:49 Donation App 00:27:55 Donation-Hapi V1 00:34:24 ~~~ For the above, the associated videoid files for each chapter would look like this: ~~~bash 9Srf_ydMdL0?start=0&174 9Srf_ydMdL0?start=174&1189 9Srf_ydMdL0?start=1189&1675 9Srf_ydMdL0?start=1675&2064 9Srf_ydMdL0?start=2064&6348 ~~~ ## HEANet Hosted Videos If you require an alternative to Youtube, you can use the HEANet service. | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Heanet Video](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-03-media/unit-2-heanet) | [HeaNet video example](https://tutors.dev/topic/reference-course/topic-03-media)) | Videos can be uploaded here: - If you wish to use this service, then your videoid file should look like this: ~~~bash heanet=7e4f1e9afedb40d5996d0703702eaaa4 ~~~ The id will be generated when you upload the video to the HEAnet media service. # Podcasts in Labs & Notes There is a separate [Podcast learning object](/note/tutors-reference-manual/unit-2-panels-and-videos/note-a-resources#podcast) if you would like a standalone player card on a course. If you wish to embed a podscast player in a Note or Lab, then use the podcast custom element: ![](img/podcast-1.png) Currently supports the Spotify player, which requires the spotify episode id. You can identify this id by locating the podcast on Spotify and select "Share->Copy link to episode". ### Note : Icons *How to include Icons as card images* --- If no image file is found in a resource, then Tutors will look to display an SVG Icon instead. This Icon is drawn from the Iconify collection: - | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Icon based cards](https://tutors.dev/topic/reference-course/topic-09-svg) | [Iconify](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-09-svg) | You can search for an icon in that collection, locate the reference and include this + a colour in a [FrontMatter](https://docs.zettlr.com/en/core/yaml-frontmatter/) section for the Learning Resource. For example: ~~~markdown --- icon: type: vscode-icons:file-type-pdf2 --- ~~~ The above icon is drawn from this resource: - For monochrome icons, you can also specify the icon colour: ~~~markdown --- icon: type: bi:filetype-pptx color: green --- ~~~ ## Unit : Advanced ### Note : Latex *How to include Latex notation in labs and notes* --- Notes and Books can have Latex content, implemented using the [Katex](https://katex.org/) component. | Example Resource | Display | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [Latex](https://github.com/tutors-sdk/tutors-reference-course/blob/main/topic-01-typical/unit-1/book-a/06.06.md) | [Latex Example](https://tutors.dev/lab/reference-course/topic-01-typical/unit-1/book-a/06) | You can express Latex content between "$" symbols. For example: ~~~latex $ x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a} $ ~~~ Will render as: $ x=\frac{ -b\pm\sqrt{ b^2-4ac } } {2a} $ You can also express content inline, so thisL ~~~latex This is an inline example: $c = \pm\sqrt{a^2 + b^2}$ with text before and after ~~~ This will render link this: This is an inline example: $c = \pm\sqrt{a^2 + b^2}$ with text before and after. ### Note : Ordering Resources *How to specify the order in which cards appear* --- ## Ordering Learning Resources For a topic, unit or side resources, the ordering of the cards is as follows: - talk - lab - note - web - github - archive This can be customised via the introduction of [FrontMatter](https://docs.zettlr.com/en/core/yaml-frontmatter/) sections in the corresponding markdown files. | Example Resource | Display | | ---------------- | ------- | | [Ordering](https://github.com/tutors-sdk/tutors-reference-course/tree/main/topic-08-ordering)| [Ordering Example](https://tutors.dev/topic/reference-course/topic-08-ordering) | This should contain an "order" number, which dictates the sequencing for the cards. ~~~yaml --- order: 1 --- ~~~ If the resouce is a Lab, then the first step should include the FrontMatter/order paramater. ### Note : Tutors Lite *The TutorsLite alternative* --- [[toc]] --- # 1. What is Tutors Lite? As well as rendering core Tutors course content, the default tutors experience encompasses: - Authentication - Tutors Time - Tutors Live - Course Themes - Code Themes - Alternative card styles - Calendar All of the above are delivered via the Tutors Reader application. This is a full stack web application hosted at https://tutors.dev. A course must be published on Netlify for the Tutors Reader to be able to read and render it. Tutors Lite is a lightweight alternative which does not require Tutors Reader. This means a course can be loaded locally (before publication) and can be deployed on any web server. The format of the course 'source' is identical, although some aspects will be ignored (auth, calendar). The generated course web will not have any of the features listed above - but it will match the overall learning experience for the core course content. # 2. Why would I use TutorsLite? - To have a local browsable version of a course before running a full publication cycle. The format will more or less match the full Tutors UX. - Speed: the lite version will be significantly faster, as no web application is required - Independence: your course does not depend on the reader and the associated services the Tutors Reader in turn depends on (e.g. DNS, Hosting, Database, communication infrastructure etc.) - Choose your own host. Publication to GitHub Pages is discussed below, but any provider will do (including Netlify) - Course archiving: you can zip up and perhaps distribute to students a 'frozen' copy or a course at the conclusion of a semester. - A backup - if there is some issue with Tutors Reader, or if the Tutors Reader application is blocked for some reason. # 3. How do I use Tutors Lite: This is the command to build a TutorsLite version: ~~~bash deno run -A jsr:@tutors/tutors-lite ~~~ This will also generate a folder of content in the course folder - this time in a **html** subfolder. You can open this folder and load the **index.html** therein in a browser (generally just double click). # 4. Any examples I can look at? Here is a the Lite version of a course: - This is the full Tutors experience for the same course: - # 5. How would I publish a TutorsLite version on Netlify? Any hosing provider for simple web sites should do. If you want to try on Netlify, then these are the key settings: ~~~ Build command : deno run -A jsr:@tutors/tutors-lite Publish directory : html ~~~ # 6. How would I publish a TutorsLite version on Github Pages? If you have your course on GitHub - and the course repo is public - you can set up the repo such that any git push will also publish the TutorsLite version as a web site hosted on the [Github Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages) facility on your repo. Here is how to do this. - Enable Gh-pages for the repo: On github.com for your course repo go to Settings->Pages and selct Build & Deployment -> GitHub Actions ![](img/gh-pages.png) - Create a new folder in your repo called `.github/workflows` - In that folder create a file called publish-tutors-lite.yaml containing: ~~~yaml name: Publish and Deploy Tutors Lite Site on: push: jobs: tutors-lite-deploy: runs-on: ubuntu-latest permissions: pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Checkout repository uses: actions/checkout@v4 - name: Setup Deno uses: denoland/setup-deno@v1 with: deno-version: v2.x - name: Build Tutors Lite Site run: deno run -A jsr:@tutors/tutors-lite - name: Configure GitHub Pages uses: actions/configure-pages@v5 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: html name: github-pages-${{ github.run_id }} - name: Deploy Site to GitHub Pages id: deployment uses: actions/deploy-pages@v4 with: artifact_name: github-pages-${{ github.run_id }} ~~~ - Commit and push the `.github/workflows/publish-tutors-lite.yaml` file above. - On GitHub navigate to the `Actions` tab for your repo: ![](img/workflow-1.png) This lists all commits (statrting from then the yml file was committed). You can examine the output of the task: ![](img/workflow-2.png) Which should show the url of the deployed TutorsLite course. You can also inspect the task output in more detail: ![](img/workflow-3.png) ### Note : Tutors Time Exploring Tutors interaction patterns --- With authentication enabled, the user will be required to authenticate using a pre-existing GitHub account. Tutors will then record how much time each view is active (in minutes) and send this to the TutorsTime data store. This can be viewed via the TutorsTime feature on the course Navigator. This data is available to student + the instructor of the course, but not to other students. No other data is gathered, nor is this data transmitted anywhere other than the TutorsTime data store. This data is gathered largely for course management purposes. For example, time spent on lab steps is valuable intelligence that will feed into the design of the labs. Also, averaged lab times across the course can help course authors better understand course load and relative load across modules. The numbers presented are an estimate of the number of minutes the lab is visible in the browser - excluding when the browser is minimised or in an inactive tab. ## TutorsLive A companion to Tutors Time, this feature lists the students currently interacting with a module. The purpose of the feature is to simulate the presence dimension of a typical timetabled 'practical' in traditional module delivery. In a practical session, students often work on their lab materials in a single physical space. They may work alone or collaborate - but they are at least aware of others in the room, and might have a general idea as to what fellow students are working on. This experience can generate a sense of community and collective effort. It can also offer opportunities for mutual learning. Starting from from when you visit the course web - Tutors Live will list students who are interacting with the course - at topic level or below. It will list the topic name + the lab if interacting with a lab. The display starts when you visit course web. No interaction data is shown prior to this time. If no activity is detected for 5 minutes, then the entry for the student is removed from the display. There is a checkbox to opt out - in this case you will not appear in the live display until you check it again. This will not affect other metrics. ## Unit : Reference ### Note : Tutors Values *The values of the Tutors Open Source Project* --- *Tutors: An Open Learning Web Toolkit* A collection of open source components & services supporting the creation of transformative learning experiences using open web standards. Tutors supports three complimentary perspectives: - The ***Learner Experience*** prioritises web interactions that are **engaging**, **contextual**, **linkable**, **searchable**, **accessible** and **responsive**. In addition the experience should foster a sense of **community** and **connection** among fellow learners. - The ***Educator Experience*** prioritises the creation of a **guided paths** through a curriculum via the creation of learning materials that are **autonomous**, **structurally aligned**, **composable**, **auditable**, **extensible**, **versioned** and **independent**. - The ***Developer Experience*** prioritises the specification and implementation of **robust**, **well documented**, **loosely coupled components & services**, integrated into a **coherent toolkit** open to contributions from **diverse skill sets**. # Learner Experience > The ***Learner Experience*** prioritises web interactions that are **engaging**, **contextual**, **linkable**, **searchable**, **accessible** and **responsive**. In addition the experience should foster a sense of **community** and **connection** among fellow learners. **Engaging**: The web experience should be visual, stimulating and provoke a sense of exploration and investigation. **Contextual**: Suitable navigation features should enable the Learner to visually explore learning objects in the appropriate context, easily reach related material, including parent/child, sibling, and schedule oriented indicators + selected external services. Transitions & Animations should subtly enhance this contextual awareness. **Linkable**: All meaningful learning objects should be capable of being bookmarked. If these links are sent to another browser session the link should enable the complete learning context to be rebuilt in that session. **Searchable**: A tutors course should support full text search + filter/summary views. **Accessible**: Learning resources should support best in class accessibility, including dyslexia, colour blindness and visual impairment. **Responsive**: Learning material should adapt adequately from the full range of device characteristics and orientations from mobile phones to widescreen workstations. **Community**: A Learner should be able to avail of a community of learners, optionally sharing their presence and activity stream as appropriate. **Connection**: A Learner should be able to reach out to fellow learners within the current context, initiating chat, content sharing or other meaningful exchange. # Educator Experience > The ***Educator Experience*** prioritises the creation of a **guided paths** through a curriculum via the creation of learning materials that are **structurally aligned**, **composable**, **auditable**, **extensible**, **versioned**, **independent** & **autonomous**. **Guided Paths**: It should be possible to create learning paths adhering to a curriculum but adaptable to individual learning styles and patterns. **Structurally Aligned**: The structure of learning content should mirror the structure of the guided learning paths. **Composable**: It should straightforward to construct courses from elements of other courses and combine courses into programmes and other configurations. **Auditable** It should be possible to ascertain whether students have engaged with specific learning resources. **Extensible**: It should be possible to introduce new, parallel learning services within a family of tutors tools. **Versioned**: It should be possible to place a course under git based version control, supporting rollback, branch previews and other version management conveniences. **Independent**: It should be possible for an educator to migrate from the tutors to other comparable systems within the static site generator category of tools. **Autonomous**: Learning resources should be capable of being self hosted, independent of any tutors cloud services. # Developer Experience > The ***Developer Experience*** prioritises the specification and implementation of **robust**, **well documented**, **loosely coupled components & services**, integrated into a **coherent toolkit** open to contributions from **diverse skill sets**. **Robust**: Unit & acceptance tests should a key part of each component **Well Documented**: Each component should be adequately documented, sufficient to enable quality improvements and other enhancements **Loosely Coupled Components**: The project should, as far as possible, consist of a set of reusable components, assembled into a range of applications and services. These components should strive to be independent , testable and shareable. **Loosely Coupled Services**: Shares services like authentication, data store, presence, analytics should be shared across the tutors components and potentially decoupled, removed, or substituted as appropriate. **Coherent Toolkit**: The role of each Component/Service should be clear and potentially substitutable by alternatives fulfilling equivalent roles. **Diverse Skill Sets**: The project should be open to all skill levels, with a welcoming and supportive environment. ### Web : Tutors Source *Source repo for the Tutors Reader* ### Web : Tutors Workshop *A workshop on the Tutors Project* ### Web : Tutors Live *Activity on tutors right now* ### Web : Gallery *A selection of Tutors Courses* ## Side : Reference ### Web : LLM Notebook A Notebook LLM trained on Tutors ### Web : Simple Starter *A simple example starter course* ### Web : Alternative Starter *Example course with alternative layouts & nesting* ### Web : Reference Course *Example Course containing all Tutors learning objects* ### Podcast : Tutors Introduction Notebook LLM generated summary podcast