# How to Use This Template

This is the CityU Web Template v3 starter. Download the package below, unzip it, and use the `3.0.0/` folder as the starting point for your site, then follow the steps below to configure and build your pages.

## 1. Folder Structure

- `htm/` — Server-side include (SSI) fragments shared by all pages (header, footer, navigation, breadcrumb, meta tags, scripts).
- `css/custom.css` — Add your site-specific styles here.
- `js/custom.js` — Add your site-specific scripts here.
- `img/` — Place your page images here.
- `sample-pages/` — Ready-made page layouts (full-width, sidebar, contact, staff, landing).
- `sample-components/` — Reusable UI components (cards, carousels, banners, tables, forms, etc.).
- `themes/` — Five pre-built colour themes (blue, green, lime, pink, purple).
- `sample-news/` — News listing page, sample article, and data file (`news-list.json`).

## 2. Create a New Page

Copy `index.htm` (or any file from `sample-pages/` that fits your layout) and rename it. Every HTML file uses SSI directives to pull in the shared fragments:

- `<!--#include file="htm/meta.htm"-->` — loads required CSS and the favicon.
- `<!--#include file="htm/header.htm"-->` — CityU masthead and language switch.
- `<!--#include file="htm/menu.htm"-->` — main navigation and tools menu.
- `<!--#include file="htm/breadcrumb.htm"-->` — breadcrumb trail.
- `<!--#include file="htm/footer.htm"-->` — footer links and social media icons.
- `<!--#include file="htm/script.htm"-->` — required JS libraries (jQuery, Bootstrap, Swiper, AOS, script.js, cityu.base.js).

Replace the Main Content block with your own content.

## 3. Apply a Colour Theme

Open a file in `themes/` (e.g. `themes/blue.htm`) and copy its `<body>` class list into your pages, or add the theme class directly to the `<body>` tag — for example:

`<body class="cityu-template-3 cityu-template-3-0 cityu-base-layout cityu-base-style cityu-theme-blue">`

## 4. Customise Styles and Scripts

Add site-specific CSS to `css/custom.css` and JavaScript to `js/custom.js`. Both files are loaded last so they override the base template styles without modifying the shared CDN assets.

## 5. Use Sample Components and Pages

Browse `sample-components/` for ready-to-paste HTML snippets and `sample-pages/` for complete page layout examples. Copy the relevant markup into your pages and adjust content as needed.

## 6. Add a News Section

The `sample-news/` folder contains a ready-made news listing and a sample article. To add a news section to your site:

1. Copy `sample-news/` into your site folder (e.g. `news/`).
2. Edit `news-list.json` — each entry needs a `title`, `date`, `summary`, `url` (path to the article), and `image` (path to a thumbnail). New entries should be added at the top of the array.
3. For each article, copy `article-20260330-001.htm`, rename it (e.g. `article-YYYYMMDD-001.htm`), and replace the content inside the Main Content block.
4. The listing page (`index.htm`) loads and paginates items automatically via `js/news.js`, which is included just before `</body>` on that page only — do not add it to other pages.

## 7. Assets and Libraries

All shared assets (Bootstrap, Swiper, AOS, jQuery, and `cityu.base.css` / `cityu.base.js`) are served from the CityU template CDN at `https://template.cityu.edu.hk/template/v3/`. Do not copy these files locally — always reference the CDN URLs so your site receives security patches and updates automatically.