Skip to content

README.md

Latest commit

 

History

History
134 lines (93 loc) · 5.01 KB

README.md

File metadata and controls

134 lines (93 loc) · 5.01 KB
Raw

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 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:

{% include button.html text="Subscribe" url="mailto:teach-net+subscribe@lists.berkeley.edu" %}

A highlighted callout box (use type="note", "tip", or "warning"):

{% 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 and Docker, open this folder, and choose Reopen in Container when prompted.

The preview updates each time you save a file.

Running it manually without the dev container

You will need Ruby (version 3.3.9, listed in .ruby-version) and Bundler. Then:

bundle install                # install dependencies (first time only)
bundle exec jekyll serve      # start the preview at http://localhost:4000

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 to confirm it meets the WCAG 2.1 AA / 2.2 standards. These checks are adapted from the 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".