# About this repository -- by David Bernhard

Some behind-the-scenes information on how this unit page is set up, in case you ever need something similar for a project of your own.

This page is hosted publicly on Github at `cs-uob/COMSM0085` so for example the address [https://github.com/cs-uob/COMSM0085](https://github.com/cs-uob/COMSM0085) (or the ssh equivalent `git@github.com:cs-uob/COMSM0085` that you'll learn about in the unit) will let you clone this repository. Opening the link in a browser will let you browse the repository too, or download a ZIP of the latest version.

[Github pages](https://pages.github.com/) lets you host a website from a git repository. The website for this unit is hosted at [https://cs-uob.github.io/COMSM0085/](https://cs-uob.github.io/COMSM0085/) which is also the link to the unit page that you'll see - Github Pages by default serves the pages under the `USERNAME.github.io` domain. Github pages provides static hosting, so you can put in any combination of HTML/CSS and client-side JS, but not any server-side scripts (e.g. JSP or similar). It also uses the [Jekyll](https://jekyllrb.com/) content management system that turns [markdown](https://www.markdownguide.org/basic-syntax/) into websites. The site is set up to point to the `docs/` folder, so the source for this page for example is [docs/repository.md](https://github.com/cs-uob/COMSM0085/blob/master/docs/repository.md) - that link will show you a Github preview, but clicking "raw" shows you the [source file](https://raw.githubusercontent.com/cs-uob/COMSM0085/master/docs/repository.md). (The blue bar at the top of this unit page is part of a Jekyll template, configured in `docs/assets/css` and `docs/_layouts`.)

Some code that's referenced in the workshops is stored in the `code/` folder of the repository, and linked to from the relevant exercises. These exercises will tell you to clone the repository, then switch to e.g. `code/server01/` to work with the example application there.

The workshops themselves are created with a different content management system called [mdbook](https://rust-lang.github.io/mdBook/) which is written in Rust, but available as an executable so I don't have to build it myself. Like Jekyll, it turns markdown pages into websites but it has a few extra features like the overview bar on the left, different styles that you can switch with a button (if you prefer "dark mode" for example) and it lets me run the markdown through a custom preprocessor that I wrote myself in python to handle custom tags, for example for the "advanced" blocks that you'll see on some pages. The files are organised like this:

  - The sources are in `exercises/part1` (resp. `part2`) in the repository. Since this is not under `docs/`, Github Pages doesn't touch it.
  - Running `mdbook build` in that folder (assuming the tool is installed) compiles the files to a subfolder `book/`. You won't see this in the repository because it's excluded with the `.gitignore` file.
  - `book.toml` is the `mdbook` configuration file which among other things runs `preprocessor.py` (assuming python 3 is installed). The point of this is that I can make custom blocks e.g. `|||advanced ... |||` which becomes a `<div class="advanced container">` to which I can apply custom styling (at the end of `theme/css/general.css`).
  - The `build.bat` in that folder then copies the compiled files to `docs/exercises/part1` which is under `docs/`, but that folder contains HTML/CSS files not markdown ones so Github Pages just serves them as is. That is how the URL [https://cs-uob.github.io/COMSM0085/exercises/part1/](https://cs-uob.github.io/COMSM0085/exercises/part1/) works.

This workflow means that whenever I make a change to the exercises, I have to remember to rebuild the "book" and commit the resulting files in `docs/` to Github so that you can see the update; it's not perfect but it's good enough for what I need and it means that I can add custom bits to the markdown sources, for example if I want to add `quiz` or `security` or other special blocks in future years.

If you want to use a copy of the unit exercises pages on your own computer, for example when you don't have an internet connection, you can just open the copy in `docs/exercises/part1` starting with the file `index.html`. You just need a browser to view it, no extra markdown tools.

The things not hosted on Github are the lecture videos and their slides, for bandwidth reasons. The videos are hosted on Microsoft Streams (which is licensed by the university). You will need your university single sign-on to watch the videos, but if you click a video link when you're not logged in you should be redirected to a log-in page rather than just hitting an error.