A static web site generator for producing course web sites from largely markdown content. For example this site here is generated using this tool.
Here is a portfolio of courses:
Here is a course on using tutors:
This course was developed using tutors - the course 'source' is here:
Make sure you have node.js installed.
Normally the LTS version would be the most suitable. You should also have git installed:
On windows, it is often easier to make sure git is integrated into the standard command prompt (an option when installing git on windows).
Once these are installed, enter this command:
npm install tutors -g
This will install the tutors command globally on your workstation. Now, to create a starter template course, enter this command:
tutors new
This will create a new course, populated with some template talks, resources and labs. To build the course, enter the following:
cd tutors-starter-0
tutors
A folder called './public-site' will be generated containing a html site of the course.
The structure of the site follows a set of filename and folder nested conventions to layout topics, labs and talks:
├── course.md
├── credits
├── mbignore
├── topic01
│ ├── topic.md
│ ├── topic.png
│ ├── book-01
│ │ ├── 00.Lab-01.md
│ │ ├── 01.01.md
│ │ ├── 02.02.md
│ │ ├── 03.03.md
│ │ ├── 04.04.md
│ │ ├── 05.Exercises.md
│ │ ├── archives
│ │ │ └── archive.zip
│ │ └── img
│ │ ├── 01.png
│ │ ├── 02.png
│ │ └── 03.png
│ └── talk-01
│ ├── talkname.pdf
│ ├── talkname.md
│ └── talkname.png
├── topic02
│ ├── topic.md
│ ...
Labs are step by step instructions focused on a specific task. Talks are simple pdf presentations. Topics are collections of talks and labs.
To explore some of the options, clone this course first:
git clone https://github.com/wit-tutors/tutors-course-src.git
Change into the folder containing the cloned repo and run tutor:
cd tutors-course-src
tutors
If all goes smoothly, you should see on the console a list of the topics as they are generated for the sample course:
tutors course web generator: 1.4.1
Setup
Talks:
-->Introducing Tutors
-->Tutors Course Structure
Labs:
-->Lab-01-Setup
Composition
Talks:
-->Composing Labs
Labs:
-->Lab-02-Composition
Publishing
Talks:
-->Publishing to Github & Moodle
Labs:
-->Lab-03-Publish
-->Lab-04-Moodle
Portfolios
Talks:
-->Portfolios
Labs:
-->Lab-05-Portfolio
Git
Labs:
-->Lab-06-Git Introduction
-->Lab-07-Branching and Merging
The site will be generated into a folder called public-site in the same folder. If you open index.html in there you should see this site, generated locally:
The tutors command is context sensetive, so will build the complete course if run from the top level, a single topic (with all its talks and labs) if run from within a topic folder, and it will build a single book/lab if run from in a book folder.
##Course Web Source File Structure
In the root folder of a course web, there are a few general files:
├── course.md: high level summary of course
├── credits: list of contributors
├── mbignore: list topics to exclude from the course web
The remainder is the topics folders:
├── topic-01
├── topic-02
├── topic-03
│ etc ...
Each topic consists of:
├── topic-01
│ ├── topic.md: topic title + summary
│ ├── topic.png: Image file for topic
- a list of
talksandlabs:
├── talk-01: the first slide deck
├── talk-02: the second slide deck
├── book-01: the first lab
└── book-02: the second lab
Each talks consists of:
└── talk-XX
├── talkname.pdf: the slide deck
├── talkname.md: a summary of the talk
└── talkname.png: an image to represent the talk on the course web
Each lab contains a series of steps each encoded in markdown. They are numbered as XX.Title.md, where number is typically two digits starting with 00:
└── book-01
├── 00.Lab-01.md
├── 01.01.md
├── 02.02.md
├── 03.03.md
├── 04.04.md
├── 05.Exercises.md
├── archives
│ └── archive.zip
└── img
├── 01.png
├── 02.png
└── 03.png
Each step can use the full range of conventional markdown - including support for github flavoured markdown, fenced code blocks etc. For more details see:
- https://help.github.com/articles/basic-writing-and-formatting-syntax/
- https://help.github.com/articles/organizing-information-with-tables/
Also included is syntax highlighting via bundled highlight.js.
In labs only, subfolders can be included, and they will be published with their contents in full. This can be useful store images in an img folder, archives for download in an archives folder etc...
An example of syntax highlighting:
Images:
Archives:
In addition to a index.html file generated for each topic, two companion files are also generated:
- indexmoodle.html
- ajaxlabel.html
These work in tandem to facilitate content embedding. indexmoodle.html is a paired down version of the topic, with protocol neutral headers and absolute urls to contained talks + labs. ajaxlabel.html is a page fragment which fetches indexmoodle via an ajax call, and renders it in a bootstrap container (for moodle). Typically, this is pasted into a topic resource in moodle, and will serve the topic seamlessly in place.
The above mechanism requires you to provide the url of the hosted course web - as the url is stitched into both files by tutor. You provide this in a file called 'courseurl' in the root folder of the course. See the example above for this procedure in action.
The mbignore file can contain a list of topics that you wish to exclude from the course web. For instance, you may be rolling over a course from a previous run. This enables you to leave the course source intact, and selectively generate topics week by week.
tutors -p
This will generate the course web to a private-site folder as well as public-site. The private version does not process the mbignore file, and will alsways generate the complete course. This can be useful if you are selectivtly publishing a course (to public-site), but want to keep a full version locally.
tutors -s
This will generate the course web to a standalone-site folder as well as public-site. This version includes the full CSS + font assets. These are loaded from CDNs by the public version. This can be useful if you want to distrubute a course to be browsed on a device completely offline.