Theme Development Workflow

Theme Development Workflow

This guide provides a step-by-step workflow for developing themes in FearlessCMS, from initial setup to final deployment.

Prerequisites

Before starting theme development, ensure you have:

• A working FearlessCMS installation
• Basic knowledge of HTML, CSS, and JavaScript
• A code editor (VS Code, Sublime Text, etc.)
• Basic understanding of responsive design principles

Development Environment Setup

1. Create Theme Directory

bash
Navigate to your FearlessCMS themes directory
cd themes/
Create your theme directory
mkdir my-theme
cd my-theme
Create required subdirectories
mkdir templates
mkdir assets
mkdir assets/images
mkdir assets/js

2. Initialize Theme Files

Create the basic theme structure:

bash
Create theme configuration
touch theme.json
touch config.json
touch README.md
Create template files
touch templates/home.html
touch templates/page.html
touch templates/blog.html
touch templates/404.html
Create assets
touch assets/style.css
Placeholder for thumbnail (add actual image later)
thumbnail.png or screenshot.png will go here
touch assets/theme.js

Step-by-Step Development Process

Step 1: Define Theme Configuration

Start by creating your theme.json:

json
{
    "name": "My Awesome Theme",
    "description": "A modern, responsive theme for blogs and websites",
    "version": "1.0.0",
    "author": "Your Name",
    "license": "MIT",
    "templates": {
        "home": "home.html",
        "page": "page.html",
        "blog": "blog.html",
        "404": "404.html"
    }
}

Step 2: Create Basic Templates

Start with a simple templates/page.html:

html



    
    
    
    




    

        
{{title}}
    
    
    

        {{content}}
    
    
    

Step 3: Add Basic Styling

Create assets/style.css:

css
/ Reset and base styles /
 {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}
body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    line-height: 1.6;
    color: #333;
}
/ Layout /
header, main, footer {
    padding: 2rem;
}
/ Typography /
h1 {
    font-size: 2.5rem;
    margin-bottom: 1rem;
}
/ Responsive /
@media (max-width: 768px) {
    h1 {
        font-size: 2rem;
    }
}

Step 4: Test Your Theme

• Activate the theme in the admin panel
• Create a test page with some content
• View the page in your browser
• Check for errors in browser console

Step 5: Iterate and Improve

Based on your testing, improve the theme:

• Fix layout issues
• Improve typography
• Add responsive design
• Enhance visual appeal

Step 6: Add Theme Options

Create config.json for customizable options:

json
{
    "options": {
        "logo": {
            "type": "image",
            "label": "Logo Image",
            "description": "Upload your site logo"
        },
        "primaryColor": {
            "type": "color",
            "label": "Primary Color",
            "default": "#007bff"
        },
        "showSidebar": {
            "type": "checkbox",
            "label": "Show Sidebar",
            "default": true
        }
    }
}

Step 7: Implement Advanced Features

Add more sophisticated features:

• Navigation menus
• Blog functionality
• Search capability
• Social media integration
• Custom JavaScript

Development Best Practices

1. Start Simple

Begin with a basic, functional theme and add features gradually:

html




    
    




    
{{siteName}}
    
{{content}}
    

2. Use Modular Templates

As your theme grows, break it into reusable components using the modular template system:

html




    {{module=head.html}}




    {{module=header.html}}
    

        {{module=hero-banner.html}}
        

            {{module=sidebar.html}}
        
    
    {{module=footer.html}}

Benefits of modular templates:

• Maintainability: Common elements in single files
• Reusability: Use modules across multiple templates
• Consistency: Changes update everywhere automatically
• Organization: Cleaner, more organized code structure

Common modules to create:

• head.html - HTML head section
• header.html - Site header with navigation
• footer.html - Site footer
• navigation.html - Navigation menus
• sidebar.html - Sidebar content
• hero-banner.html - Hero banner sections

For detailed information, see the Modular Templates Guide.

3. Use Semantic HTML

Always use proper HTML5 semantic elements:

html

    

    

        

            
{{title}}
        
        

            {{content}}
        
    

4. Mobile-First Design

Start with mobile styles and add desktop enhancements:

css
/ Mobile first /
.container {
    padding: 1rem;
}
/ Tablet and up /
@media (min-width: 768px) {
    .container {
        padding: 2rem;
        max-width: 1200px;
        margin: 0 auto;
    }
}
/ Desktop /
@media (min-width: 1024px) {
    .container {
        padding: 3rem;
    }
}

5. Use CSS Custom Properties

Make your theme easily customizable:

css
:root {
    --primary-color: #007bff;
    --secondary-color: #6c757d;
    --text-color: #333;
    --bg-color: #fff;
    --border-color: #e9ecef;
}
.button {
    background-color: var(--primary-color);
    color: white;
    padding: 0.5rem 1rem;
    border: none;
    border-radius: 4px;
}
.card {
    background-color: var(--bg-color);
    border: 1px solid var(--border-color);
    border-radius: 8px;
    padding: 1rem;
}

6. Progressive Enhancement

Add JavaScript features progressively:

html

Testing Your Theme

1. Content Testing

Test with different types of content:

• Short pages (just a title and paragraph)
• Long pages (lots of content)
• Pages with images
• Pages with lists and tables
• Blog posts with different formats

