Automated collaborative courseware maintenance and production with ease!
Courseware as Code Action is an intuitive courseware management project for education everywhere. This project allows you to generate a fully functional and deploy-able website by writing only Markdown files!
- What Courseware as Code Actually Means
- Why This Project
- Motivation
- What's Inside?
- Values
- Getting Started
- Become a Sponsor
- Roadmap
- Contributing to This Project
- Contributors
- FAQ
In 2014, the US Army established the Cyber branch and the U.S. Army Cyber School (USACyS). Quickly building USACyS from scratch required building courseware to fill workforce-oriented curricula. They had assigned students and scheduled classes before suitable content was created and needed a rapid solution to create needed content.
Their requirements included the ability to store markup languages and the ability to create, share, review, and manage content approval. GitLab provided this through Git, which allowed them to apply the "everything as code" concept
So, why not apply this elsewhere?
You may be asking "why not just make a guide explaining how to manage courseware as code" and the answer is quite simple: maintaining everything as code requires a full team just to setup and maintain, while many institutes cannot spare this kind of human resources.
So I had the idea of developing a GitHub action with a template repository that anyone can just "Use this template" and voila, you have a fully functioning courseware as code maintenance system.
Of course it doesn't yet solve the problems of static hosting media and other non-markup files, but I wanted to release it at this stage to get feedback and to involve the community from the early start. Can't have a good community-based project without the community! 😉
Disclaimer: The Motivation documentation was written when I was in my third year of University. I'm now a graduate and enrolled in (mandatory 😅) military service.
I'm a student. A tired student. I'm tired of having to deal with outdated knowledge in the courses I'm enrolled in. I'm tired of having no way of contributing to the course I'm taking, nor a choice in how content is presented to me.
This project, despite not providing a complete solution to these problems, remains a positive attempt at providing an easier way for teachers and courseware maintainers to update courseware, and a straight-forward method to build a truly positive community led by students and teachers alike. A step forward towards a dream I have. I got the idea from GitLab's GSoC 2020 project.
- Statically generated HTML lecture pages!
- Markdown + Math (LaTeX) = ❤️
- Add more pages to your website without having to go outside of your Markdown comfort-zone with MDX! 😍
- Tutorials and examples to get started!
- Complete control over site metadata using configuration
cac.config.json. - Complete control over site themes through classless CSS. I built it with the most standard way of doing things in HTML to make this easier.
As the creator of this project I envisioned it how my student self 2 years ago sought. Transparency, humbleness, appreciating collaboration, and support are the pillars of my vision with this project.
- Transparency in admitting your mistakes as a course maintainer and letting the history of your changes be visible to the world.
- Humbleness in accepting that you can make mistakes, and in accepting help and contribution from students who may be decades younger than you and ages less experienced than you.
- Appreciating collaboration in showing how grateful you are that maintainers and students are putting in the effort to improve the courseware, and in providing a healthy environment for collaboration between maintainers and students alike.
- Support in providing the help needed in order for others to contribute comfortably to courses you maintain, and in creating a community of respect. This meant the world to me and I'm sure millions of other students as well.
The project consists of three repositories:
- kl13nt/courseware-as-code-action: the action code itself.
- kl13nt/courseware-as-code-template: the NextJS template used to render the website.
- kl13nt/courseware-as-code-example: An example template repository to bootstrap course repositories from.
This project assumes you have a GitHub account. It's free.
If you're a courseware maintainer or student you're going to interact with the third repo only, which consists of the markdown content itself. Refer to the Usage Guide.
I invest a lot of my personal time and energy to maintain this project (and others!). If you'd like to sponsor me I have a GitHub Sponsors profile up!
- Custom directives for notes and warnings!
- GitHub Flavoured Markdown extensions (Autolink literals, footnotes, strikethrough, tables, tasklists)
- Automatically create embeds from links
- Dynamic collection structure
- Configurable code syntax highlighting language support!
- Custom image sizes!
- Presentations support through Marp/Core
- Student articles and blogs!
- Downloadable PDF lecture and presentation files!
- CMS support!
- Configurable NextJS templates and build pipeline steps!
If you're a developer wishing to extend or contribute to the action you're going to be interacting with the first two, which are the source code that runs the project. Refer to the Developers Guide.
I'm open to all kinds of contributions. If you want to:
🚀 Suggest a feature
🐛 Report an issue
📖 Improve documentation
👩💻 Contribute to the code
You are more than welcome. By contributing to this repository you accept my contribution guidelines.
This project uses the All Contributors bot. All contributors (even on other repositories) will be added to this list.
 Mostafa Elbadri 📖 |
||||||
Add your contributions
|
||||||
Why not use GitHub's Jekyll setup?
Because I wanted this solution to work with other platforms like GitLab, and to have complete control over the build steps. This allows me to swap out NextJS for anything else, configure custom transformations on files before the static generator is ever run, etc.
Why not just a template repo with NextJS and everything else in one repo?
Because I wanted to make the source repo for course content as friendly as possible. I didn't want a student or instructor to be pushed away by a complicated repository with tons of config files and source TypeScript modules.
I also wanted this project to be as customizable as possible. Having the action the way it is allows me to extend it later to allow for custom NextJS templates, a completely different workflow, etc.
This decision allowed me to keep my assumptions slim to none and therefore have an easily customisable solution. This is a raw attempt and is not the best way something like this could be built, but it's a positive step towards my vision.