FearlessCMS Theme Development Documentation

Welcome to the FearlessCMS theme development documentation! This collection of guides will help you create beautiful, functional themes for FearlessCMS.

📚 Documentation Index

Getting Started

Customization Overview - Complete guide to all customization options
Creating Themes in FearlessCMS - Complete guide to creating themes from scratch
Theme Development Workflow - Step-by-step development process and best practices

Reference Guides

Template Reference - Complete template syntax and variable reference
Theme Options Guide - How to implement and use theme options
Modular Templates - How to use the modular template system for better code organization
Global UI Enhancements - Optional hamburger and theme toggle controls

System Administration

CMS Modes Guide - How to configure and manage CMS operational modes
File Permissions Guide - Setting up proper file permissions and ownership
Ad Area System - Conditional advertising system for hosting service modes

Examples and Tutorials

Nightfall Theme Example - Real-world example of a complete theme
Theme Examples - Browse all available themes for inspiration

🚀 Quick Start

Read the Basics: Start with Creating Themes in FearlessCMS
Follow the Workflow: Use Theme Development Workflow for step-by-step guidance
Reference Syntax: Check Template Reference for all available variables and syntax
Add Options: Learn about Theme Options to make your theme customizable
Go Modular: Explore Modular Templates for better code organization

🎯 What You'll Learn

How to create a complete theme from scratch
Template system and variable usage
Modular template system for reusable components
Implementing theme options for customization
Responsive design principles
Best practices for theme development
Testing and deployment strategies
CMS modes and system administration
File permissions and security best practices
Ad area system integration for hosting services

📁 Theme Structure

A typical FearlessCMS theme includes:

themes/your-theme/
├── templates/
│   ├── home.html      # Homepage template
│   ├── page.html      # Individual page template
│   ├── blog.html      # Blog listing template
│   ├── 404.html       # Error page template
│   ├── header.html    # Header module (modular system)
│   ├── footer.html    # Footer module (modular system)
│   └── navigation.html # Navigation module (modular system)
├── assets/
│   ├── style.css      # Main stylesheet
│   ├── images/        # Theme images
│   └── js/           # JavaScript files
├── theme.json        # Theme metadata
├── config.json       # Theme options (optional)
└── README.md         # Theme documentation

🔧 Key Features

Simple Template System: Easy-to-learn syntax with powerful features
Modular Templates: Break down templates into reusable components with {{module=filename.html}}
Theme Options: User-friendly customization without code editing
Responsive Design: Built-in support for mobile-first design
Extensible: Add custom functionality with JavaScript
SEO-Friendly: Semantic HTML and meta tag support
Ad Area Integration: Automatic conditional advertising for hosting service modes

Global UI Enhancements (Optional)

FearlessCMS can optionally inject two small UI features across themes:

A responsive hamburger button that toggles the main nav under 900px
A theme mode toggle (System → Light → Dark) that stores preference in localStorage and applies it via data-theme on <html>

Enabling/Disabling

Site-level flags in config/config.json (defaults shown):

{
  "global_ui_enhancements": true,
  "enable_hamburger": true,
  "enable_theme_toggle": true
}

Theme-level flags in themes/<theme>/config.json:

{
  "disableGlobalEnhancements": false,
  "disableHamburger": false,
  "disableThemeToggle": false,
  "supportsDarkMode": true
}

To quickly disable on a page/theme without changing JSON, add in your head module:

<meta name="fcms-disable-global-ui" content="1">

Requirements

Your header should contain a nav. If .header-inner exists, controls appear before nav inside it; otherwise they appear before nav in header.
For themes without dark mode, set supportsDarkMode: false or disableThemeToggle: true to hide the toggle.

Accessibility

Buttons are keyboard-focusable and announce state (aria-expanded for hamburger).
Dark/light/system preference persists per browser via localStorage (fcms-theme).

💡 Tips for Success

Start Simple: Begin with a basic, functional theme
Use Modular Templates: Break down complex templates into reusable modules
Test Thoroughly: Check on different devices and browsers
Use Semantic HTML: Follow web standards for better accessibility
Mobile-First: Design for mobile devices first, then enhance for desktop
Document Everything: Include clear documentation for users

🤝 Contributing

Found an issue or have a suggestion? Contributions are welcome! Please:

Check existing issues first
Follow the established documentation style
Test your changes thoroughly
Submit clear, descriptive pull requests

📖 Additional Resources

FearlessCMS Main Documentation
Admin Panel Guide
Plugin Development Guide
CMS Modes Guide - System administration and deployment modes
File Permissions Guide - Security and permission setup
Ad Area System - Conditional advertising features
API Reference

🆘 Getting Help

If you need help with theme development:

Check the documentation - Most questions are answered here
Look at examples - Browse existing themes for inspiration
Search issues - Check if your question has been asked before
Ask the community - Join discussions in the project forums

🔒 Security Note: Config Directory Location

FearlessCMS supports storing your configuration files outside the webroot for enhanced security. Set the FCMS_CONFIG_DIR environment variable to point to a secure directory. See File Permissions Guide for details.

Happy theme development! 🎨

This documentation is maintained by the FearlessCMS community. Last updated: January 2025