CS2103 Website

Live Website (redirected)

Setting up

1. Clone this repo.
2. Run git submodule update --init --recursive to pull the content of the submodule.
3. Install MarkBind

Updating content

1. Checkout the branch of the course e.g., cs2103
2. Update content using MarkBind syntax (How to use MarkBind)
3. markbind serve to start the local server (to preview changes). This command also initiates the live-preview ability i.e., when any changes to the MarkBind code is saved, the site is auto-generated and the Web page (that was opened by the serve command) auto-refreshes to show the new content. This works well for small websites but not so well for this website. Recommended to shutdown the server (Ctrl+C) before doing further edits.
4. When you are happy with the edits, use the markbind deploy to deploy to the GitHub website at the origin repo.
   1. If the deployment failed due to a 'caching' issue, try deleting the cache generated by the previous deploy command (on Windows, the cache can be found in /c/Users/{user-name}/AppData/Roaming/npm/node_modules/markbind-cli/node_modules/gh-pages/.cache)
5. If you need to update contents inside the book folder,
   1. Post an issue in the se-edu/se-book issue tracker to request for the change
   2. After the change has been done, pull the sub-module, and commit the changes to sub-module reference (when you pull a sub-module, Git automatically updates the submodule reference which is seen as a change in the enclosing repo).

      $ cd book
      $ git pull origin master
      $ cd ..
      $ git commit -am "sync with book"
      

   3. Deploy the website to make the updated book content visible to students

Keeping content readable in both light mode and dark mode

This site renders in both light mode and dark mode, and each reader gets whichever one their operating system prefers. There is no "default" theme to design against, so every page has to work in both. The toggle in the navbar lets a reader override their operating system setting, and their choice is remembered.

The rules below matter most when you reach for a Bootstrap class, because only some Bootstrap colors follow the theme. The rest are a single fixed value that was chosen for a white page.

Never put a color in an inline style attribute

An inline color cannot change between themes. Text written as <span style="color:purple"> stays the same dark purple on the dark page, where it drops to roughly 1.4:1 against the background and becomes unreadable.

Add a class in css/main.css instead, with a [data-bs-theme="dark"] counterpart. The dark rule only has to cover the values that actually need to move:

