From d9f241c80ad6254d0f27211428b7f2f8a0fd8144 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Fri, 24 Apr 2026 00:28:14 +0000 Subject: [PATCH] chore: bump patch version for release pipeline fixes [skip ci] --- README.md | 478 ++---------------------------------------------------- 1 file changed, 10 insertions(+), 468 deletions(-) diff --git a/README.md b/README.md index 80ea6e8..627aafa 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ INGROUP: MokoOnyx.Documentation REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx FILE: ./README.md - VERSION: 01.00.25 + VERSION: 01.00.26 BRIEF: Documentation for MokoOnyx template --> @@ -24,489 +24,31 @@ [![Joomla](https://img.shields.io/badge/Joomla-5.x%20%7C%206.x-red.svg?logo=joomla&logoColor=white)](https://www.joomla.org) [![PHP](https://img.shields.io/badge/PHP-8.1%2B-777BB4.svg?logo=php&logoColor=white)](https://www.php.net) -MokoOnyx is a modern, lightweight enhancement layer built on top of Joomla's Cassiopeia template. It adds **Font Awesome 7**, **Bootstrap 5** helpers, an automatic **Table of Contents (TOC)** utility, advanced **Dark Mode** theming, and optional integrations for **Google Tag Manager** and **Google Analytics (GA4)**β€”all while maintaining minimal core template overrides for maximum upgrade compatibility. +MokoOnyx is a modern, lightweight enhancement layer built on top of Joomla's Cassiopeia template. It adds **Font Awesome 7**, **Bootstrap 5** helpers, an automatic **Table of Contents (TOC)** utility, advanced **Dark Mode** theming, and optional integrations for **Google Tag Manager** and **Google Analytics (GA4)** -- all while maintaining minimal core template overrides for maximum upgrade compatibility. ---- - -## πŸ“‘ Table of Contents - -- [Features](#-features) -- [Requirements](#-requirements) -- [Installation](#-installation) -- [Quick Start](#-quick-start) -- [Configuration](#️-configuration) -- [Theme System](#-theme-system) -- [Development](#-development) -- [Documentation](#-documentation) -- [Changelog](#-changelog) -- [Support](#-support) -- [Contributing](#-contributing) -- [Included Libraries](#-included-libraries) -- [License](#-license) - ---- - -## ✨ Features - -### Core Enhancements +## Features - **Built on Cassiopeia**: Extends Joomla's default template with minimal overrides - **Font Awesome 7**: Fully integrated into Joomla's asset manager with 2,000+ icons - **Bootstrap 5**: Extended utility classes and responsive grid system -- **Template Overrides**: Includes overrides for all core Joomla modules, Community Builder, and DPCalendar with consistent title rendering and Bootstrap 5 styling -- **Upgrade-Friendly**: Minimal core modifications ensure smooth Joomla updates - -### Advanced Theming - +- **Template Overrides**: Includes overrides for all core Joomla modules, Community Builder, and DPCalendar - **Dark Mode Support**: Built-in light/dark mode toggle with system preference detection -- **Color Palettes**: Standard, Alternative, and Custom color schemes -- **Theme Persistence**: User preferences saved via localStorage -- **Theme Control Options**: Switch, radio buttons, or hidden controls -- **Auto Dark Mode**: Optional automatic dark mode based on time/system settings -- **Meta Tags**: Automatic color-scheme and theme-color meta tags - -### Developer Features - -- **Custom Code Injection**: Add custom HTML to `` start/end -- **Drawer Sidebars**: Configurable left/right drawer positions with custom icons -- **Font Options**: Local and web fonts (Roboto, Fira Sans, Noto Sans) -- **Sticky Header**: Optional sticky navigation -- **Back to Top**: Floating back-to-top button - -### Analytics & Tracking - -- **Google Tag Manager**: Optional GTM integration with container ID configuration -- **Google Analytics**: Optional GA4 integration with measurement ID -- **Privacy-Friendly**: All tracking features are optional and easily disabled - -### Content Features - +- **Google Tag Manager / GA4**: Optional analytics integrations - **Table of Contents**: Automatic TOC generation for long articles - - Placement options: `toc-left` or `toc-right` layouts - - Automatic heading extraction and navigation - - Responsive sidebar positioning ---- - -## πŸ“‹ Requirements +## Requirements - **Joomla**: 5.x or 6.x - **PHP**: 8.1 or higher -- **Database**: MySQL 5.7+ / MariaDB 10.2+ / PostgreSQL 11+ -- **Browser Support**: Modern browsers (Chrome, Firefox, Safari, Edge) ---- +## Installation -## πŸ“¦ Installation +Download the latest `mokoonyx-{version}.zip` from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases) and install via Joomla's Extension Manager. -**Note**: MokoOnyx is a **standalone Joomla template extension** (not bundled as a package). Install it directly via Joomla's Extension Manager. - -### Via Joomla Extension Manager - -1. Download the latest `mokoonyx-{version}.zip` from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases) -2. In Joomla admin, navigate to **System β†’ Install β†’ Extensions** -3. Upload the ZIP file and click **Upload & Install** -4. Navigate to **System β†’ Site Templates** -5. Set **MokoOnyx** as your default template - -### Via Git (Development) - -```bash -git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git -cd MokoOnyx -``` - -See [Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for development setup. - ---- - -## πŸš€ Quick Start - -### 1. Install the Template - -Install `mokoonyx.zip` via Joomla's Extension Manager. - -### 2. Set as Default - -Navigate to **System β†’ Site Templates** and set **MokoOnyx** as default. - -### 3. Configure Template Options - -Go to **System β†’ Site Templates β†’ MokoOnyx** to configure: - -- **Branding**: Upload logo, set site title/description -- **Theme**: Configure color schemes and dark mode -- **Layout**: Set container type (static/fluid), sticky header -- **Analytics**: Add GTM/GA4 tracking codes (optional) -- **Custom Code**: Inject custom HTML/CSS/JS - -### 4. Test Dark Mode - -The template includes a dark mode toggle. Test it by: -- Using the floating theme toggle button (bottom-right by default) -- Checking theme persistence across page loads -- Verifying system preference detection - ---- - -## Usage - -Once installed and set as the default site template, MokoOnyx works out of the box with Joomla's standard content and module system. Key usage points: - -- **Template Options** β€” Configure via **System β†’ Site Templates β†’ MokoOnyx** (theme colours, layout, analytics, favicon, drawers) -- **Custom Colour Schemes** β€” Copy `templates/mokoonyx/templates/light.custom.css` or `dark.custom.css` to `media/templates/site/mokoonyx/css/theme/` and select "Custom" in the Theme tab -- **Custom CSS/JS** β€” Create `media/templates/site/mokoonyx/css/user.css` or `js/user.js` for site-specific overrides that survive template updates -- **Module Overrides** β€” The template includes overrides for common Joomla modules with consistent title rendering, Bootstrap 5 styling, and Font Awesome 7 icons -- **Dark Mode** β€” Enabled by default with a floating toggle button; respects system preference and persists via localStorage - -See [Configuration](#️-configuration) below for detailed parameter reference. - ---- - -## βš™οΈ Configuration - -### Global Parameters - -Access template configuration via **System β†’ Site Templates β†’ MokoOnyx**. - -#### Theme Tab - -**General Settings:** -- **Theme Enabled**: Enable/disable theme system -- **Theme Control Type**: Switch (Light↔Dark), Radios (Light/Dark/System), or None -- **Default Choice**: System, Light, or Dark -- **Auto Dark Mode**: Automatic dark mode based on time -- **Meta Tags**: Enable color-scheme and theme-color meta tags -- **Bridge Bootstrap ARIA**: Sync theme with Bootstrap's data-bs-theme - -**Variables & Palettes:** -- **Light Mode Palette**: Standard, Alternative, or Custom -- **Dark Mode Palette**: Standard, Alternative, or Custom - -**Typography:** -- **Font Scheme**: Local (Roboto) or Web fonts (Fira Sans, Roboto+Noto Sans) - -**Branding & Icons:** -- **Brand**: Enable/disable site branding -- **Logo File**: Upload custom logo (no default logo included) -- **Site Title**: Custom site title -- **Site Description**: Tagline/description -- **Font Awesome Kit**: Optional FA Pro kit code - -**Header & Navigation:** -- **Sticky Header**: Enable fixed header on scroll -- **Back to Top**: Enable floating back-to-top button - -**Theme Toggle UI:** -- **FAB Enabled**: Enable floating action button toggle -- **FAB Position**: Bottom-right, Bottom-left, Top-right, or Top-left - -#### Advanced Tab - -- **Layout**: Static or Fluid container - -#### Google Tab - -- **Google Tag Manager**: Enable and configure GTM container ID -- **Google Analytics**: Enable and configure GA4 measurement ID - -#### Custom Code Tab - -- **Custom Head Start**: HTML injected at start of `` -- **Custom Head End**: HTML injected at end of `` - -#### Drawers Tab - -- **Left Drawer Icon**: Font Awesome icon class (e.g., `fa-solid fa-chevron-right`) -- **Right Drawer Icon**: Font Awesome icon class (e.g., `fa-solid fa-chevron-left`) - -### Custom Theme Palettes - -MokoOnyx supports custom theme schemes: - -1. **Copy template files** from `/templates/` directory: - - `light.custom.css` β†’ `media/templates/site/mokoonyx/css/theme/light.custom.css` - - `dark.custom.css` β†’ `media/templates/site/mokoonyx/css/theme/dark.custom.css` -2. **Customize** the CSS variables to match your brand colors -3. **Enable in Joomla**: System β†’ Site Templates β†’ MokoOnyx β†’ Theme tab β†’ Set palette to "Custom" -4. **Save** and view your site with custom colors - -**Note:** Custom color files are excluded from version control (`.gitignore`) to prevent fork-specific customizations from being committed. - -**Quick Example:** - -```css -:root[data-bs-theme="light"] { - --color-primary: #1e40af; - --color-link: #2563eb; - --color-hover: #1d4ed8; - --body-color: #1f2937; - --body-bg: #ffffff; -} -``` - -**Complete Reference:** See [CSS Variables Documentation](./docs/CSS_VARIABLES.md) for all available variables and detailed usage examples. - -### Table of Contents - -Enable automatic TOC for articles: - -1. Edit an article in Joomla admin -2. Navigate to **Options β†’ Layout** -3. Select **toc-left** or **toc-right** -4. Save the article - -The TOC will automatically generate from article headings (H2, H3, etc.) and appear as a sidebar. - ---- - -## 🎨 Theme System - -### Dark Mode Features - -- **Automatic Detection**: Respects user's system preferences -- **Manual Toggle**: Floating button or radio controls -- **Persistence**: Saves preference in localStorage -- **Smooth Transitions**: Animated theme switching -- **Comprehensive Support**: All components themed for dark mode - -### Theme Control Types - -1. **Switch**: Simple light/dark toggle button -2. **Radios**: Three options - Light, Dark, System -3. **None**: No visible control (respects system only) - -### Meta Tags - -When enabled, the template adds: - -```html - - - -``` - ---- - -## πŸ›  Development - -### For Contributors - -**New to the project?** See [Quick Start Guide](./docs/QUICK_START.md) for a 5-minute setup. - -### Development Resources - -- **[Quick Start Guide](./docs/QUICK_START.md)** - Setup and first steps -- **[Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Testing, quality checks, deployment -- **[Workflow Guide](./docs/WORKFLOW_GUIDE.md)** - Git workflow and branching -- **[Contributing Guide](./CONTRIBUTING.md)** - Contribution guidelines -- **[Roadmap](./docs/ROADMAP.md)** - Feature roadmap and planning - -### Development Tools - -- **Pre-commit Hooks**: Automatic validation before commits -- **PHP CodeSniffer**: Code style validation (Joomla standards) -- **PHPStan**: Static analysis for PHP code -- **Codeception**: Testing framework - -### Quick Development Setup - -```bash -# Clone repository -git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git -cd MokoOnyx - -# Install development dependencies (if using Composer) -composer install --dev - -# Run code quality checks -make validate # or manual commands -``` - -### Building Template Package - -See [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for packaging instructions. - ---- - -## πŸ“š Documentation - -### User Documentation - -- **[README](./README.md)** - This file (overview and features) -- **[CHANGELOG](./CHANGELOG.md)** - Version history and changes -- **[Roadmap](./docs/ROADMAP.md)** - Planned features and timeline - -### Developer Documentation - -- **[Quick Start](./docs/QUICK_START.md)** - 5-minute developer setup -- **[Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Comprehensive development guide -- **[Workflow Guide](./docs/WORKFLOW_GUIDE.md)** - Git workflow and processes -- **[CSS Variables Reference](./docs/CSS_VARIABLES.md)** - Complete CSS customization guide -- **[Documentation Index](./docs/README.md)** - All documentation links - -### Governance - -- **[Contributing](./CONTRIBUTING.md)** - How to contribute -- **[Code of Conduct](./CODE_OF_CONDUCT.md)** - Community standards -- **[Governance](./GOVERNANCE.md)** - Project governance model -- **[Security Policy](./SECURITY.md)** - Security reporting and procedures - ---- - -## πŸ“– Changelog - -See the [CHANGELOG.md](./CHANGELOG.md) for detailed version history. - -### Recent Releases - -See [Gitea Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases) for all versions. - ---- - -## πŸ’¬ Support - -### Getting Help - -- **Documentation**: Check this README and [docs folder](./docs/) -- **Issues**: Report bugs via [Gitea Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -- **Roadmap**: View planned features in [Roadmap](https://mokoconsulting.tech/support/joomla-cms/mokoonyx-roadmap) - -### Reporting Bugs - -Please include: -- Joomla version -- PHP version -- Template version -- Steps to reproduce -- Expected vs actual behavior -- Screenshots (if applicable) - -### Security Issues - -**Do not** report security vulnerabilities via public issues. See [SECURITY.md](./SECURITY.md) for reporting procedures. - ---- - -## 🀝 Contributing - -We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. - -### How to Contribute - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Make your changes -4. Run quality checks -5. Commit your changes (`git commit -m 'Add amazing feature'`) -6. Push to the branch (`git push origin feature/amazing-feature`) -7. Open a Pull Request - -### Development Workflow - -See [Workflow Guide](./docs/WORKFLOW_GUIDE.md) for detailed Git workflow. - -### Customizations - -For template customizations, use Joomla's built-in template settings (System β†’ Site Templates β†’ MokoOnyx β†’ Custom Code tab) for HTML/CSS/JS customizations. - ---- - -## πŸ“¦ Included Libraries - -MokoOnyx includes the following third-party libraries to provide enhanced functionality: - -### Bootstrap TOC - -- **Version**: 1.0.1 -- **Author**: Aidan Feldman -- **License**: MIT License -- **Source**: [GitHub Repository](https://github.com/afeld/bootstrap-toc) -- **Release**: [v1.0.1 Release](https://github.com/afeld/bootstrap-toc/releases/tag/v1.0.1) -- **Purpose**: Automatically generates a table of contents from article headings with scrollspy support -- **Location**: `src/media/vendor/bootstrap-toc/` -- **Integration**: Registered in `joomla.asset.json` as `vendor.bootstrap-toc` (CSS) and `vendor.bootstrap-toc.js` (JavaScript) -- **Usage**: Activated when using `toc-left` or `toc-right` article layouts -- **Features**: - - Automatic TOC generation from H1-H6 headings - - Hierarchical nested navigation - - Active state highlighting with scrollspy - - Responsive design (collapses on mobile) - - Smooth scrolling to sections - - Automatic unique ID generation for headings -- **Customizations**: CSS adapted to use MokoOnyx CSS variables for theme compatibility - -### Font Awesome 7 Free - -- **Version**: 7.0 (Free) -- **License**: Font Awesome Free License -- **Source**: [Font Awesome](https://fontawesome.com) -- **Purpose**: Provides 2,000+ vector icons for interface elements -- **Location**: `src/media/vendor/fa7free/` -- **Integration**: Fully integrated into Joomla's asset manager -- **Styles Available**: Solid, Regular, Brands - -### Bootstrap 5 - -- **Version**: 5.x (via Joomla) -- **License**: MIT License -- **Source**: [Bootstrap](https://getbootstrap.com) -- **Purpose**: Provides responsive grid system and utility classes -- **Integration**: Inherited from Joomla's Cassiopeia template, extended with additional helpers -- **Components Used**: Grid, utilities, modal, dropdown, collapse, offcanvas, tooltip, popover, scrollspy - -### Integration Method - -All third-party libraries are: -- βœ… Properly licensed and attributed -- βœ… Registered in Joomla's Web Asset Manager (`joomla.asset.json`) -- βœ… Loaded on-demand to optimize performance -- βœ… Versioned and documented for maintenance -- βœ… Compatible with Joomla 5.x and 6.x - ---- - -## πŸ“„ License +## License This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](./LICENSE) file for details. -### Third-Party Licenses - -- **Joomla! CMS**: GPL-2.0-or-later -- **Cassiopeia Template**: GPL-2.0-or-later (Joomla Project) -- **Font Awesome 7 Free**: Font Awesome Free License -- **Bootstrap 5**: MIT License -- **Bootstrap TOC**: MIT License (A. Feld) - -All third-party libraries and assets remain the property of their respective authors and are credited in source files. - --- -## πŸ”— Links - -- **Repository**: [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -- **Issue Tracker**: [Gitea Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -- **GitHub Mirror**: [GitHub](https://github.com/mokoconsulting-tech/MokoOnyx) -- **Roadmap**: [Full Roadmap](https://mokoconsulting.tech/support/joomla-cms/mokoonyx-roadmap) -- **Moko Consulting**: [Website](https://mokoconsulting.tech) - ---- - -## πŸ“Š Metadata - -- **Maintainer**: Moko Consulting Engineering -- **Author**: Jonathan Miller (@jmiller-moko) -- **Repository**: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx -- **License**: GPL-3.0-or-later -- **Classification**: Public Open Source Standards - -## πŸ“ Revision History - -| Date | Version | Change Summary | Author | -| ---------- | -------- | ------------------------------------------------------------------------- | ------------------------------- | -| 2026-04-22 | 01.00.15 | Updated README: dynamic version badge, corrected requirements, fixed links | Claude Code | -| 2026-04-19 | 01.00.00 | Initial MokoOnyx release β€” renamed from MokoCassiopeia with auto-migration | Moko Consulting | - ---- - -**Made with ❀️ by [Moko Consulting](https://mokoconsulting.tech)** +**Made with love by [Moko Consulting](https://mokoconsulting.tech)**