# CityU Web Template 3.0 — Site Starter Kit

CDN base: `https://template.cityu.edu.hk/template/v3/` — never copy files from this CDN base URL locally (e.g. Bootstrap, Swiper, jQuery, AOS).

## Tech Stack
Bootstrap 5.3.8 · Bootstrap Icons 1.13.1 · Swiper 11.2.0 · AOS 2.3.4 · jQuery 3.7.1 · Google Fonts (Montserrat)
- `cityu.base.css` — design system, BEM-scoped under `.cityu`
- `cityu.base.js` — reads `js/cityu.config.js`, auto-fills metadata, initialises UI

## Folder Structure
| Path | Purpose |
|------|---------|
| `htm/` | SSI fragments (header, footer, menu, breadcrumb, meta, scripts) |
| `css/custom.css` | Site-specific CSS overrides |
| `js/custom.js` | Site-specific scripts |
| `js/cityu.config.js` | Configure per site — `mode`, `logoutLink`, `cookieNotice`, etc. |
| `js/news.js` | News list fetch + pagination |
| `img/` | Site images |
| `sample-pages/` | Page layout templates |
| `sample-components/` | Copy-paste HTML snippets |
| `sample-news/` | News listing + article pattern |
| `themes/` | Colour theme variants |

## Page Layouts (mandatory)

**Before writing HTML, read the matching sample file and follow its structure exactly.** No sidebar → `page-full-width.htm`; sidebar → `page-with-sidebar.htm`. Never default to sidebar.

| File | Use for |
|------|---------|
| `sample-pages/page-with-sidebar.htm` | Standard content page with left sidemenu |
| `sample-pages/page-full-width.htm` | Content page, no sidebar |
| `sample-pages/landing-page.htm` | Landing/special pages |
| `sample-pages/contact.htm` | Contact pages |
| `sample-pages/staff.htm` | Staff directory pages |

### Structure & Layout
- **`<body>` class**: `cityu-template-3 cityu-template-3-0 cityu-base-layout cityu-base-style`; prepend `home` on home pages.
- **Main content nesting** (exact hierarchy, never reorder):
  ```
  <div class="cityu">
    <main class="cityu-main" role="main">
      <div class="cityu-main-inner">
        [banner section]
        <section class="section-wrap section-light">
          <div class="section-content">
            <div class="container-xxl">
  ```
- **Sidemenu**: left column `col-12 col-xl-3 d-none d-xl-block`; content: right `col-12 col-xl-9 d-block`
- **Breadcrumb**: own row before content+sidebar row; omit on home pages

### CSS Classes, Paths & Sections
- `content-color-default` must always accompany `cityu-content`
- SSI paths: root pages use `htm/`; subdirectory pages use `../htm/`
- **Section transitions**: when a dark/coloured section follows `section-light`, add `<div class="section-bg bg-skew-radius-right"></div>` as a sibling of `section-content` (direct child of `<section>`), just before `</section>`.

## Conventions
- `<title>`: always `<title>City University of Hong Kong</title>` — auto-replaced at runtime
- `<h1>` in `.cityu-content`: add `class="header-gradient"`
- `<h2>` in `.cityu-content`: add `class="heading-underline"`
- **Buttons**: never use `btn`/`btn-*`; use `button`, `button button-sm/lg/xl`, `button-light`
- Spacing: `me-auto`/`ms-auto` (not `mr-`/`ml-`)
- CSS: `0` not `0px`
- Below-fold images: `loading="lazy"`
- External links: `target="_blank" rel="noopener"`
- **Tables**: wrap in `<div class="table-responsive">`; add `class="table"`, `<thead>`/`<tbody>`, `scope="col"` on headers
- **Anchors**: use `id="anchor"` on heading/wrapper — never `<a name="">`

## Migration Workflow
- **New site — verify tech stack**: Read `htm/meta.htm` and `htm/script.htm`; fetch CDN URLs to confirm versions. Update Tech Stack before any page work.
- **Ask before bulk migration**: Confirm (1) sidebar vs full-width; (2) subdirectory pages — migrate or skip; (3) pages requiring case-by-case decisions (e.g. PDF-only, redirects). Offer "migrate / redirect / skip" options.
- **First page of session**: also migrate `menu-main.htm`, `header.htm`, `footer-media.htm`, `menu-tools.htm`:
  - **header**: uncomment `cityu-header-lg-mainsite`, comment out `cityu-header-lg-subsite`; never remove `cityu-header-md-name`
  - **footer-media**: comment out all `<li>` if no social media; never remove the `<ul>`
  - **menu-tools**: comment out language switcher if absent; update language `href` values if present
- **Chinese pages**: create `htm/menu-main-tc.htm`, `menu-main-sc.htm`, `menu-tools-tc.htm`, `menu-tools-sc.htm` (correct `is-active`), and `htm/menu-tc.htm` / `menu-sc.htm` wrappers. Chinese pages include the wrapper instead of `htm/menu.htm`. URLs with `[_-]chi` suffix are auto-matched to the English menu item by `cityu.base.js`.
- **Banner**: first child of `<div class="cityu-main-inner">`. Home pages: `component-banner-1` with `<img>`; all others: `component-banner-2` (empty `<div class="component-banner-2">`).

## Migration Checklist (per page)
- **Read source first**: read in full before writing; copy content verbatim, only rewrite the HTML wrapper.
- **Absolute URLs**: convert old-host URLs (e.g. `https://www6.cityu.edu.hk/...`) to site-relative paths.
- **Legacy HTML**: strip `<font>`, `<center>`, non-semantic `<b>`/`<i>`, inline `style=""`, `<a name="">`. Use semantic HTML and Bootstrap utilities.
- **FontAwesome → Bootstrap Icons**: replace `fas fa-*`, `far fa-*`, `fab fa-*` with `<i class="bi bi-*"></i>`. Notify user if no equivalent exists.
- **Base href**: `baseurl.htm` sets `<base href="/{site-folder}/">` — all paths resolve from site root. For anchor links: `href="subdir/page.htm#section"`.
- **Images**: for every `<img>`, check file exists in source; copy to `img/` and update `src`. Use absolute `src` only for genuinely external images. Every `<img>` needs `alt`; decorative: `alt=""`.
- **Documents**: for every PDF/Word link, check file exists in source; copy to `doc/` and update `href`.
- **PowerShell writes**: use `Set-Content -Encoding UTF8NoBOM` to avoid BOM (`&#xFEFF;`) in browser output.
- **Broken link audit**: check (1) all non-absolute `href` in `htm/menu-main.htm`; (2) all internal `href` in `*.htm` (exclude `mailto:`, `https?://`, bare `#`). Strip fragments; resolve from site root. Write results to a temp file.
- **CHANGELOG**: log to `.github/CHANGELOG.md` (create if absent); entry: `## YYYY-MM-DD — description` with new/updated file lists.