.text-purple { color: purple; }                        /* fine on white */
[data-bs-theme="dark"] .text-purple { color: #b69ae8; }

The same applies to style="background-color: ...", which otherwise leaves a light panel sitting in a dark page.

Prefer the utilities that follow the theme

These Bootstrap utilities change value between themes, so they are safe to use anywhere:

Use	Instead of	Notes
text-body-emphasis	text-dark, text-white	Highest-contrast body text
text-body-secondary	text-muted, text-secondary	De-emphasized text; text-secondary is not theme-aware
bg-body-tertiary	bg-light	Subtle panel fill
border, border-top, etc.	border-light, border-dark	Picks up the theme's border color
text-primary-emphasis, text-success-emphasis, ...	text-primary, text-success, ...	The -emphasis variants are the theme-aware pair

Avoid the fixed-color utilities for anything that carries text. bg-dark, bg-light, text-dark, text-white, text-secondary, and the plain text-primary / text-success / text-danger / text-info family all resolve to one value in both themes.

Pair a background with its text using text-bg-*

A bg-* class sets only the background, and leaves the text color to whatever it inherits. On a badge that default is white, so <span class="badge bg-info"> renders white on cyan at about 2:1, which is unreadable, and it is wrong in both themes.

Write text-bg-info instead, which sets the background and the matching text color together:

<span class="badge text-bg-info">PPP</span>      <!-- good -->
<span class="badge bg-info">PPP</span>           <!-- white on cyan -->

Do not use bg-dark for banners or pills

bg-dark is #212529, which is exactly the dark page background, so a dark banner or pill dissolves into the page. Its white text stays readable, but the bar itself disappears. css/main.css already lifts these to a visible slate in dark mode, so existing bg-dark markup is safe; prefer a semantic class over adding more.

Avoid the *-subtle backgrounds

The bg-*-subtle utilities do change with the theme, but their dark values are darker than the dark page, so the tint you wanted vanishes and the box reads as a hole. bg-info-subtle is #032830 against a #212529 page, barely one part in a hundred of difference.

Use a translucent wash instead, which tints whatever is behind it and therefore needs no dark-mode counterpart at all:

.bg-term-highlight { background-color: rgba(13, 202, 240, 0.2); }

Pin the text color on any fixed-color ground

Theme-aware text drifts off a fixed-color background. bg-warning stays amber in both themes, so text that lightens for dark mode (%%dimmed%%, ==highlighted==, text-danger) ends up light-on-amber. Anything placed inside bg-warning, bg-info, a <mark>, or an image panel needs its color pinned for both themes rather than left to inherit.

Give transparent images the tbg class

Diagrams saved with a transparent background lose their black lines and labels on the dark page. Add tbg, which puts a translucent light panel behind the image:

<pic eager class="tbg" src="../images/classDiagramsAllNotations.png" width="600" />

Use add-class="tbg" when the tag already carries other attributes. A caption inside the panel is handled automatically: css/main.css pins dark text and links inside tbg and bg-white.

Check both themes before you commit

Build the site, open the page, and toggle the theme in the navbar. Because the theme follows your operating system, viewing a page once only tells you about half of it. Look for text that fades into its background, and for panels, badges, or banners that disappear.

When you add a rule to css/main.css, check that a later rule does not override it. Two rules with the same specificity are resolved by order, so a general [data-bs-theme="dark"] .dimmed added at the end of the file will beat a more targeted .bg-warning .dimmed written earlier. Give the targeted rule the higher specificity when they overlap.

Bug reports, suggestions, change requests

• MarkBind bug reports and suggestions https://github.com/MarkBind/markbind/issues
• SE-Book bug reports and change requests se-edu/se-book issue tracker

Notable pages

/schedule/week1/index.html /schedule/week2/index.html /schedule/week3/index.html /schedule/week4/index.html /schedule/week5/index.html /schedule/week6/index.html /schedule/week7/index.html /schedule/week8/index.html /schedule/week9/index.html /schedule/week10/index.html /schedule/week11/index.html /schedule/week12/index.html /schedule/week13/index.html

/admin/courseOverview.html /admin/usingThisWebsite.html /admin/courseExpectations.html /admin/courseBriefings.html /admin/weeklySchedule.html /admin/lectures.html /admin/tutorials.html /admin/instructors.html /admin/textbooks.html /admin/programmingLanguages.html /admin/standardsAndConventions.html /admin/peerEvaluations.html /admin/tools.html /admin/exams.html /admin/participation.html /admin/gradeBreakdown.html

/admin/ip-overview.html /admin/ip-w2.html /admin/ip-w3.html /admin/ip-w4.html /admin/ip-w5.html /admin/ip-w6.html /admin/ip-w7.html /admin/ip-w8.html /admin/ip-grading.html

/admin/tp-overview.html /admin/tp-expectations.html /admin/tp-timeline.html /admin/tp-constraints.html /admin/tp-teams.html /admin/tp-w3.html /admin/tp-w4.html /admin/tp-w5.html /admin/tp-w6.html /admin/tp-w7.html /admin/tp-w8.html /admin/tp-w9.html /admin/tp-w10.html /admin/tp-w11.html /admin/tp-w12.html /admin/tp-w13.html /admin/tp-deliverables.html /admin/tp-ped.html /admin/tp-pe.html /admin/tp-grading.html /admin/tp-supervision.html

/admin/appendixA-principles.html /admin/appendixB-policies.html /admin/appendixC-faq.html /admin/appendixD-help.html /admin/appendixE-gitHub.html /admin/appendixF-teamworkIssues.html /admin/appendixG-troubleshooting.html

/admin/appendixH-tipsFromStudents.html