Introduction

Founded and maintained by John Mortensen.

Open Coding Society Pages is a project designed to support students in their Computer Science and Software Engineering education. It offers a wide range of resources including tech talks, code examples, and educational blogs.

This GitHub Pages repository can be customized by the blogger to support computer science learning as the student works through the pathways of using Javascript, Python/Flask, Java/Spring. It is intended to support course work for Computer Science and Software Engineering (CSSE), AP Computer Science Principles (APCSP or CSP), and AP Computer Science 'A' (APCSA, or CSA).

"Open Coding Society's instructional model is grounded in Connectivism, recognizing that learning happens through diverse networks of people, platforms, and AI. OCS is refining pages using Merrill's structure, deepening learning through Fink, ensuring access via UDL, and supporting our classroom through Agile and Design Thinking ceremonies, with a touch of Gagné to focus each classroom day. OCS wants to create projects that support learning for today's digital, open, and connected world."

Student Requirements

HS students will have the opportunity to create their personal GitHub Pages repository as they progress through their coursework. In general, students and instructors are expected to use GitHub Pages to build lessons, complete classroom hacks/challenges and perform exploratory work. Exchange of information from this repository to you personal GitHub Pages can be done in many ways...

1. sharing a file, ie: wget "raw-link.ipynb"
2. creating a template from this repository
3. creating a fork to be shared by you and team members
4. etc.

---

History

This project is in its 4th revision (aka 4.0).

The project was initially based on a project called Fastpages. But this project has diverged from those roots into an independent entity, in fact most things (like the build system), are completely different. The decision to separate from Fastpages was influenced by it's deprecation by the authors. It is believed by our community that the authors of Fastpages turned toward the support of Quatro. After that change of direction Fastpages did not align with the Instructors's goals. Thus, Open Coding Society 'Pages' has more of a raw development and classroom blogging purpose. But, we are grateful to Fastpages for their inspiration. But, we are grateful to Fastpages for their inspiration.

License

The Apache license has its roots in Fastpages. Thus, it carries that license forward. However, most of the code is likely unrecognizable from those original roots.

Key Features

• Code Examples: Provides practical coding examples in JavaScript, including a platformer game, and frontend code for user databases using Python and Java backends.
• Educational Blogs: Offers instructional content on various topics such as developer tools setup, deployment on AWS, SQL databases, machine learning, and data structures. It utilizes Jupyter Notebooks for interactive lessons and coding challenges, often referred to as hacks.
• Tools and Integrations: Features GitHub actions for blog publishing, Utterances for blog commenting, local development support via Makefile and scripts, and styling with the Minima Theme and SASS. It also includes an Agile Toolkit to assist in Student Teaching, Assignment Tracking, Live Reviews, and more.
• Keyboard Shortcuts: Pages supports keyboard shortcuts using Alt+Shift+key (e.g. Alt+Shift+C for calendar, Alt+Shift+H for home, Alt+Shift+S for student toolkit). Press Alt+Shift+? to see all shortcuts. These use a non-conflicting modifier so browser defaults (copy, save, print, etc.) are unaffected.

Contributions

• Notable Contributions: Highlights significant contributions to the project, including theme development, search and tagging functionality, GitHub API integration, and the incorporation of GitHub Projects into GitHub pages. Contributors such as Tirth Thakker, Mirza Beg, and Toby Ledder have played crucial roles in these developments.

• Blog Contributions: Often students contribute articles and blogs to this project. Their names are typically listed in the front matter of their contributing post.

---

GitHub Pages setup

The absolutes in setup up...

Activate GitHub Pages Actions: This step involves enabling GitHub Pages Actions for your project. By doing so, your project will be automatically deployed using GitHub Pages Actions, ensuring that your project is always up to date with the latest changes you push to your repository.

• On the GitHub website for the repository go to the menu: Settings -> Pages ->Build
• Under the Deployment location on the page, select "GitHub Actions".

Update _config.yml: You need to modify the _config.yml file to reflect your repository's name. This configuration is crucial because it ensures that your project's styling is correctly applied, making your deployed site look as intended rather than unstyled or broken.

github_repo: "pages" 
baseurl: "/pages"

