diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d17cee3..880f9ca 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -326,11 +326,11 @@ cd scripts ## Client Forks -For client-specific customizations: -- Use `CLIENT_FORK_README.md` template -- Follow fork workflow in `docs/CLIENT_FORK_WORKFLOW.md` -- Keep custom color files in `media/.../css/colors/` (gitignored) -- Document client-specific changes separately +For client-specific color customizations: +- Use automated workflow in `docs/CLIENT_FORK_WORKFLOW.md` +- Custom color files tracked via client fork .gitignore template +- Use Joomla's template settings for other customizations (Custom Code tab) +- Limited scope: colors only ## License Compliance diff --git a/CLAUDE.md b/CLAUDE.md index d0103f8..1b7487f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -543,4 +543,4 @@ Must-read before contributing: - **CHANGELOG.md** - Version history and release notes - **GOVERNANCE.md** - Project governance model and decision-making - **CODE_OF_CONDUCT.md** - Community standards and expectations -- **CLIENT_FORK_README.md** - Guide for client-specific customization forks +- **CLIENT_FORK_WORKFLOW.md** - Automated setup for client color customizations diff --git a/CLIENT_FORK_README.md b/CLIENT_FORK_README.md deleted file mode 100644 index 2b8aa85..0000000 --- a/CLIENT_FORK_README.md +++ /dev/null @@ -1,455 +0,0 @@ - - -# [CLIENT NAME] - MokoCassiopeia Custom Fork - -**Custom Joomla Template Fork for [CLIENT NAME]** - -This is a customized fork of the [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) Joomla template, tailored specifically for [CLIENT NAME]'s website. - -> **💡 Tip**: This fork was likely created using the automated [Client Fork Workflow](./docs/CLIENT_FORK_WORKFLOW.md). If you're creating a new client fork, use the workflow for instant setup! - ---- - -## 📋 About This Fork - -This repository contains client-specific customizations built on top of the MokoCassiopeia template. The template provides a modern, lightweight enhancement layer for Joomla with advanced theming, Font Awesome 7, Bootstrap 5, and dark mode support. - -### Customization Strategy - -This fork maintains the following customizations: -- **Custom Color Schemes**: Brand-specific colors for light and dark modes -- **Custom Code**: Client-specific HTML, CSS, and JavaScript customizations -- **Configuration**: Pre-configured template settings for the client environment - -All customizations are designed to be preserved when syncing with upstream MokoCassiopeia updates. - ---- - -## 🚀 Quick Start - -### Prerequisites - -- **Joomla**: 4.4.x or 5.x -- **PHP**: 8.0 or higher -- **Git**: For version control and syncing with upstream -- **Local Development**: MAMP/XAMPP/Docker for local testing - -### Installation for Development - -1. **Clone this repository**: - ```bash - git clone [YOUR-FORK-URL] - cd [YOUR-FORK-NAME] - ``` - -2. **Set up upstream remote** (for syncing updates): - ```bash - git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git - git fetch upstream - ``` - -3. **Install into Joomla**: - - Copy the `src/` directory contents to your Joomla installation: - - `src/templates/` → `[joomla]/templates/` - - `src/media/` → `[joomla]/media/templates/site/mokocassiopeia/` - - `src/language/` → `[joomla]/language/` - - `src/administrator/language/` → `[joomla]/administrator/language/` - -4. **Enable the template**: - - Log into Joomla admin - - Navigate to **System → Site Templates** - - Set **MokoCassiopeia** as the default template - ---- - -## 🎨 Custom Branding & Colors - -### Custom Color Schemes - -This fork includes custom color schemes specific to [CLIENT NAME]'s brand: - -**Location**: -- Light mode: `src/media/css/colors/light/colors_custom.css` -- Dark mode: `src/media/css/colors/dark/colors_custom.css` - -**Note**: These files are gitignored in the upstream repository to prevent conflicts, but are tracked in this fork. - -### Modifying Brand Colors - -1. **Edit the custom color files**: - ```bash - # Light mode colors - edit src/media/css/colors/light/colors_custom.css - - # Dark mode colors - edit src/media/css/colors/dark/colors_custom.css - ``` - -2. **Key variables to customize**: - ```css - :root[data-bs-theme="light"] { - --color-primary: #YOUR-BRAND-COLOR; - --accent-color-primary: #YOUR-ACCENT-COLOR; - --color-link: #YOUR-LINK-COLOR; - --nav-bg-color: #YOUR-NAV-BG; - } - ``` - -3. **Test your changes**: - - Clear Joomla cache: System → Clear Cache - - Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R) - - View your site in light and dark modes - -### Available CSS Variables - -For a complete reference of all customizable CSS variables, see the [CSS Variables Documentation](./docs/CSS_VARIABLES.md) in the upstream repository. - ---- - -## 🔧 Custom Code Injection - -### Using custom.php - -The `src/templates/custom.php` file allows for custom PHP functions and HTML snippets: - -**Location**: `src/templates/custom.php` - -**Example Use Cases**: -- Custom helper functions -- Client-specific HTML snippets -- Custom console logging -- Integration code - -**Example**: -```php -' . $js_code . ''; - } - echo $js_code; -} -?> - -``` - -### Custom Code via Joomla Template Settings - -You can also inject custom code via the Joomla admin interface: - -1. Navigate to **System → Site Templates → MokoCassiopeia** -2. Go to the **Custom Code** tab -3. Add custom HTML/CSS/JS in: - - **Custom Head Start**: Injected at the beginning of `` - - **Custom Head End**: Injected at the end of `` - -This approach is ideal for: -- Analytics tracking codes -- Custom meta tags -- External script includes -- Custom CSS snippets - ---- - -## 🔄 Syncing with Upstream Updates - -To keep your fork up-to-date with new features and bug fixes from the upstream MokoCassiopeia repository: - -### 1. Fetch Upstream Changes - -```bash -# Ensure upstream remote is configured -git remote -v -# If upstream is not listed, add it: -# git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git - -# Fetch latest changes -git fetch upstream -``` - -### 2. Review Changes - -```bash -# See what changed in upstream -git log HEAD..upstream/main --oneline - -# Review the diff -git diff HEAD..upstream/main -``` - -### 3. Merge Upstream Changes - -```bash -# Switch to your main branch -git checkout main - -# Merge upstream changes -git merge upstream/main - -# Or rebase (preserves cleaner history): -# git rebase upstream/main -``` - -### 4. Resolve Conflicts - -If conflicts occur (typically in custom files): - -1. **Check conflict status**: - ```bash - git status - ``` - -2. **Resolve conflicts manually** in your editor: - - Look for conflict markers: `<<<<<<<`, `=======`, `>>>>>>>` - - Keep your custom changes - - Remove conflict markers - -3. **Complete the merge**: - ```bash - git add . - git commit -m "Merge upstream updates and resolve conflicts" - ``` - -### 5. Test After Merging - -- Clear Joomla cache -- Test critical functionality: - - Homepage loads correctly - - Custom colors are preserved - - Dark mode toggle works - - Navigation functions properly - - Custom code still executes - -### Protected Files - -The following files contain your customizations and should be carefully reviewed during merges: - -- `src/media/css/colors/light/colors_custom.css` (custom light mode colors) -- `src/media/css/colors/dark/colors_custom.css` (custom dark mode colors) -- `src/templates/custom.php` (custom PHP code) -- Template configuration (stored in Joomla database, not in files) - ---- - -## 📦 Building & Deployment - -### Creating a Template Package - -To create an installable ZIP package of your customized template: - -1. **Prepare the package**: - ```bash - cd src - zip -r ../mokocassiopeia-[CLIENT-NAME]-[VERSION].zip . -x "*.git*" "*.DS_Store" - ``` - -2. **Install via Joomla**: - - Upload the ZIP file via **System → Install → Extensions** - - Or manually copy files to the Joomla installation - -### Deployment to Production - -**Recommended Deployment Methods**: - -1. **Via Joomla Extension Manager** (Easiest): - - Create a ZIP package as described above - - Upload via Joomla admin interface - - The template will automatically overwrite the existing installation - -2. **Via FTP/SFTP**: - - Upload changed files directly to the server - - Clear Joomla cache after deployment - -3. **Via Git** (Advanced): - - Push changes to a deployment branch - - Use Git hooks or CI/CD to deploy to production - - Ensure proper file permissions - -**Post-Deployment Checklist**: -- [ ] Clear Joomla cache (System → Clear Cache) -- [ ] Test homepage -- [ ] Test navigation and menus -- [ ] Verify custom colors appear correctly -- [ ] Test dark mode toggle -- [ ] Check mobile responsiveness -- [ ] Verify analytics tracking (if enabled) - ---- - -## 🛠 Local Development Setup - -### Setting Up a Local Joomla Environment - -1. **Install a local server stack**: - - **MAMP** (Mac/Windows): https://www.mamp.info/ - - **XAMPP** (Cross-platform): https://www.apachefriends.org/ - - **Docker**: https://github.com/joomla-docker/docker-joomla - -2. **Install Joomla**: - - Download Joomla from https://downloads.joomla.org/ - - Extract to your local server's web directory - - Follow the Joomla installation wizard - -3. **Install this template**: - - Copy files from this repository to your Joomla installation - - Or upload the ZIP package via Joomla's Extension Manager - -4. **Enable development mode**: - - Edit `configuration.php`: - ```php - public $debug = '1'; - public $error_reporting = 'maximum'; - ``` - -### Development Workflow - -1. **Make changes** to template files in your local Joomla installation -2. **Test changes** in your browser -3. **Copy changes back** to this repository: - ```bash - # From Joomla installation - cp [joomla]/templates/mokocassiopeia/* [repo]/src/templates/ - cp [joomla]/media/templates/site/mokocassiopeia/css/* [repo]/src/media/css/ - ``` -4. **Commit and push** to your fork -5. **Deploy** to staging/production when ready - -### Quick Testing Commands - -```bash -# Clear Joomla cache from command line -rm -rf [joomla]/cache/* -rm -rf [joomla]/administrator/cache/* - -# Watch for CSS changes (if using a build tool) -# npm run watch -``` - ---- - -## 📝 Customization Checklist - -Use this checklist when setting up or modifying your custom fork: - -### Initial Setup -- [ ] Fork the MokoCassiopeia repository -- [ ] Update this README with client name and details -- [ ] Configure custom brand colors -- [ ] Test light and dark modes -- [ ] Add custom code if needed -- [ ] Configure template settings in Joomla -- [ ] Set up analytics tracking (if required) -- [ ] Test on multiple devices and browsers - -### Ongoing Maintenance -- [ ] Sync with upstream periodically (monthly recommended) -- [ ] Review upstream changelog for breaking changes -- [ ] Test thoroughly after merging upstream updates -- [ ] Keep this README updated with customization notes -- [ ] Document any client-specific configurations -- [ ] Maintain backup before major updates - ---- - -## 📚 Documentation Resources - -### MokoCassiopeia Documentation - -- **[Main README](https://github.com/mokoconsulting-tech/MokoCassiopeia/blob/main/README.md)** - Features and overview -- **[CSS Variables Reference](./docs/CSS_VARIABLES.md)** - Complete CSS customization guide -- **[Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Development and testing -- **[Quick Start](./docs/QUICK_START.md)** - Quick setup guide -- **[Changelog](./CHANGELOG.md)** - Version history - -### Joomla Resources - -- **[Joomla Documentation](https://docs.joomla.org/)** - Official Joomla docs -- **[Joomla Templates](https://docs.joomla.org/J4.x:How_to_Create_a_Joomla_Template)** - Template development guide -- **[Cassiopeia Documentation](https://docs.joomla.org/J4.x:Cassiopeia)** - Parent template docs - ---- - -## 🔒 Security & Best Practices - -### Security Considerations - -1. **Keep Joomla Updated**: Always run the latest stable Joomla version -2. **Update Dependencies**: Regularly sync with upstream MokoCassiopeia for security patches -3. **Secure Custom Code**: Review all custom code for security vulnerabilities -4. **Use HTTPS**: Always serve production sites over HTTPS -5. **Regular Backups**: Maintain regular backups of both files and database - -### Best Practices - -1. **Version Control**: Commit changes frequently with clear messages -2. **Testing**: Always test changes locally before deploying to production -3. **Documentation**: Document all customizations in this README -4. **Code Review**: Have changes reviewed before deploying to production -5. **Staging Environment**: Use a staging site to test updates before production - ---- - -## 📞 Support & Contact - -### Client-Specific Support - -**Client Contact**: [CLIENT CONTACT INFO] -**Developer Contact**: [DEVELOPER CONTACT INFO] -**Hosting Provider**: [HOSTING INFO] - -### Upstream MokoCassiopeia Support - -- **Repository**: https://github.com/mokoconsulting-tech/MokoCassiopeia -- **Issues**: https://github.com/mokoconsulting-tech/MokoCassiopeia/issues -- **Documentation**: https://github.com/mokoconsulting-tech/MokoCassiopeia/blob/main/README.md -- **Moko Consulting**: https://mokoconsulting.tech - ---- - -## 📄 License - -This fork maintains the original GPL-3.0-or-later license from MokoCassiopeia. - -- **MokoCassiopeia**: GPL-3.0-or-later -- **Client Customizations**: GPL-3.0-or-later (or as specified by client agreement) -- **Third-Party Libraries**: See [Included Libraries](https://github.com/mokoconsulting-tech/MokoCassiopeia#-included-libraries) - ---- - -## 📊 Fork Information - -- **Upstream Repository**: https://github.com/mokoconsulting-tech/MokoCassiopeia -- **Fork Repository**: [YOUR-FORK-URL] -- **Client**: [CLIENT NAME] -- **Created**: [DATE] -- **Last Synced with Upstream**: [DATE] -- **Current Version**: 03.06.03 - ---- - -## 🔄 Revision History - -| Date | Version | Change Summary | Author | -|------|---------|----------------|--------| -| [DATE] | 03.06.03 | Initial fork setup with custom colors and branding | [YOUR NAME] | - ---- - -**Maintained by [CLIENT NAME] / [DEVELOPER NAME]** diff --git a/README.md b/README.md index 0d1610e..67b2e8a 100644 --- a/README.md +++ b/README.md @@ -332,11 +332,11 @@ See [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for packaging instr - **[Template Files](./templates/)** - Ready-to-use templates for customization - `colors_custom.css` - Custom color palette template - - `CLIENT_FORK_README_TEMPLATE.md` - Template for client fork documentation + - `gitignore-template` - .gitignore template for client forks ### Client Forks -- **[Client Fork Guide](./CLIENT_FORK_README.md)** - Comprehensive guide for creating and maintaining client custom code forks +- **[Client Fork Workflow Guide](./docs/CLIENT_FORK_WORKFLOW.md)** - Automated setup for client color customizations ### Governance @@ -406,16 +406,17 @@ See [Workflow Guide](./docs/WORKFLOW_GUIDE.md) for detailed Git workflow. ### Client Custom Forks -Creating a custom fork for client-specific branding and code? +Creating a custom fork for client-specific color branding? -**Quick Setup**: Use our automated workflow to create a client fork in minutes: +**Automated Workflow**: Use our streamlined workflow to create a client fork in minutes: - **[Client Fork Workflow Guide](./docs/CLIENT_FORK_WORKFLOW.md)** - Automated GitHub Actions workflow or local bash script -**Comprehensive Guide**: See our [Client Fork Guide](./CLIENT_FORK_README.md) for: -- Setting up custom color schemes -- Maintaining fork-specific customizations -- Syncing with upstream updates -- Deployment workflows +**What You Get**: +- Custom color files set up for light and dark modes +- .gitignore configured to track your custom colors +- Clean separation from upstream for easy syncing + +**For Other Customizations**: Use Joomla's built-in template settings (System → Site Templates → MokoCassiopeia → Custom Code tab) for HTML/CSS/JS customizations. --- diff --git a/docs/README.md b/docs/README.md index 6388659..ac9e318 100644 --- a/docs/README.md +++ b/docs/README.md @@ -102,12 +102,11 @@ For end-user documentation, installation instructions, and feature guides, see t * Complete setup automation in minutes * Post-setup customization guide -* **[Client Fork Guide](../CLIENT_FORK_README.md)** - Comprehensive guide for client custom code forks - * Setting up custom branding and colors - * Maintaining fork-specific customizations +* **[Client Fork Workflow Guide](./CLIENT_FORK_WORKFLOW.md)** - Automated setup for client color customizations + * Setting up custom brand colors for light and dark modes + * .gitignore template for tracking custom colors * Syncing with upstream MokoCassiopeia - * Deployment and development workflows - * Template README for client forks + * Limited scope: colors only (use Joomla's template settings for other customizations) ## Project Structure @@ -120,6 +119,7 @@ moko-cassiopeia/ │ ├── JOOMLA_DEVELOPMENT.md # Joomla-specific development guide │ ├── CSS_VARIABLES.md # CSS variables reference │ ├── MODULE_OVERRIDES.md # Module & component overrides guide +│ ├── CLIENT_FORK_WORKFLOW.md # Client fork creation workflow │ └── ROADMAP.md # Version-specific roadmap ├── src/ # Template source code (Joomla template root) │ ├── component.php # Component template @@ -131,8 +131,8 @@ moko-cassiopeia/ │ ├── media/ # Assets (CSS, JS, images, fonts) │ │ ├── css/ # Stylesheets │ │ │ └── colors/ # Color schemes -│ │ │ ├── light/ # Light mode color files (colors_standard.css, colors_custom.css) -│ │ │ └── dark/ # Dark mode color files (colors_standard.css, colors_custom.css) +│ │ │ ├── light/ # Light mode color files (colors_standard.css) +│ │ │ └── dark/ # Dark mode color files (colors_standard.css) │ │ ├── js/ # JavaScript files │ │ ├── images/ # Image assets │ │ └── fonts/ # Font files @@ -145,11 +145,10 @@ moko-cassiopeia/ │ └── en-US/ # English (US) system translations ├── templates/ # Template files for customization │ ├── colors_custom.css # Custom color palette template (copy to src/media/css/colors/) -│ ├── CLIENT_FORK_README_TEMPLATE.md # Template for client fork docs +│ ├── gitignore-template # .gitignore template for client forks │ └── README.md # Guide to using templates ├── scripts/ # Build and utility scripts ├── tests/ # Automated tests -├── CLIENT_FORK_README.md # Client fork guide └── .github/ # GitHub configuration and workflows ``` diff --git a/templates/CLIENT_FORK_README_TEMPLATE.md b/templates/CLIENT_FORK_README_TEMPLATE.md deleted file mode 100644 index 4b2d497..0000000 --- a/templates/CLIENT_FORK_README_TEMPLATE.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# [CLIENT NAME] - MokoCassiopeia Custom - -Custom Joomla template fork for **[CLIENT NAME]**. - ---- - -## 🎨 Custom Branding - -**Brand Colors**: -- Primary: `[COLOR]` -- Accent: `[COLOR]` -- Background: `[COLOR]` - -**Custom Files**: -- Light mode colors: `src/media/css/colors/light/colors_custom.css` -- Dark mode colors: `src/media/css/colors/dark/colors_custom.css` -- Custom PHP code: `src/templates/custom.php` - ---- - -## 🔄 Syncing with Upstream - -```bash -# Add upstream remote (first time only) -git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git - -# Sync with upstream -git fetch upstream -git merge upstream/main -``` - ---- - -## 📚 Documentation - -- **Full Client Fork Guide**: [CLIENT_FORK_README.md](../CLIENT_FORK_README.md) -- **MokoCassiopeia Docs**: https://github.com/mokoconsulting-tech/MokoCassiopeia -- **CSS Variables**: [docs/CSS_VARIABLES.md](../docs/CSS_VARIABLES.md) - ---- - -## 📝 Quick Notes - -[Add your client-specific notes here] - ---- - -**Fork of**: [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) v03.06.03 -**Last Synced**: [DATE] -**Contact**: [CONTACT INFO]