Skip to content

USAGE.md

Latest commit

 

History

History
326 lines (223 loc) · 9.61 KB

USAGE.md

File metadata and controls

326 lines (223 loc) · 9.61 KB
title {{name}} - Usage Guide
version {{version}}
last_updated 2024-10-18
author {{author}}
description User guide for {{name}}
type documentation

Usage Guide

This guide explains how to use the {{name}} in your WordPress site.

Installation

From WordPress Admin

  1. Download the plugin ZIP file from the releases page
  2. In your WordPress admin, go to Plugins > Add New
  3. Click Upload Plugin and select the ZIP file
  4. Click Install Now and then Activate

Manual Installation

  1. Download and extract the plugin files
  2. Upload the {{plugin_slug}} folder to /wp-content/plugins/
  3. Activate the plugin through the Plugins menu in WordPress

Via Composer

composer require {{author}}/{{plugin_slug}}

Getting Started

Once activated, the {{name}} blocks will be available in the WordPress block editor.

Adding Blocks

  1. Open the block editor for any post or page
  2. Click the (+) button to add a new block
  3. Search for "{{name}}" or find blocks in the Widgets category
  4. Click to insert the block

Basic Configuration

Each block provides several options for customization:

Content Settings

  • Text Content: Enter your text in the rich text editor
  • Text Alignment: Choose left, center, or right alignment
  • Formatting: Use bold, italic, links, and strikethrough

Design Settings

The blocks support WordPress's design tools:

  • Colors: Set text and background colors
  • Typography: Adjust font size, family, and style
  • Spacing: Configure margins and padding
  • Borders: Add borders with custom colors and radius

Block Controls

Toolbar Controls

When a block is selected, you'll see toolbar controls for:

  • Text Alignment: Quick alignment buttons
  • Text Formatting: Bold, italic, link, strikethrough
  • More Options: Additional block settings

Sidebar Controls

In the block settings sidebar, you'll find:

  • Block Settings Panel: Core block options
  • Color Settings: Text and background color options
  • Typography Settings: Font and text styling
  • Dimensions Settings: Spacing and border options

Advanced Usage

Styling and Customization

Theme Integration

The blocks are designed to integrate seamlessly with your theme:

  • Inherits theme colors from your theme palette
  • Respects theme typography settings
  • Follows theme spacing conventions
  • Supports theme.json configuration

Custom CSS

You can add custom styles using WordPress's Additional CSS feature:

/* Target the block wrapper */
.wp-block-{{namespace}}-{{block_slug}} {
    /* Your custom styles */
}

/* Target the content area */
.wp-block-{{namespace}}-{{block_slug}}__content {
    /* Content-specific styles */
}

/* Alignment variations */
.wp-block-{{namespace}}-{{block_slug}}.has-text-align-left {
    /* Left-aligned styles */
}

Block Patterns

Create reusable patterns with the blocks:

  1. Create your design using the blocks
  2. Select the block(s) you want to save
  3. Go to Patterns > Create Pattern
  4. Name your pattern and choose categories
  5. Save and reuse across your site

Accessibility Features

The {{name}} blocks are built with accessibility in mind:

Keyboard Navigation

  • Tab navigation through interactive elements
  • Enter/Space to activate buttons
  • Arrow keys for text alignment selection
  • Escape to exit menus and dialogs

Screen Reader Support

  • Proper ARIA labels for all controls
  • Descriptive text for screen readers
  • Focus management for modal dialogs
  • Semantic HTML structure

Color Contrast

  • Automatic contrast checking in the editor
  • Warnings for poor contrast combinations
  • Support for high contrast mode
  • Respects user preferences for reduced motion

Performance Considerations

The blocks are optimized for performance:

Loading

  • Lightweight CSS - only essential styles are loaded
  • Conditional loading - scripts only load when needed
  • Minified assets in production
  • Browser caching support

Best Practices

  • Use sparingly - don't overload pages with too many blocks
  • Optimize images if using background images
  • Test on mobile devices for performance
  • Monitor Core Web Vitals metrics

Troubleshooting

Common Issues

Block Not Appearing

  1. Check plugin activation - ensure the plugin is active
  2. Clear caches - if using caching plugins
  3. Check theme compatibility - try with a default theme
  4. Update WordPress - ensure you're using WordPress 6.0+