2. Browser Testing

Test in multiple browsers:

• Chrome/Chromium
• Firefox
• Safari
• Edge

3. Device Testing

Test on different devices:

• Mobile phones (portrait and landscape)
• Tablets (portrait and landscape)
• Desktop computers (different screen sizes)

4. Performance Testing

Check theme performance:

• Page load speed
• CSS file size
• JavaScript execution time
• Image optimization

Debugging Tips

1. Use Browser Developer Tools

• Inspect elements to see how CSS is applied
• Check console for JavaScript errors
• Use network tab to see if files are loading
• Test responsive design with device simulation

2. Add Debug Output

Temporarily add debug information to your templates:

html


    Debug Info:

    Title: {{title}}

    URL: {{url}}

    Theme: {{theme}}

    Children: {{#if children}}Yes{{else}}No{{/if}}

3. Check File Permissions

Ensure your theme files have proper permissions:

bash
chmod 644 assets/style.css
chmod 644 templates/.html
chmod 644 theme.json
chmod 644 config.json

Version Control

1. Initialize Git Repository

bash
cd themes/my-theme
git init

2. Create .gitignore

bash
.gitignore
.DS_Store
.log
node_modules/
Add any build tool directories if you use them
.sass-cache/
dist/
build/

3. Make Initial Commit

bash
git add .
git commit -m "Initial theme commit"

Creating Theme Thumbnails

Before deploying your theme, create a thumbnail image for the admin panel preview:

1. Prepare Your Theme for Screenshot

bash
Ensure theme is active and properly styled
Add sample content to showcase the theme
Test at desktop resolution (1200px+ width)

2. Capture the Thumbnail

• Open your theme in a browser at desktop resolution
• Navigate to homepage or most representative page
• Take a screenshot of the full viewport
• Crop to 1200x675px (16:9 aspect ratio)
• Optimize the image to keep under 500KB
• Save as thumbnail.png in your theme root directory

3. Thumbnail Best Practices

bash
Good thumbnail characteristics:
- Shows homepage or main layout
- High resolution and clear quality
- Realistic sample content (not Lorem Ipsum)
- Proper lighting and contrast
- Highlights theme's unique features

4. Test Thumbnail Display

• Refresh admin panel to see the thumbnail
• Check grid layout - ensure it displays properly
• Test modal view - click to view larger version
• Verify fallback - temporarily rename file to test placeholder

5. Thumbnail File Requirements

• Filename: thumbnail.png, thumbnail.jpg, screenshot.png, or screenshot.jpg
• Dimensions: 1200x675px (recommended)
• Format: PNG (preferred), JPG, JPEG, GIF, or WebP
• Size: Under 500KB for optimal performance
• Location: Theme root directory (same level as config.json)

Deployment

1. Package Your Theme

Create a clean distribution:

bash
Verify thumbnail is present
ls -la thumbnail.png  # or thumbnail.jpg, screenshot.png, etc.
Remove development files
rm -rf .git
rm -rf node_modules
Remove any build tool directories
rm -rf .sass-cache
rm -rf dist
rm -rf build
Create zip file (include thumbnail)
zip -r my-theme-v1.0.0.zip . -x ".git" "node_modules/"

2. Install in FearlessCMS

• Upload the theme to your FearlessCMS installation
• Extract to the themes/ directory
• Verify thumbnail appears in admin themes section
• Activate the theme in admin panel
• Configure theme options
• Test thoroughly

Maintenance

1. Keep Dependencies Updated

Regularly update any external dependencies:

• CSS frameworks
• JavaScript libraries
• Font files

2. Monitor Performance

Track theme performance over time:

• Page load speeds
• User feedback
• Browser compatibility issues

3. Version Management

Use semantic versioning for your theme:

• Major version (1.0.0 → 2.0.0): Breaking changes
• Minor version (1.0.0 → 1.1.0): New features
• Patch version (1.0.0 → 1.0.1): Bug fixes

Example: Complete Development Session

Here's an example of a complete development session:

bash
1. Create theme structure
mkdir -p themes/my-blog-theme/{templates,assets/{css,js,images}}
2. Create basic files
cd themes/my-blog-theme
touch theme.json config.json README.md
touch templates/{home,page,blog,404}.html
touch assets/css/style.css assets/js/theme.js
3. Edit theme.json
cat > theme.json << 'EOF'
{
    "name": "My Blog Theme",
    "description": "A clean blog theme",
    "version": "1.0.0",
    "author": "Your Name",
    "license": "MIT",
    "templates": {
        "home": "home.html",
        "page": "page.html",
        "blog": "blog.html",
        "404": "404.html"
    }
}
EOF
4. Create basic template
cat > templates/page.html << 'EOF'



    
    
    
    




    

        
{{title}}
    
    
{{content}}
    


EOF
5. Add basic CSS
cat > assets/css/style.css << 'EOF'
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: sans-serif; line-height: 1.6; padding: 2rem; }
EOF
6. Test the theme
- Activate in admin panel
- Create test content
- View in browser
- Debug any issues
7. Iterate and improve
- Add more styling
- Implement responsive design
- Add theme options
- Test thoroughly

This workflow ensures you create a robust, maintainable theme that works well across different devices and content types.