concept-image/wp-starter-theme

Base theme setup for WordPress with custom hooks and templates for Concept Image. Optimized for Roots Acorn.

3.1.0 2025-06-13 09:37 UTC

Requires

• php: >=8.3
• log1x/acf-composer: >=3.0
• roots/acorn: >=5.0

MIT

• Aurélien
• antoine

README

WP Starter Theme is a modern WordPress theme designed to provide a solid foundation for building custom themes. It leverages modern PHP practices and integrates seamlessly with the WordPress ecosystem.

Requirements

• WordPress 6.0 or later.
• PHP 8.0 or higher.
• Roots Acorn 4.3 or higher.

Installation

To install CI WP Starter Theme in your WordPress project using Roots Acorn, follow these steps:

1. Ensure you have Composer installed and initialized in your WordPress project. If you're using Bedrock, Composer is already set up.

2. Add the CI WP Starter Theme package to your project by running the following command in your terminal from your theme directory:

composer require concept-image/wp-starter-theme

Publishing Assets

After installing the theme, you need to discover and publish the theme's assets using Acorn. Run the following command:

wp acorn vendor:publish --tag="wp-starter-theme"

This command will publish the necessary assets to your theme's public directory.

Views, Styles, and Scripts

Views

The theme's view files are located in the resources/views directory. These files are responsible for rendering the HTML structure of your theme. You can customize these views to match your design requirements.

Styles

The theme's styles are located in the resources/styles directory. This directory contains all the CSS and SCSS files used to style your theme. You can add or modify these files to customize the appearance of your theme.

Scripts

The theme's scripts are located in the resources/scripts directory. This directory contains all the JavaScript files used to add interactivity to your theme. You can add or modify these files to enhance the functionality of your theme.

Vite

Install NPM depencies in the theme directory with the command:

npm install

Usage

Development:

To start the development server, run:

npm run dev

This will start the Vite development server on the specified port (default is 5173).

Build:

To build the project for production, run:

npm run build

Components

The theme comes with several pre-built components that help you create responsive and accessible websites.

Image Component

The Image component provides an enhanced way to handle WordPress images with automatic optimization and responsive attributes. It wraps WordPress's wp_get_attachment_image function with additional features:

<x-image :image="$imageId" size="medium_large" />
<x-image :image="$imageId" width="800" height="600" cover />
<x-image :image="$imageId" size="medium_large" eager />

Features:

• Dynamic sizing: Automatically determines the best image size based on provided width and height attributes
• Lazy loading: Images are lazy-loaded by default for better performance
• Priority loading: Easily mark images as high priority with the eager attribute
• Format-aware scaling: Intelligently handles different image formats (portrait/landscape) with the cover attribute
• Accessibility: Ensures proper alt text and other accessibility attributes are applied

Favicon Component

The Favicon component simplifies adding favicon and touch icon support to your site:

<x-favicon />

Features:

• Automatically adds all necessary favicon formats
• Supports standard favicon.ico, PNG formats, and SVG
• Includes Apple touch icons
• Integrates web manifest for PWA support

Figure Component

The Figure component combines images with optional captions in a semantic HTML structure:

<x-figure :image="$image" size="large" imageClass="rounded" />

Features:

• Wraps images in proper semantic <figure> elements
• Supports image captions using <figcaption>
• Works with the Image component to inherit all its features
• Applies default styling that can be easily customized

Configuration

The theme's configuration is handled through config files located in the theme/config directory. These files allow you to customize various aspects of the theme without modifying core files.

Theme Configuration (theme.php)

The theme.php configuration file allows you to customize core theme settings including:

return [
    'menus' => [
        'main-nav'        => __('Main Menu'),
        'footer-nav'      => __('Footer Menu'),
    ],
    
    'images' => [...],
    
    'tiny_mce' => [...],
    
    'disable' => [...],
    
    'gravity_forms' => [...],
    
    'supports' => [...],
    
    'textdomain' => 'your-textdomain',
];

Menu Registration

Define the navigation menus available in your theme:

'menus' => [
    'main-nav'            => __('Main Menu'),
    'secondary-nav'       => __('Secondary Menu'),
    'footer-nav'          => __('Footer Menu'),
    'footer-secondary-nav' => __('Legal Menu'),
],

Image Size Management

Control WordPress image sizes by removing default sizes and adding custom ones:

'images' => [
    'sizes_to_remove' => [
        '1536x1536',
        '2048x2048'
    ],
    'sizes_to_add' => [
        [
            'name' => 'image_hd',
            'width' => 1920,
            'height' => 0,
            'crop' => true
        ],
        [
            'name' => 'image_mobile',
            'width' => 425,
            'height' => 0,
            'crop' => true
        ],
    ],
],

TinyMCE Customization

Customize the WordPress editor with custom formats, styles, and toolbars:

'tiny_mce' => [
    'config' => [
        'block_formats' => 'Paragraph=p;Heading 2=h2;Heading 3=h3;',
        'style_formats' => [
            [
                'title' => __('Button Link'),
                'classes' => 'btnSolid btnSolid--arrow',
                'selector' => 'a'
            ],
            [
                'title' => __('Large Paragraph'),
                'classes' => 'text-h4',
                'selector' => 'p'
            ],
        ],
        'textcolor_map' => [
            "f869b7", "Primary Color",
        ],
    ],
    'toolbars' => [
        'Color' => [
            1 => ['forecolor']
        ],
    ],
],

Feature Management

Disable WordPress features you don't need for better performance:

'disable' => [
    'comments' => true,           // Disable comments functionality
    'search'   => true,           // Disable default WordPress search
    'disable_json_api' => true,   // Disable WP REST API
    'remove_json_api' => true,    // Remove REST API links from HTML
    'core_blocks' => true,        // Disable default Gutenberg blocks
    'default_post_type' => true,  // Disable default post type
    'heartbeat' => true,          // Disable WordPress heartbeat API
],

Plugin Integration

Configure plugin settings for better theme integration:

'gravity_forms' => [
    'disable_css' => true,        // Use theme styles instead of GF default
    'default_address' => env('GRAVITY_FORMS_DEFAULT_ADDRESS', ''),
],

Feature Flags

Enable/disable theme features as needed:

'supports' => [
    'breadcrumbs' => true,        // Enable breadcrumb navigation
],

Localization

Set the theme's text domain for translations:

'textdomain' => 'your-textdomain',

Assets Configuration (assets.php)

For assets configuration, see the Vite section of this documentation.

Hooks and Functions

The theme registers various hooks and functions through the provider located in the app/Providers/CiWpStarterThemeServiceProvider.php file. This provider is responsible for:

Registering theme support: Adds support for various WordPress features such as post thumbnails, custom logos, and more. Registering custom hooks: Adds custom hooks that can be used throughout the theme to extend functionality. Registering custom functions: Adds custom functions that can be used in your theme's templates and other files. You can customize the hooks and functions by modifying the CiWpStarterThemeServiceProvider.php file according to your needs.

Changelog

Please refer to CHANGELOG for more information.

Contributing

Please refer to CONTRIBUTING for more information.

License

Please refer to LICENSE for more information.