Styling Issues

  1. Theme conflicts - some themes may override block styles
  2. Plugin conflicts - deactivate other plugins to test
  3. Custom CSS - may be interfering with block styles
  4. Browser caching - clear browser cache and hard refresh

Performance Issues

  1. Too many blocks - reduce the number of blocks on the page
  2. Large content - break up very long content
  3. Plugin conflicts - check for poorly coded plugins
  4. Hosting resources - ensure adequate server resources

Getting Support

If you encounter issues:

  1. Check the FAQ below for common solutions
  2. Search existing issues on GitHub
  3. Create a new issue with detailed information
  4. Contact support - see SUPPORT.md for options

Frequently Asked Questions

Can I use these blocks in widgets?

Yes, the blocks work in any area that supports blocks, including:

  • Widget areas (if your theme supports block widgets)
  • Full Site Editing template areas
  • Custom post types that support blocks

Does it work with page builders?

The blocks are designed for the WordPress block editor. Compatibility with page builders depends on whether they support WordPress blocks.

Can I customize the styling?

Yes, you can customize styling through:

  • WordPress's built-in design tools
  • Theme customizer options
  • Custom CSS
  • Child theme modifications

Is it translation ready?

Yes, the plugin is fully internationalized and ready for translation. Translation files can be contributed via WordPress.org.

Does it support RTL languages?

Yes, the blocks support right-to-left (RTL) languages and will automatically adjust their layout accordingly.

Can I use it in Classic Editor?

The blocks are designed for the block editor (Gutenberg). For Classic Editor support, you would need to use shortcodes or widgets.

Is it compatible with my theme?

The blocks are designed to work with any properly coded WordPress theme. If you experience compatibility issues, please report them.

How do I update the plugin?

Updates are delivered through WordPress's standard update system:

  1. You'll see update notifications in your admin
  2. Click Update to install the latest version
  3. Always backup your site before updating

Can I contribute to development?

Yes! See CONTRIBUTING.md for information on how to contribute code, translations, or documentation.

Examples

Basic Usage

<!-- wp:{{namespace}}/{{block_slug}} {"content":"Hello World","alignment":"center"} -->
<div class="wp-block-{{namespace}}-{{block_slug}} has-text-align-center">
    <div class="wp-block-{{namespace}}-{{block_slug}}__content">
        <p>Hello World</p>
    </div>
</div>
<!-- /wp:{{namespace}}/{{block_slug}} -->

With Custom Colors

<!-- wp:{{namespace}}/{{block_slug}} {"content":"Styled content","textColor":"primary","backgroundColor":"secondary"} -->
<div class="wp-block-{{namespace}}-{{block_slug}} has-primary-color has-secondary-background-color has-text-color has-background">
    <div class="wp-block-{{namespace}}-{{block_slug}}__content">
        <p>Styled content</p>
    </div>
</div>
<!-- /wp:{{namespace}}/{{block_slug}} -->

In a Pattern

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- wp:{{namespace}}/{{block_slug}} {"content":"Pattern Example","alignment":"center"} -->
    <div class="wp-block-{{namespace}}-{{block_slug}} has-text-align-center">
        <div class="wp-block-{{namespace}}-{{block_slug}}__content">
            <p>Pattern Example</p>
        </div>
    </div>
    <!-- /wp:{{namespace}}/{{block_slug}} -->
</div>
<!-- /wp:group -->

Best Practices

Content Strategy

  • Keep content concise - blocks work best with focused content
  • Use appropriate headings - maintain proper document structure
  • Consider mobile users - ensure content is readable on small screens
  • Test accessibility - use screen readers and keyboard navigation

Design Guidelines

  • Maintain consistency - use consistent colors and typography
  • Follow theme patterns - align with your site's overall design
  • Consider contrast - ensure text is readable against backgrounds
  • Responsive design - test on multiple screen sizes

Performance Tips

  • Optimize content - avoid unnecessarily large content
  • Use caching - implement proper caching strategies
  • Monitor metrics - track Core Web Vitals and page speed
  • Regular maintenance - keep WordPress and plugins updated

Related Resources