Make a TeachNet Page

.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+  "name": "Teach-Net (Jekyll)",
+  "image": "mcr.microsoft.com/devcontainers/jekyll:2.2.1-3.3-bookworm",
+
+  "features": {},
+
+  // 4000 = the local website, 35729 = live-reload when you save a file.
+  "forwardPorts": [4000, 35729],
+  "portsAttributes": {
+    "4000": { "label": "Website preview", "onAutoForward": "openPreview" }
+  },
+
+  "postCreateCommand": "sh .devcontainer/post-create.sh",
+
+  "customizations": {
+    "codespaces": {
+      "openFiles": ["README.md", "index.md"]
+    },
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "ms-ruby.ruby",
+        "deque-systems.vscode-axe-linter"
+      ]
+    }
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Runs once when the dev container (or GitHub Codespace) is first created.
+# It installs the site's dependencies and starts a live preview.
+
+set -e
+
+# Install the Ruby gems listed in the Gemfile.
+if [ -f Gemfile ]; then
+  bundle install
+fi
+
+# Start the local website. It rebuilds automatically when you save a file.
+# Open the forwarded "Website preview" port to see it.
+bundle exec jekyll serve --livereload --force-polling --host 0.0.0.0

.github/workflows/accessibility.yml

@@ -0,0 +1,31 @@
+# Runs the accessibility checks (spec/) on every push and pull request.
+name: Accessibility tests
+
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+jobs:
+  a11y:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Run accessibility tests
+        run: bundle exec rspec
+      - name: Summary
+        if: failure()
+        run: ruby spec/support/spec_summary.rb
+      - name: Keep screenshots from failed tests
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: screenshots
+          path: ${{ github.workspace }}/tmp/capybara
+          if-no-files-found: ignore
+          retention-days: 7

.github/workflows/jekyll.yml

@@ -0,0 +1,52 @@
+# Builds the Jekyll site and publishes it to GitHub Pages on every push to main.
+#
+# One-time setup in the repository: go to Settings -> Pages and set
+# "Build and deployment" -> Source to "GitHub Actions".
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+# Permissions needed to publish to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one deployment at a time.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,16 @@
+# Jekyll build output
+_site/
+.jekyll-cache/
+.jekyll-metadata
+.sass-cache/
+
+# Test output and screenshots
+tmp/
+
+# Ruby dependencies installed locally
+vendor/
+.bundle/
+
+# Editor / OS noise
+.DS_Store
+*.swp

.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--format json --out tmp/rspec_output.json

.ruby-version

@@ -0,0 +1 @@
+3.3.9

Gemfile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Use the Ruby version pinned in .ruby-version.
+ruby file: ".ruby-version"
+
+# Gems used to build the website.
+gem "jekyll", "~> 4.3"
+gem "kramdown-parser-gfm"
+gem "webrick"
+
+# Jekyll plugins.
+group :jekyll_plugins do
+  gem "jekyll-sitemap"
+end
+
+# Tools used to run the accessibility tests. These are not needed just to edit
+# the site, only to run `bundle exec rspec` locally or in CI.
+group :development, :test do
+  gem "axe-core-capybara"
+  gem "axe-core-rspec"
+  gem "capybara"
+  gem "capybara-screenshot"
+  gem "rack"
+  gem "rackup"
+  gem "rspec"
+  gem "selenium-webdriver"
+end

README.md

