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

 This file is part of a Moko Consulting project.

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

 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.

 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the  GNU General Public License for more details. 

 You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/ .

 # FILE INFORMATION
 DEFGROUP: Joomla.Template.Site
 INGROUP: Moko-Cassiopeia.Documentation
 REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
 FILE: ./README.md
 VERSION: 03.05.00
 BRIEF: Documentation for Moko-Cassiopeia template
 -->

# Moko-Cassiopeia (VERSION: 03.05.00)

A modern, lightweight enhancement layer for Joomla's Cassiopeia
template.
Moko-Cassiopeia adds **Font Awesome 7**, **Bootstrap 5** helpers, an
automatic **Table of Contents (TOC)** utility, and optional **Moko
Expansions** including **Google Tag Manager** and **Google Analytics
(GA4)** hooks---all while keeping core template overrides minimal and
upgrade-friendly.

## Table of Contents

-   [Features](#features)
-   [Requirements](#requirements)
-   [Quick Start](#quick-start)
-   [Installation](#installation)
-   [Configuration](#configuration)
	-   [Global Params](#global-params)
	-   [Font Awesome 6](#font-awesome-6)
	-   [Bootstrap 5 Helpers](#bootstrap-5-helpers)
	-   [Table of Contents](#table-of-contents)
	-   [Dark Mode Toggle](#dark-mode-toggle)
	-   [Soft Offline Mode](#soft-offline-mode)
-   [Development](#development)
-   [Changelog](#changelog)
-   [Roadmap](#roadmap)

## Features

### Core Enhancements

-   Built on top of Joomla's default **Cassiopeia** template.
-   **Font Awesome 6** integration.
-   **Bootstrap 5** helpers (grid, utility classes).
-   **Automatic TOC** insertion for articles (activated via layout
	`toc-left` or `toc-right`).

### Added in 2.0

-   **Dark Mode Toggle**
	-   User-facing switch in the header.
	-   Persists preference with local storage.
	-   Admins can override default mode in template settings.
-   **Improved Template Params**
	-   Configure logo, GTM container ID, and dark mode defaults
		directly from template settings.

### New in 2.1.5 (In Development)

-   **Soft Offline Mode**
	-   Keeps articles in specific categories available when the site is
		offline.
	-   Example: legal or policy documents remain publicly viewable even
		during maintenance.
	-   Admin can configure which categories remain accessible.

## Requirements

-   Joomla **4.4.x** or **5.x**
-   PHP **8.0+**
-   MySQL/MariaDB compatible database

## Quick Start

1.  Install `moko-cassiopeia.zip` via Joomla's Template Installer.
2.  Set **Moko-Cassiopeia** as your default template.
3.  Configure template options under **System → Site Templates →
	Moko-Cassiopeia**.

## Installation

Upload and install through Joomla's extension manager.
If upgrading from a prior version, Joomla will safely overwrite files
--- no manual uninstall required.

## Configuration

### Global Params

-   **Logo**: Upload a custom site logo.
-   **Color Scheme**: Toggle light/dark defaults.
-   **Analytics/GTM**: Enable/disable optional expansions.

### Font Awesome 7

-   Fully integrated into Joomla's asset manager.
-   No extra scripts required.

### Bootstrap 5 Helpers

-   Adds extended utility classes and responsive tweaks.

### Table of Contents

-   Select `toc-left` or `toc-right` in article **Options → Layout** to
	insert TOC automatically.

### Dark Mode Toggle

-   User-facing switch in the header.
-   Remembers preference via local storage.
-   Default behavior can be set in template settings.

### Soft Offline Mode

-   Introduced in **2.1.5**.
-   Allows articles in selected categories to remain viewable during
	offline/maintenance mode.
-   Useful for compliance, legal, or policy content.

## Development

For developers and contributors working on the moko-cassiopeia template:

### Quick Start for Developers

Get started in minutes:

```bash
# Setup development environment
make dev-setup

# Validate code
make validate-required

# Check code quality
make quality

# Create distribution package
make package

# Install Git hooks (optional but recommended)
python3 ./scripts/git/install-hooks.py
```

**New to the project?** See [Quick Start Guide](./docs/QUICK_START.md) for a 5-minute walkthrough.

### Development Resources

- **[Quick Start Guide](./docs/QUICK_START.md)** - Get up and running in 5 minutes
- **[Workflow Guide](./docs/WORKFLOW_GUIDE.md)** - Complete workflow reference with examples
- **[Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Testing, quality checks, and deployment
- **[Scripts Documentation](./scripts/README.md)** - Available automation scripts
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute

### Available Tools

- **Makefile**: Run `make help` to see all available commands
- **Python Scripts**: All automation scripts are now Python-based for cross-platform compatibility
- **Pre-commit Hooks**: Automatic validation before commits
- **VS Code Tasks**: Pre-configured development tasks
- **GitHub Actions**: Automated CI/CD pipelines

### Cross-Platform Support

All scripts are now written in Python for maximum cross-platform compatibility:
- **Joomla Extension Support**: Full support for Joomla 4.x and 5.x templates, components, modules, and plugins
- **Dolibarr Module Support**: Automatic detection and packaging of Dolibarr modules
- **Platform Detection**: Scripts automatically detect whether you're working with Joomla or Dolibarr extensions

### Joomla Development Workflows

Comprehensive Joomla-aware development tools and workflows are available:

- **Extension Packaging** - Create distributable ZIP packages for Joomla or Dolibarr
- **PHP Quality Checks** - PHPStan and PHP_CodeSniffer with Joomla standards
- **Automated Testing** - Codeception framework with multiple Joomla versions
- **CI/CD Pipelines** - GitHub Actions with caching for faster builds

Run `make help` to see all available development commands.

## Changelog

See the [CHANGELOG.md](./CHANGELOG.md) for detailed version history.

---

## Metadata

* Maintainer: Moko Consulting Engineering
* Repository: [https://github.com/mokoconsulting-tech/moko-cassiopeia](https://github.com/mokoconsulting-tech/moko-cassiopeia)
* File: README.md
* Version: 3.0
* Classification: Public Open Source Standards

## Revision History

| Date       | Change Summary                                                      | Author                          |
| ---------- | ------------------------------------------------------------------- | ------------------------------- |
| 2026-01-05 | Initial publication of template documentation and feature overview. | Moko Consulting                 |
| 2026-01-05 | Fixed malformed markdown table formatting in revision history.     | Jonathan Miller (@jmiller-moko) |