Set Repository Name in Makefile: Adjust the REPO_NAME variable in your Makefile to match your GitHub repository's name. This action facilitates the automatic updating of posts and notebooks on your local development server, improving the development process.

# Configuration, override port with usage: make PORT=4200
PORT ?= 4500
REPO_NAME ?= pages
LOG_FILE = /tmp/jekyll$(PORT).log

Tool requirements

All GitHub Pages websites are managed on GitHub infrastructure and use GitHub version control. Each time we change files in GitHub it initiates a GitHub Action, a continuous integration and development toolset, that rebuilds and publishes the site with Jekyll.

• GitHub uses Jekyll to transform your markdown and HTML content into static websites and blogs. Jekyll.
• A Linux shell is required to work with this project integration with GitHub Pages, GitHub and VSCode. Ubuntu is the preferred shell, though MacOS shell is supported as well. There will be some key setup scripts that follow in the README.
• Visual Studio Code is the Pages author's preferred code editor and extensible development environment. VSCode has a rich ecosystem of developer extensions that ease working with GitHub Pages, GitHub, and many programming languages. Setting up VSCode and extensions will be elaborated upon in this document.
• An anatomy section in this README will describe GitHub Pages and conventions that are used to organize content and files. This includes file names, key coding files, metadata tagging of blogs, styling tooling for blogs, etc.

Development Environment Setup

Comprehensive start. A topic-by-topic guide to getting this project running is published here.

Quick start. A quick start below is a reminder, but is dependent on your knowledge. Only follow this instruction if you need a refresher. Always default to the comprehensive start if any problem occurs.

Clone Repo

Run these commands to obtain the project, then locate into the project directory with the terminal, install an extensive set of tools, and make.

git clone <this-repo> # git clone https://github.com/open-coding-society/pages.git 
cd <repo-dir>/scripts # cd pages 

Windows WSL and/or Ubuntu or Kali Users

• Execute the script: ./activate_ubuntu.sh or ./activate_kali.sh

macOS Users

• Execute the script: ./activate_macos.sh

Kasm Cloud Desktop Users

• Execute the script: ./activate_github.sh

Run Server on localhost

To preview the project you will need to "make" the project.

Bundle install

The very first time you clone run project you will need to run this Ruby command as the final part of your setup.

bundle install

Jupyter Kernels

To run many of the IPYNB files you will need to install Jupyter kernels for the languages you want to use. Here are the most common and recommended kernels:

Recommended Kernels

• Python3 (ipykernel): For Python code cells and most data science workflows.
• Java (IJava or jbang-ijava): For Java code cells and Java notebooks.
• JavaScript (tslab): For JavaScript code cells and JavaScript notebooks.

Installing tslab

First, Install tslab

npm install -g tslab

Second, confirm it's installed

tslab install --version

Finally, register it to your Jupyter environment

tslab install

Installing IJava or JBang

macOS (Homebrew):

# For Java kernel (IJava)
brew install coursier
cs install --channel=https://github.com/SpencerPark/IJava/releases/latest/download/channel.json ijava
# Or for jbang-ijava
brew install jbang
jbang app install ijava

Ubuntu/Linux (apt):

# For Java kernel (IJava)
sudo apt install coursier
cs install --channel=https://github.com/SpencerPark/IJava/releases/latest/download/channel.json ijava

# Or for jbang-ijava
sudo apt install jbang
# or sudo snap install jbang --classic
jbang app install ijava

List your installed kernels

(venv) username@machine path % jupyter kernelspec list
Available kernels:
  python3        /Users/username/Library/Jupyter/kernels/python3
  java           /Users/username/Library/Jupyter/kernels/java
  jbang-ijava    /Users/username/Library/Jupyter/kernels/jbang-ijava
  jslab          /Users/username/Library/Jupyter/kernels/jslab
  tslab          /Users/username/Library/Jupyter/kernels/tslab

Recommended Kernels

Start the Server

This requires running terminal commands make, make stop, make clean, or make convert to manage the running server. Logging of details will appear in the terminal. A Makefile has been created in the project to support commands and start processes.

Start the server, this is the best choice for initial and ite