@@ -0,0 +1,134 @@
+# Teach-Net website
+
+This is the website for **Teach-Net**, the moderated email forum for UC Berkeley
+faculty and staff. It is a small [Jekyll](https://jekyllrb.com/) site that is
+published with **GitHub Pages**, and it follows UC Berkeley's brand colours and
+fonts.
+
+You do **not** need to be a programmer to update this site. Most changes are as
+simple as editing a text file and saving it.
+
+---
+
+## What is in this project
+
+The files you are most likely to touch are written in **Markdown** — a simple way
+to write text with headings, links, and lists. The two pages are:
+
+| File           | What it is                                    |
+| -------------- | --------------------------------------------- |
+| `index.md`     | The main Teach-Net page (the home page)       |
+| `resources.md` | The "Teaching resources" page                 |
+
+A few other files control how the site looks and works. You usually will not
+need to change them:
+
+| File / folder          | What it does                                             |
+| ---------------------- | ------------------------------------------------------- |
+| `_config.yml`          | Site-wide settings (title, description, web address)    |
+| `_data/navigation.yml` | The list of links in the top menu                       |
+| `_layouts/`            | The page frame (header, footer) that wraps each page    |
+| `_includes/`           | Small reusable pieces, like buttons and callout boxes   |
+| `_sass/`               | The colours, fonts, and styling                         |
+
+---
+
+## How to make a simple edit (right in your browser)
+
+You can edit the text without installing anything:
+
+1. On GitHub, open the file you want to change (for example, `index.md`).
+2. Click the **pencil icon** in the top-right to edit it.
+3. Change the text. Markdown basics:
+   - `# Heading` is a big heading, `## Heading` is a smaller one.
+   - `[words you see](https://the-link.com)` makes a link.
+   - A line that starts with `- ` becomes a bullet point.
+   - Leave a blank line between paragraphs.
+4. Scroll down, write a short note about your change, and click **Commit changes**.
+
+Within a minute or two, GitHub will rebuild and publish the site automatically.
+
+### Adding a link to the menu
+
+Open `_data/navigation.yml`, copy one of the existing two-line blocks, and change
+the `title` (the words shown) and the `url` (the page address). Save the file.
+
+---
+
+## Reusable building blocks
+
+Two ready-made pieces can be dropped into any page. You add them with a short tag.
+
+**A button:**
+
+```liquid
+{% include button.html text="Subscribe" url="mailto:teach-net+subscribe@lists.berkeley.edu" %}
+```
+
+**A highlighted callout box** (use `type="note"`, `"tip"`, or `"warning"`):
+
+```liquid
+{% include callout.html type="tip" title="Good to know" content="Your message here." %}
+```
+
+You can see both of these used in `index.md` and `resources.md`.
+
+---
+
+## Previewing the site on your own computer (optional)
+
+If you want to see your changes before publishing, you can run the site locally.
+The easiest way is with the included **dev container**, which sets everything up
+for you:
+
+- **GitHub Codespaces:** click the green **Code** button on GitHub, choose the
+  **Codespaces** tab, and create a codespace. It builds the site and opens a
+  live preview automatically.
+- **VS Code on your computer:** install the
+  [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+  and [Docker](https://www.docker.com/), open this folder, and choose
+  **Reopen in Container** when prompted.
+
+The preview updates each time you save a file.
+
+<details>
+<summary>Running it manually without the dev container</summary>
+
+You will need [Ruby](https://www.ruby-lang.org/) (version 3.3.9, listed in
+`.ruby-version`) and [Bundler](https://bundler.io/). Then:
+
+```sh
+bundle install                # install dependencies (first time only)
+bundle exec jekyll serve      # start the preview at http://localhost:4000
+```
+
+</details>
+
+---
+
+## How the site gets published
+
+When a change is committed to the `main` branch, GitHub automatically rebuilds
+the site and publishes it. This is handled by `.github/workflows/jekyll.yml`.
+
+**One-time setup** (only needed once, by a repository administrator): in the
+repository's **Settings -> Pages**, set **Build and deployment -> Source** to
+**GitHub Actions**.
+
+---
+
+## Accessibility
+
+Accessibility is a requirement, not an afterthought. Every time the site changes,
+an automated check (in `spec/`) runs against each page using the
+[axe accessibility checker](https://github.com/dequelabs/axe-core) to confirm it
+meets the WCAG 2.1 AA / 2.2 standards. These checks are adapted from the
+[berkeley-cdss/berkeley-class-site](https://github.com/berkeley-cdss/berkeley-class-site)
+template. If a change introduces an accessibility problem, the check fails and
+tells you what to fix.
+
+When you add content, please keep it accessible:
+
+- Give every image meaningful **alt text**.
+- Use headings in order (don't skip from `#` to `###`).
+- Write descriptive link text ("the subscribe page"), not "click here".

_config.yml

@@ -0,0 +1,37 @@
+# Site settings — edit the values below to change site-wide text.
+# After editing this file you must stop and restart the local server.
+title: Teach-Net
+tagline: A teaching forum for Berkeley faculty and staff
+description: >-
+  Teach-Net is a moderated email forum open to UC Berkeley faculty and staff to
+  share ideas and resources and communicate about teaching.
+author: UC Berkeley Center for Teaching & Learning
+
+# The web address where the site lives. Update these when you publish.
+# For a GitHub Pages "project" site the URL is https://<user>.github.io and
+# the baseurl is "/<repository-name>". For a custom domain, set baseurl to "".
+url: ""
+baseurl: ""
+
+# Build settings — you normally do not need to change anything below this line.
+markdown: kramdown
+kramdown:
+  input: GFM
+  hard_wrap: false
+
+sass:
+  style: compressed
+
+plugins:
+  - jekyll-sitemap
+
+# Files and folders that should not be copied into the published site.
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md
+  - vendor
+  - spec
+  - .devcontainer
+  - .github
+  - script

_data/navigation.yml

@@ -0,0 +1,7 @@
+# The links shown in the top navigation bar.
+# To add a page to the menu, copy one block and change the title and url.
+# The url should match the page's `permalink` (or its path).
+- title: Teach-Net
+  url: /
+- title: Teaching resources
+  url: /resources/

_includes/button.html

@@ -0,0 +1,12 @@
+{%- comment -%}
+  A prominent link styled as a button.
+
+  Use it inside any Markdown page like this:
+
+    {% include button.html text="Subscribe to Teach-Net" url="mailto:teach-net+subscribe@lists.berkeley.edu" %}
+
+  Options:
+    text - the words shown on the button.
+    url  - where the button links to (a web address or mailto: link).
+{%- endcomment -%}
+<a class="button" href="{{ include.url }}">{{ include.text }}</a>

_includes/callout.html

@@ -0,0 +1,18 @@
+{%- comment -%}
+  A highlighted box for tips, notes, or warnings.
+
+  Use it inside any Markdown page like this:
+
+    {% include callout.html title="Good to know" content="Reply goes to everyone." %}
+
+  Options:
+    title   - optional heading shown in bold at the top of the box.
+    content - the text to show. Plain text or simple Markdown links work.
+    type    - optional style: "note" (default), "tip", or "warning".
+{%- endcomment -%}
+<aside class="callout callout--{{ include.type | default: 'note' }}">
+  {%- if include.title -%}
+    <p class="callout__title">{{ include.title }}</p>
+  {%- endif -%}
+  <div class="callout__body">{{ include.content | markdownify }}</div>
+</aside>