MokoCassiopeia/README.md

<!-- 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:

### Joomla Development Workflows

Comprehensive Joomla-aware development tools and workflows are available:

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

See the [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for:
- Setup instructions for local development
- Running tests and quality checks
- Creating release packages
- Deployment workflows
- CI/CD pipeline details

### Quick Start for Developers

```bash
# Validate code
./scripts/validate/php_syntax.sh
./scripts/validate/manifest.sh

# Create distribution package
./scripts/release/package_extension.sh dist 3.5.0

# Run tests (requires Codeception)
codecept run

# Check code quality (requires PHPStan/PHPCS)
phpstan analyse --configuration=phpstan.neon
phpcs --standard=phpcs.xml
```

## 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

| Version | Date       | Author 													| Description 													|
| ------- | ---------- | -----------------------------_-- | ------------------------------------- |
| 3.0     | 2025-12-09 | Jonathan Miller (@jmiller-moko) 	| Added Metadata and Revision History  	|