tutors-sdk/tutors

The core Tutors Reader application.

Tutors: An Open Learning Web Toolkit

Website | Documentation

Table of Contents

• What is Tutors
• Getting Started
• Requesting Features
• Reporting Bugs
• Setting Up a Tutors Development Environment
• Example Tutors Courses
• Tutors Project Repos
• Contributing

What is Tutors

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 into a Tutors course

• Reader: presents a Tutors course as an intuitive, discoverable and attractive Web experience

This repo is the Tutors Reader. A companion repo:

• https://github.com/tutors-sdk/tutors-apps

...host the generators + support tools. These components are developed in the open by an active and friendly community, based on a simple set of values.

Getting Started

The first step might be to become familiar with the course structure by browsing a sample course, and then scan the reference manual. The manual will guide you through the process creating and publishing your own course (perhaps a copy of a sample). Thereafter you could scan the Gallery of existing courses to get an idea as to how Tutors is used in practice.

Consider setting up your own development version of tutors for experimentation.

Reporting Bugs

We are delighted to get bug reports. If you encounter a bug, please open a Tutors Issue with a description of the problem. Include information about the environment where the bug occurred, steps to reproduce it, and any relevant screenshots or error messages. Label the issue 'fix'. Perhaps do a quick scan to see if the bug has been reported - if so you might comment / react to the existing error (use filtering to see only 'fix labeled issues).

Requesting Features

If you have an idea for a new feature or enhancement, feel free to open a Tutors Issue. Describe the proposed feature, its benefits, and any other relevant details. Label the new issue feature. Perhaps do a quick scan to see if the feature has already been proposed and consider commenting / reacting to the feature instead of creating a new one (use filtering to see only 'feature labeled issues).

Setting up a tutors Development Environment

Make sure you have Node 18 + installed, and start by cloning this repo:

git clone https://github.com/tutors-sdk/tutors.git

Open a shell and change into the project folder and run npm install...

cd tutors
npm install

Then copy the file .env.example to .env

Now to start the app you can run this command from the root:

npm run dev

This should launch the application:

  VITE v5.0.12  ready in 1069 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Now the app is up and running and you can browse to it by opening the local location in your browser.

The Tutors reader relies on a segment of the url to locate the course to display. Any of the samples below can be 'read' with an appropriate url segments appended to the local url you now have running. So for instance:

• https://tutors.dev/course/reference-course

... can be loaded locally by:

• http://localhost:3000/course/reference-course

(Note the port number 3000 may vary - see the launch console)

The 'source' for the above course is here:

• https://github.com/tutors-sdk/tutors-reference-course

You could try any of the other sample courses above. For example this course:

• https://tutors.dev/course/full-stack-web-dev-oth-2022

can be opened by this local reader like this:

• https://localhost:3000/course/full-stack-web-dev-oth-2022

Tutors Project Repos

There are 4 key tutors repos:

• Tutors: The course reader application. This is a SvelteKit application, written in TypeScript with a user experience implemented using Tailwind & Skeleton.
• Tutors Apps: A monorepo encapsulating the generators, tests + support tools and applications. It is written in TypeScript.
• Tutors Reference Manual: The manual is itself a tutors course, and is largely written in Markdown.
• Tutors Reference Course: A Tutors course to included all tutors learning objects and structures.

Example Tutors Courses

The reference course might be a place to start:

• Reference Course

You can clone and rebuild this course following these instructions.

This is an example of an open source course:

• Full Stack Development

This is a selected Course Gallery:

• Gallery of Tutors Courses

Some courses of interest:

• Higher Diploma in Computer Science Portal
• Full Stack Development
• Data Analytics
• Reference Course
• Higher Diploma in Computer Science at SETU: 2020-2022
• Classic Design Patterns
• Agile Software Development
• Technologische Fähigkeiten

Note: Some courses will request you authenticate via github for access.

Contributing

We welcome feature requests & bug reports! If you would like to try your hand at tackling an issue - your own or one off the shelf, then here is how it might work:

1. Fork the tutors repository
2. Set up a local build
3. Create a new branch for your selected issue (feature or fix).
4. Make your changes, and verify that feature behaves as expected in your local build
5. Commit your changes, perhpas consider following these guideline for commit messages
6. Push your changes to your fork
7. Submit a pull request to tutors.

All contributors are eligible to earn a Holopin - a digital badge that represents your contributions to the project. These badges evolve the more contributions you make to the project!

Every time you open a PR that is accepted, you will be assigned holobytes. Collect these holobytes to see your owl evolve!

License

tutors's Issues

Cli:fix: correctly interpret course icon defined in properties.yaml

Update tutors-home website (tutors.dev)

Update the sections of the tutors-home website.

• Contributors section (auto generate? not sure)
• Design page - link components card to vitebook
• Changelog - Automatically get changelog from repo?

Implement common tailwind config in tutors-time-reader

Implement the common tailwind config from tutors-configs in the tutors-time-reader package.

You can see the implementation of this in action on the tutors-course-reader package.

implement eslint in course-reader packages

implement ESLint in the tutors-course-reader & tutors-reader-lib packages

UI: Primary Navigation Bar Components

Build out the components for the primary nav bar. This is to include:

• Nav Title
• Nav Button
• Nav User

App: Pass sveltekit fetch from load function to course service

For best results, use the fetch that is passed to your load function: https://kit.svelte.dev/docs/load#making-fetch-requests

tutors-publish-html website build error on note

Building courses with #388 [email protected] and Node 20.5.0 may fail upon reaching a note card. I haven't been able to identify what makes these notes special in order to trigger this issue since there are notes which don't trigger it. This issue is not present in [email protected].

I have submitted an example of a course with a note that triggers the aforementioned issue at:
https://github.com/tc-565/tutors-publish-html-regression-testing

I attach the error message too:

% tutors-html
Static course generator tutors-publish-html: 3.0.1 (tutors-gen-lib: 1.0.0)
: Regression testing :  Reference Course
--: unit-01-local : Avanzado: Desarrollo local de cursos
----: note-01-gh-desktop :  Uso de GitHub Desktop
----: note-02-compilar :  Compilación del sitio
cd: no such file or directory: unit-01-local
mkdir: no such file or directory: /Users/USERNAME/Documents/Regression testing/html/unit-01-local
node:internal/fs/utils:351
    throw err;
    ^

Error: ENOENT: no such file or directory, open '/Users/USERNAME/Documents/Regression testing/html/unit-01-local/note-01-gh-desktop/index.html'
    at Object.openSync (node:fs:602:3)
    at Object.writeFileSync (node:fs:2334:35)
    at writeFile (/opt/homebrew/lib/node_modules/tutors-publish-html/node_modules/tutors-gen-lib/src/utils/utils.js:34:15)
    at publishTemplate (/opt/homebrew/lib/node_modules/tutors-publish-html/src/lo/html-emitter.js:32:27)
    at Object.emitNote (/opt/homebrew/lib/node_modules/tutors-publish-html/src/lo/html-emitter.js:38:9)
    at Object.emitLoPage (/opt/homebrew/lib/node_modules/tutors-publish-html/src/lo/html-emitter.js:49:18)
    at Object.emitLo (/opt/homebrew/lib/node_modules/tutors-publish-html/src/lo/html-emitter.js:63:18)
    at /opt/homebrew/lib/node_modules/tutors-publish-html/src/lo/html-emitter.js:71:18
    at Array.forEach (<anonymous>)
    at Object.emitTopic (/opt/homebrew/lib/node_modules/tutors-publish-html/src/lo/html-emitter.js:70:103) {
  errno: -2,
  syscall: 'open',
  code: 'ENOENT',
  path: '/Users/USERNAME/Documents/Regression testing/html/unit-01-local/note-01-gh-desktop/index.html'
}

App: move live route from course to time group

App: Update homepage of tutors.dev with new info and links

Centralise tsconfig for generators

tutors-html readme

Readme writeup for tutors-html package

Custom domain on Auth0 login

Allow for custom domain use on Auth0 login to unify the Tutors experience.

Implement ESLint in sites/tutors-time-reader

Implement ESLint in the sites/tutors-course-reader package

tutors-publish-html: link in card description isn't rendered correctly

Building a course with [email protected], if the description of a card contains a link formatted in markdown, such as [text](https://github.com/) then the card description is shown as such, instead of rendering text.

update tutors-time-reader design

Update the design of the tutors-time-reader package to align with tutors-course-reader - current components can be found at /sites/tutors-course-reader/src/tailwind.css

Implement common tailwind config in tutors-home

Implement the common tailwind config from tutors-configs in the tutors-home package.

You can see the implementation of this in action on the tutors-course-reader package.

Notes won't open in a tutors-html generated site if placed as topic>unit>note

I have run into certain problems displaying notes inside units using [email protected].

If notes are placed inside a topic they work as intended, the title and subtitle show correctly, and the content displays when opened. For units I have witnessed an anomalous behaviour depending on the location of the unit directory is inside a topic.

If a note is placed under home>topic>unit, the title and subtitle show correctly, but attempting to open the note won't open the note.

If a note is placed under home>unit, no problems arise.

Implement Storybook for tutors-ui

Implement Storybook on tutors-ui - use sb@next (v7 beta) for vite/svelte support OOTB with a view to move to v7 once in production

Convert Tutors Course Reader to a PWA

Enable installations of Tutors on devices, with the homepage as the course it is being installed from.

May be a larger job - to scope out.

tutors-publish-html won't display certain cards on home

I have been testing #388 [email protected], and I have noticed that the following cards won't display in the root directory of a course when building: github, web, archive and paneltalk (the one that doesn't reside on an unit, course/paneltalk).

These would show when building with [email protected], so I suspect this could be a regression.

Tutors Time - Hide Names

Hide names and ID

Why?
GDPR

Cli: fix build path issues + remove generated files from git

Card Videos Play the video immediately

Why?
Currently requires 2 clicks.
one to to refresh the page to a panel video
another to start the video playing

Simplify
to combine both
reducing number of user clicks

Docs: Update readme to reflect new project structure

App: address typescript type errors

Either fix the type error, or disable the type check (single line only)

Create common eslint config

Create a common eslint config in components/tutors-configs

See implementation of tailwind config for how this should be implemented

Multiple login types with Auth0 & account linking

Allow for multiple login types with auth0 (username&password, github, slack) and set up account linking.

tutors-publish-html can't create table of contents in note

Regression in tutors-publish-html, tested in version 3.0.2. If a markdown note includes a line with the contents [toc], a table of contents doesn't generate as it previously did in tutors-html.

[toc]

Create Astro generator

Few upper bar icons in tutors-html

As of [email protected], the only icons that can be used on the upper left bar are Slack, YouTube and Moodle, as seen in
https://github.com/tutors-sdk/tutors/blob/f73645f41d5758db8bb10830a92e6c7a5bb774bb/cli/tutors-html/src/views/components/navigators/support/Companions.njk

I unsuccessfully tried to use other icons such as the ones listed in tutors-sdk/tutors-template/properties.yaml. Neither the ones for Teams or Piazza display on the official deployment of the tutors-template website at https://tutors-sdk.github.io/tutors-template/, despite being listed on the aforementioned file.

As workaround, is there a way to use custom svg icons in tutors-html for this particular situation? Are there plans for the icon selection of tutors-html to be expanded?

Build tutors-ui components

Break down the components used in the tutors reader and build ui components.

The ui is built using TailwindCSS & DaisyUI as a base.

UI: Build out a base for a component library in $lib/components

As title, build out a base for a component library in $lib/components for the app. These components are to live separately to the learning object model, with specific data to be passed to them, thus ensuring they are reusable in any form.

This means building out a structure for the UI components to live in, an index to export and a visual tool to view the components (ie storybook).

Centralise tailwindcss config in readers

create a base tailwind.config.js in the tutors-configs package and import this into the readers / tutors-home packages

Cli: refactor tutors-gen-lib into tutors-lib & tutors-gen-lib

• tutor-lib to be browser compatible and so available in app.
• tutors-gen-lib to contain reusable aspects for use in tutors-publish & tutors-publish-html

Update skeleton to v1.0.0

• Update all packages using skeleton to 1.0.0 stable
• Migrate (depracated) menus to popups
• Update lightswitch utility used
• fix theme builder
• fix search bar design
• check all other functions work as normal

App: Refactor $lib folder

Refactor $lib folder to contain 2 sub-folders:

• UI
• Services

UI will contain all svelte UI elements, services will contain all typescript elements.

Build electron app for tutors-course-reader

Cypress Tests: Info bar & TOC & Companions & Walls

A few items we can start to consider to test:

• Info bar (top left)
• TOC (top right)
• Companions (noodle etc..)
• Walls (the filters - for all labs, lectures etc..

**These are the links in the nav bar to Moodle, YouTube, slack etc….

You will find them at the end of tutors.json - a “companions” property**

App: Integrate cypress tests into Netlify pipeline for PRs

Simplify tutors-ui components & create storybook stories

Now that we have storybook set up and configured, we need to simplify the component in the tutors-ui package (ie make them more generic) and create stories for the components.

This package follows the atomic design methodology, so best to work on atoms first, before moving on to Molecules & Organisms.

storybook production deploy: https://ui.tutors.dev/

Instructions to run SB locally:

npm i

cd packages/tutors-ui

npm run storybook

Readme Typos

Fix typos in readme

tutors-home readme

Update the readme for the tutors-home package (sites/tutors-home).

Cypress Tests: adapt existing test framework to test tutors-publish-html

Cypress Tests currently exercise the 'dynamic' site as generate by tutors-publish.

• Dynamic Reference Course

The static publisher - generated by tutors-publish-html - is approaching feature parity (for course content only)

• Static Reference Course

Documenton on using tutors-publish-html is here

Rebuild tutors-ui to not use lo's

Rebuild tutors-ui so the components do not use learning objects, and explicit data is passed to the component.

These components will be opinionated to suit the style of Tutors and can be reused then across all Tutors applications.

Each component must be broken up into smaller components and storybook stories created as such to display them. Assembled components must have all variations and code snippets on how to use in the story.

All work for this is being completed in the attached development branch ( feat/tutors-ui )

Add the feature of cliping code in markdown

HI, I am an international student in SETU, and my major is software engineering.
Really appreciate this project. Here is a suggestion of adding the feature of cliping code in markdown in tutor-reader.

I found that in packages/tutors-reader-lib/src/utils/markdown-utils.ts, showdown is used to convert markdown to html. Here is a simple plugin to implement the function of copying code in markdown: showdown-copy-code.

Hope this suggestion helpful.

Kind Regards.

App: Upgrade to svelte 4 + Skeleton v2 (When released)

tutors-json readme

readme writeup for tutors-json package

GitHub action for tutors-html static website deployment

Hi. I am attempting to make a GitHub action in order to automatically build and deploy a tutors website with tutors-html each time a change is pushed. For testing, I forked tutors-template.

I am able to build the website with Node v19.6.1 from my computer with [email protected], but I am facing trouble when doing so with one of GitHub's runners, for which I have tried both Node v18.4.1 and v19.6.1. An error is thrown after a Template render error message, and the site doesn't get to build. I am not able to figure out why this different behaviour presents itself.

The deploy action can be consulted at my fork, as well as the logs of the run.

Kudos for this amazing project!

/opt/hostedtoolcache/node/19.6.1/×64/lib/node_modules/tutors-html/node_modules/nunjucks/src/environment.js:575
        throw err;
  Template render error: (/opt/hostedtoolcache/node/19.6.1/×64/lib/node_modules/tutors-html/src/views/Topic.njk)
  Template render error: (/opt/hostedtoolcache/node/19.6.1/x64/lib/node_modules/tutors-html/src/views/Topic.njk)
  Template render error: (/opt/hostedtoolcache/node/19.6.1/x64/lib/node_modules/tutors-html/src/views/Topic.njk)
  Error: template not found: components/cards/card.njk
    at Object._prettifyError (/opt/hostedtoolcache/node/19.6.1/x64/lib/node_modules/tutors-html/node_modules/nunjucks/src/lib.js:36:11)
    at /opt/hostedtoolcache/node/19.6.1/x64/lib/node_modules/tutors-html/node_modules/nunjucks/src/environment.js:563:19 at Template.root [as rootRenderFunc] (eval at _compile (/opt/hostedtoolcache/node/19.6.1/×64/1ib/node_modules/tutors-
html/node_modules/nunjucks/src/environment.js:633:18),<anonymous>:71:3)
    at Template. render (/opt/hostedtoolcache/node/19.6.1/×64/1ib/node_modules/tutors-html/node_modulles/nunjucks/src/environment.js:552:10)
    at /opt/hostedtoolcache/node/19.6.1/x64/lib/node _modules/tutors-htm1/node_modules/nunjucks/src/environment.js:366:27 at createTemplate(/opt/hostedtoolcache/node/19.6.1/×64/1ib/node_modules/tutors-html/node_modules/nunjucks/src/environment.js:315:9)
    at handle (/opt/hostedtoolcache/node/19.6.1/x64/1ib/node_modules/tutors-html/node_modules/nunjucks/src/environment.js:327:11)
    at /opt/hostedtoolcache/node/19.6.1/x64/lib/node_modules/tutors-html/node_modules/nunjucks/src/environment.js:339:9 at next (/opt/hostedtoolcache/node/19.6.1/×64/lib/node_modules/tutors-html/node_modules/nunjucks/src/lib.js:328:7)
    at Object.asyncIter/opt/hostedtoolcache/node/19.6.1/x64/lib/node_modules/tutors-html/node_modules/nunjucks/src/lib.js:334:3)
Node.js v19.6.1

Implement cypress testing

Implement cypress in the tutors-course-reader

upgrade cli design for tutors-json

upgrade cli design for tutors-json package (ie. loading bars, prompts, menus as required).