tailwind_wordpress_template WordPress Theme

A classic WordPress theme built with PHP templates and Tailwind CSS.

Theme Information

• Theme Name: tailwind_wordpress_template
• Author: xowei.tw
• Website: https://xowei.tw
• Version: 1.0.0
• Description: A traditional WordPress theme styled with Tailwind CSS

Table of Contents

• Quick Start
• Features
• Development Guide
• Project Structure
• Theme Settings
• Troubleshooting
• Changelog
• License
• Support

Quick Start

1) Install dependencies

Run these commands in the theme directory:

cd wp-content/themes/tailwind_wordpress_template
npm install

2) Build Tailwind CSS

Development mode (watch file changes):

npm run dev

Production mode (minified CSS):

npm run build

3) Activate the theme

1. Log in to the WordPress admin panel.
2. Go to Appearance > Themes.
3. Find tailwind_wordpress_template and click Activate.

4) Basic setup

• Menus: Go to Appearance > Menus, create or select a menu, then assign it to the main menu location.
• Widgets: Go to Appearance > Widgets, then add widgets to the sidebar or footer widget areas.
• Logo (optional): Go to Appearance > Customize > Site Identity and upload a logo.

Features

Supported

• Traditional PHP template system (not block templates)
• Tailwind CSS utility-first styling
• Responsive layout for different devices
• Built-in CSS/JS cache-busting by file modification time
• Custom logo support
• Sticky post support (including archive pages)
• Contact info management (phone, email, LINE, social links)
• Dedicated page templates (about, contact, donate)
• Post-type specific templates (podcast, youtube)
• Reusable template parts (template-parts/)
• Utility function library (utils/)

Simplified / Not included

To keep the theme simple, these default customizer design options are removed:

• Custom background
• Custom header image
• Extra visual design controls in Appearance > Customize

Use Tailwind classes in templates for visual customization.

Sticky posts

Sticky posts are fully supported:

• They appear first on the home page.
• They also appear first on archive pages (category/tag/search), through theme customization.
• A yellow sticky label is displayed for sticky posts.

Example sticky label markup:

<span class="inline-block bg-yellow-400 text-yellow-900 text-xs font-semibold px-2 py-1 rounded mb-2">Sticky</span>

Development Guide

Requirements

• Node.js (recommended v18+)
• npm
• WordPress 6.0+
• PHP 7.4+

Tailwind workflow

• Use utility classes directly in PHP templates whenever possible.
• Add custom CSS only when utility classes cannot cover your needs.
• Main input file: src/input.css
• Output file: assets/css/style.css

Example:

<div class="container mx-auto px-4 py-12">
    <h1 class="text-3xl font-bold text-gray-900">Title</h1>
    <p class="text-gray-600 mt-4">Content</p>
</div>

Responsive example:

<div class="w-full md:w-1/2 lg:w-1/3">
    <!-- Full width on small screens, half on medium, one-third on large -->
</div>

Cache-busting version system

This theme uses file modification time as asset version:

• When CSS/JS files are updated, the version changes automatically.
• WordPress appends a query string like ?ver=1704067200.
• Browsers fetch the latest file instead of using stale cache.

Concept example:

$css_version = tailwind_wordpress_template_get_file_version('assets/css/style.css');
wp_enqueue_style(
    'tailwind_wordpress_template-style',
    get_template_directory_uri() . '/assets/css/style.css',
    array(),
    $css_version,
    'all'
);

Best practices

1. Prefer Tailwind utility classes over custom CSS.
2. Use responsive prefixes (sm:, md:, lg:, xl:).
3. Use npm run build for production deployments.
4. Keep template and utility files modular and reusable.

Project Structure

tailwind_wordpress_template/
├── 404.php
├── README.md
├── archive.php
├── assets/
│   ├── css/style.css
│   ├── images/
│   │   └── icons/
│   └── js/main.js
├── comments.php
├── content.php
├── footer.php
├── functions.php
├── header.php
├── index.php
├── node_modules/
├── package-lock.json
├── package.json
├── page.php
├── screenshot.png
├── search.php
├── searchform.php
├── sidebar.php
├── single.php
├── src/
│   ├── components/
│   │   ├── _entry-content.css
│   │   ├── _pagination.css
│   │   ├── _slider.css
│   │   └── index.css
│   ├── input.css
│   └── layout/
│       ├── _base.css
│       ├── _content.css
│       ├── _footer.css
│       ├── _header.css
│       └── index.css
├── style.css
├── tailwind.config.js
├── template-parts/
│   ├── content-featured-image-cover.php
│   ├── content-gospel-card.php
│   ├── content-page-hero.php
│   ├── content-post-card.php
│   ├── content-readmore-button.php
│   ├── content-section-title.php
│   ├── content-slider-card.php
│   ├── content-slider.php
│   └── pagination.php
└── utils/
    ├── classnames.php
    ├── content-helper.php
    ├── icon-helper.php
    └── tabs-helper.php

Theme Settings

WordPress Admin > Settings > General

This theme provides custom fields such as:

• Default image (for posts without featured image)
• Footer HTML text
• LINE ID and LINE URL
• Contact phone number(s)
• Contact email
• Facebook URL
• Instagram URL
• YouTube URL
• Spotify URL
• External links HTML (shown in footer)

These values are used automatically in the footer and contact page template.

WordPress Admin > Settings > Discussion

• Disable comments site-wide (tailwind_wordpress_template_disable_comments)
  • Hides comment UI in admin screens.
  • Disables comment and ping support for public post types.
  • Prevents comment display on the frontend.

WordPress Admin > Settings > Writing

• Use Classic Editor (tailwind_wordpress_template_use_classic_editor)
  • When enabled, posts and pages use Classic Editor instead of Block Editor (Gutenberg).
  • This option can be switched on/off without installing extra plugins.

Sticky post setup

You can set sticky posts in either:

• Post editor (Status and Visibility section), or
• Quick Edit in post list.

Troubleshooting

CSS does not update

1. Run npm run dev or npm run build.
2. Confirm assets/css/style.css changed.
3. Hard refresh browser cache.

Asset version does not update

1. Check file path correctness.
2. Check file permissions.
3. Check tailwind_wordpress_template_get_file_version() in functions.php.

Tailwind class has no effect

1. Ensure CSS is compiled.
2. Verify content paths in tailwind.config.js include all relevant PHP files.
3. Confirm compiled CSS is loaded in browser dev tools.

Theme does not appear in WordPress

1. Ensure required files exist (style.css, functions.php).
2. Ensure style.css header metadata is valid.
3. Check file permissions.

Changelog

1.0.0

• Initial release
• Base template structure
• Tailwind CSS integration
• Built-in cache-busting version mechanism

License

Developed by xowei.tw. All rights reserved.

Support

For questions or suggestions, please contact: xowei.tw