<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

 This file is part of a Moko Consulting project.

 SPDX-License-Identifier: GPL-3.0-or-later

 # FILE INFORMATION
 REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero
 FILE: ./README.md
 VERSION: 01.07.00
 BRIEF: MokoJoomHero - Joomla Module
 -->

# MokoJoomHero

A Joomla 5 site template developed following MokoStandards.

[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)

## Overview

MokoJoomHero is a modern, accessible Joomla 5 template by Moko Consulting. It features a prominent hero section, flexible module positions, sticky header, customisable brand colour, and responsive layout — all built on Joomla's Web Asset Manager.

## Features

- **Hero Section**: Dedicated `hero` module position with gradient styling
- **Flexible Layout**: 11 module positions including sidebars, topbar, banner, and footer
- **Sticky Header**: Optional sticky navigation with smooth scroll
- **Brand Customisation**: Configurable brand colour, logo, and tagline via Template Manager
- **Responsive**: Mobile-first layout with CSS custom properties
- **Accessibility**: Semantic HTML5, ARIA landmarks, skip-to-content support
- **Web Asset Manager**: Modern asset loading via `joomla.asset.json`
- **Error & Offline Pages**: Custom styled error and offline templates

## Prerequisites

- **PHP**: 8.1 or higher
- **Joomla**: 5.x (also compatible with 6.x)
- **Make**: GNU Make for build automation

## Installation

1. Build the template package:
   ```bash
   make build
   ```

2. Upload the generated `tpl_mokojoomhero-1.0.0.zip` via Joomla's Extension Manager

3. Set as default template in **System → Site Template Styles**

## Usage

```bash
# Display available commands
make help

# Validate code
make validate

# Build template package
make build
```

## Module Positions

| Position | Purpose |
|----------|---------|
| `topbar` | Slim bar above the header (contact info, social links) |
| `banner` | Full-width banner below the header |
| `menu` | Main navigation inside the header |
| `hero` | Hero section with gradient background |
| `breadcrumbs` | Breadcrumb trail |
| `sidebar-left` | Left sidebar |
| `sidebar-right` | Right sidebar |
| `main-top` | Above the main content area |
| `main-bottom` | Below the main content area |
| `footer` | Footer area |
| `debug` | Debug output (hidden from users) |

## Template Parameters

Configure via **System → Site Template Styles → MokoJoomHero**:

- **Logo** — Upload a site logo image
- **Site Description** — Tagline displayed next to the logo
- **Brand Colour** — Primary accent colour (default: `#1a73e8`)
- **Fluid Container** — Toggle full-width vs fixed-width layout
- **Sticky Header** — Keep the header visible on scroll
- **Back to Top** — Floating scroll-to-top button

## Project Structure

```
.
├── docs/                          # Documentation files
├── scripts/                       # Build and deployment scripts
├── src/                           # Template source code
│   ├── css/template.css           # Main stylesheet
│   ├── js/template.js             # Main JavaScript
│   ├── images/                    # Template images
│   ├── html/                      # Template overrides
│   ├── language/en-GB/            # Language files
│   ├── templateDetails.xml        # Joomla manifest
│   ├── joomla.asset.json          # Web Asset Manager config
│   ├── index.php                  # Main template
│   ├── error.php                  # Error page
│   ├── offline.php                # Offline page
│   └── component.php              # Component-only output
├── Makefile                       # Build automation
└── README.md                      # This file
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Versioning

This project uses [Semantic Versioning](https://semver.org/).

See [CHANGELOG.md](CHANGELOG.md) for version history.

## License

Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SPDX-License-Identifier: GPL-3.0-or-later

## Support

- **Documentation**: See the [docs/](docs/) directory
- **Contact**: hello@mokoconsulting.tech
- **Website**: [mokoconsulting.tech](https://mokoconsulting.tech)