Skip to content

Commit

Permalink
Change README
Browse files Browse the repository at this point in the history
  • Loading branch information
CostinCarabas committed Sep 28, 2023
1 parent 814f9f0 commit b7fa380
Show file tree
Hide file tree
Showing 2 changed files with 4 additions and 103 deletions.
105 changes: 3 additions & 102 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,104 +1,5 @@
# OER Template Repository
# Welcome to Blockchain Protocols and Distributed Applications

These are open educational resources ([OER](https://en.wikipedia.org/wiki/Open_educational_resources)).
The repository should be used as a template for the your own classes.
This is a landing page for your course.

## Using the Content

Content is located in the `chapters/` folder.

Each chapter has its own folder.

Lecture content is expected to be presented and followed.
Practice content is expected to be used hands-on individually or as part of team.

## Publishing Workflow

Before building the repository you have to set up the following items:

* Select the GitHub Pages branch by following the [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) tutorial.
You will have to set up the `gh-pages` branch as the publishing branch, if it is not already set up.

In order to publish the content of this repository, we use a GitHub workflow located in `.github/workflows/deployment.yml`.
This workflow will build the site using [Docusaurus](https://docusaurus.io/) and publish the contents to a link similar to `<github_username>.github.io/repository-name`.

## Your first TODOs

To configure this repo for the class for which you intend to develop content, you must make the following changes:

* Change the repository name to match your class name (the default name is `oer-template`).
* In `config.yaml`:
* Change `title` to you class name.
* Change `url` to `<github_usename>.github.io`.
* Change `baseurl` to `/` if the repository is the only one with a GitHub page in your profile.
Otherwise, change it to `/<repository_name>/`.
* Change links to social media sites, if applicable.

## Running Locally

When testing locally, you will have to build the container that will run the builder based on the [`Dockerfile`](Dockerfile).
For this, the simplest way is the use the [`Makefile`](Makefile).
First, edit the `Makefile` and update the `REPO_NAME` variable to the preferred name of your future website.

To generate the web contents locally, run:

```console
make
```

To view the local contents, start a web server by running the command:

```console
make serve
```

As the output of the command tells, point your browser to `http://localhost:8080/$REPO_NAME`, where `$REPO_NAME` is the name of the repository you configured in the [`Makefile`](Makefile)..

## Chapter Contents

### Lecture

Slides are written in [GitHub Markdown](https://guides.github.com/features/mastering-markdown/) and use [reveal-md](https://github.com/webpro/reveal-md) and [reveal.js](https://revealjs.com/) to render HTML output.
Building slides requires [MarkdownPP](https://github.com/amyreese/markdown-pp).
Lecture slides are built from the `slides.mdpp` file using the `make` command (and the `Makefile`).
`slides.mdpp` is a wrapper / index file;
actual content is stored in Markdown format in files in the `slides/` subfolder.
Output is generated in the `_site/` subfolder;
open the `_site/index.html` in a browser to view the slides.

Demos are snippets of code and support files that showcase concepts and ideas related to the lecture.
Demos are located in the `demo/` subfolder.
Each demo has its own folder with source code, `Makefile` or other build files (if required) and support files.

Media files are images and films used in slides for visual support.
Media files are located in the `media/` subfolder.

Quizzes are used in slides to trigger interactivity with participants and as a form of (self-)assessment.
Quizzes are located in the `quiz/` subfolder.
Quiz questions are stored in [Markdown format](https://guides.github.com/features/mastering-markdown/), one file per quiz.

### Practice

Practice content consists of background text, media files, support files and quizzes in the `practice/` subfolder of each chapter.

Background text is located in `chapters/` folder as a series of sections.
Each section consists of general information, tutorial information followed by description of actual work items and a quiz.
Sections are indexed in the `README.md` file.

Support files for work items are stored in the `support/` subfolder.
There is a subfolder for each section.
Each section subfolder contains source code, `Makefile` (or other build files, if required) and support files.

Media files are images and films used in text for visual support.
Media files are located in the `media/` subfolder.

Quizzes are referenced at the end of each section as a form of (self-)assessment.
Quizzes are located in the `quiz/` subfolder.
Quiz questions are stored in [Markdown format](https://guides.github.com/features/mastering-markdown/), one file per quiz.

## Contributing

Contributions are welcome.
See the [contribution guide](CONTRIBUTING.md) on how you could report or fix issues and on how you can improve the content.

Reviewers are requested to follow the [reviewing guide](REVIEWING.md).
Here you will add information about your course that a student might want to know at first glance.
2 changes: 1 addition & 1 deletion config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ embed_reveal:
docusaurus:
plugin: docusaurus
options:
course_name: Template
course_name: Blockchain Protocols and Distributed Applications
sidebar: js
structure:
- Introduction: chapters/README.md
Expand Down

0 comments on commit b7fa380

Please sign in to comment.