Stars: 118
Forks: 192
Pull Requests: 26
Issues: 99
Watchers: 12
Last Updated: 2021-08-10 20:07:06
Add subtitles into your WordPress posts, pages, custom post types, and themes. No coding required. Simply activate Subtitles and you're ready to go.
License: GNU General Public License v2.0
Languages: JavaScript, PHP, CSS
Add subtitles into your WordPress posts, pages, custom post types, and themes. No coding required. Simply activate Subtitles and you're ready to go.
Right now WordPress currently presents no easy way for web publishers to add subtitles into their posts, pages, and other custom post types. This leaves users and developers in a bit of a quandary, trying to figure out how best to present subtitles in a beautiful and sensible way. Post excerpts are a very poor choice for subtitles and the only available option outside of custom fields, but custom fields aren't entirely self-explanatory or user-friendly. This simple, straightforward plugin aims to solve this issue.
Simply download Subtitles, activate it, and begin adding subtitles into your posts and pages today. For more advanced usage of the plugin, please see the Frequently Asked Questions.
If you like Subtitles, thank us with coffee ☕. If you find it buggy, tell us on GitHub 🪲. And if you have a cool example of how you're using Subtitles on your website, let us know on Twitter 🐦.
By default the Subtitles plugin just works. All you should need to do in order to begin using it is activate the plugin and begin adding subtitles into your posts, pages, and Subtitles-enabled custom post types.
There are no custom template tags to add into your theme and, outside of advanced use, there is nothing you need to do to your theme in order to begin using this plugin.
What follows are instructions on how to install the plugin and get it working.
subtitles
.subtitles.zip
in its download location on your computer.subtitles.zip
.subtitles
directory to your computer.subtitles
directory to your /wp-content/plugins/
directory.There are two types of questions that are anticipated: user questions and developer questions. I'll address the user questions first, and then dive into more detailed information about customizing Subtitles.
Subtitles lets you easily add subtitles into your WordPress posts, pages, custom post types, and themes.
After plugin activation, you should see an input field labeled Enter subtitle here immediately under your Enter title here input field. After adding a subtitle into your post, simply hit publish and then view your post. There's nothing else to do.
When you uninstall Subtitles, nothing will happen to your subtitles post meta. They'll still be retained in your database, so if you ever decide to use Subtitles again, you'll be able to activate the plugin and have your subtitles show up. In a future release, there may be the option to clean subtitles out of your database, but it didn't make the cut for the initial release, and auto-deleting the data on uninstallation would have been a bad move, as subtitles are non-trivial post meta.
There are two primary issues that may cause users to think that Subtitles doesn't work: 1) no subtitles show on the site or 2) weird HTML begins to appear around titles on a site. We will address both of those here.
Subtitles relies on two things to work properly: 1) the_title
being present in your theme and 2) the WordPress Loop. This plugin works by automatically filtering all appropriate post titles so that you are not put in the position of needing to open your theme files manually and using the custom template tags that are available in this plugin.
Some themes use titles outside of the standard WordPress Loop, which means that Subtitles won't touch those. If you would like to use subtitles in a non-standard area of your site, outside of the Loop, then you can either change the views that are supported by the plugin or manually use the template tags that are available to you in this plugin.
The reason this approach has been taken is because if titles outside of the Loop were touched so liberally, you would end up seeing subtitles in places on your site that you wouldn't want them, like in sidebars, navigation menus, and admin screens.
I can almost guarantee that the reason this is happening is because your theme developer is using either the_title
or get_the_title
in places where they should not be used. This is a theme bug, not a plugin bug. When titles are used as attributes, the appropriate template tag to use is the_title_attribute
, never the_title
.
Please see these long threads as examples of what happens when themes conflict with Subtitles.
Will Subtitles ruin your SEO? That's a fair question. The answer is no. We've made a note of exactly why <spans>
are the default wrappers for subtitles in the inline developer docs for the plugin, which I'll reiterate here:
* 4. Visually, we have made a major assumption that subtitles belong immediately after titles. The very
* definition of a subtitle is that it is a subordinate title of a published work that often gives
* explanatory details about the immediately preceeding title. It's for this reason that we've chosen
* to filter the output of the_title() with the expectation that post titles will be wrapped in
* primary heading (h1) tags. So post titles will be H1, while their subtitles will be spans.
* Multiple H1 tags in the HTML5 age are okay.
* 5. The reason that <spans> are being used is because HTML does not have a dedicated mechanism for
* marking up subheadings, alternative titles, or taglines. There are suggested alternatives from
* the World Wide Web Consortium (W3C); among them are spans, which work well for what we're trying
* to do with titles in WordPress. See the linked documentation for more information.
* @link http://www.w3.org/html/wg/drafts/html/master/common-idioms.html#sub-head
If you're worried about SEO and the markup of Subtitles, then roll your own markup.
As of version 2.0.0, Subtitles outputs its CSS via wp_head
. This is to load sensible CSS that will ensure your subtitle is always scaled properly alongside your website title and never shown in comment areas.
/**
* Plugin Name: Subtitles
* Plugin URI: http://wordpress.org/plugins/subtitles/
* Description: Easily add subtitles into your WordPress posts, pages, custom post types, and themes.
* Author: We Cobble
* Author URI: https://wecobble.com/
* Version: 2.1.1
* License: GNU General Public License v2 or later
* License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/
/**
* Be explicit about this styling only applying to spans,
* since that's the default markup that's returned by
* Subtitles. If a developer overrides the default subtitles
* markup with another element or class, we don't want to stomp
* on that.
*
* @since 1.0.0
*/
span.entry-subtitle {
display: block; /* Put subtitles on their own line by default. */
font-size: 0.53333333333333em; /* Sensible scaling. It's assumed that post titles will be wrapped in heading tags. */
}
/**
* If subtitles are shown in comment areas, we'll hide them by default.
*
* @since 1.0.5
*/
#comments .comments-title span.entry-subtitle {
display: none;
}
If you'd like to remove this additional CSS, then simply add a similar function to the following in your plugin or theme's primary setup file:
if ( class_exists( 'Subtitles' ) && method_exists( 'Subtitles', 'subtitle_styling' ) ) {
remove_action( 'wp_head', array( Subtitles::getInstance(), 'subtitle_styling' ) );
}
After doing this, no styling should be loaded on the front end of your site and you'll need to style subtitles using your own CSS.
If you'd like to add Subtitles support into a custom post type, use add_post_type_support
in a function hooked to init
, for example:
function theme_slug_add_subtitles_support() {
add_post_type_support( 'custom-post-type-slug', 'subtitles' );
}
add_action( 'init', 'theme_slug_add_subtitles_support' );
This should also work on core-supported post types, like attachment
.
If you'd like to remove Subtitles support from posts or pages, use remove_post_type_support
in a function hooked to init
, for example:
function remove_subtitles_support() {
remove_post_type_support( 'post', 'subtitles' );
remove_post_type_support( 'page', 'subtitles' );
}
add_action( 'init', 'remove_subtitles_support' );
This will work on any post type that may have had Subtitles support added into it elsewhere.
HTML does not have a dedicated mechanism for marking up subheadings, alternative titles, or taglines. There are suggested alternatives from the World Wide Web Consortium (W3C); among them are spans, which work well for what we're trying to do with titles in WordPress.
If for some reason you'd like to change the markup, hook a custom output function to subtitle_markup
, for example:
function subtitle_markup_mods( $markup ) {
$markup[ 'before' ] = '<span class="custom-subtitle-class">';
$markup[ 'after' ] = '</span>';
return $markup;
}
add_filter( 'subtitle_markup', 'subtitle_markup_mods' );
I do not suggest using headings tags for subtitles.
By default subtitles do not show in RSS feeds. If you'd like to show them then the following snippet should help:
/**
* Show subtitles in RSS feeds.
*/
function display_subtitles_in_rss_feeds() {
return false;
} // end function display_subtitles_in_rss_feeds
add_filter( 'subtitles_is_feed', 'display_subtitles_in_rss_feeds' );
By default, subtitles appear on most views throughout a site. This includes single post views, single page views, archive views, and search results pages.
If you'd like to change this behavior, you can do so by taking advantage of subtitle_view_supported
. For example, if you'd like to hide subtitles on all archive pages, the following code would work:
/**
* Disable Subtitles in archive views.
*
* @see function is_archive
* @see function in_the_loop
*/
function subtitles_mod_supported_views() {
// Ditch subtitles in archives.
if ( is_archive() ) {
return false;
}
// Default in The Loop behavior from Subtitles.
if ( in_the_loop() ) {
return true;
}
} // end function subtitles_mod_supported_views
add_filter( 'subtitle_view_supported', 'subtitles_mod_supported_views' );
By default, the plugin will bail out early if no subtitle is present on a post. As of version 2.2.0, this behavior can be modified. The sample code snippet below will work just fine:
/**
* Override the early return if no subtitle exists.
*
* @see function is_archive
* @see function in_the_loop
*/
function subtitle_does_exist() {
return true;
} // end function subtitle_does_exist
add_filter( 'subtitle_exists', 'subtitle_does_exist' );
If you'd like to change the output of all subtitles throughout your site, use a function hooked to the_subtitle
, for example:
function better_subtitle( $title ) {
return $title . 'Hello World';
}
add_filter( 'the_subtitle', 'better_subtitle' );
This will filter both the title and subtitle output after Subtitles has done all of its magic.
I very much hope that you do not need to use these template tags, because all of the above methods for handling subtitles should be enough. That said, in the event that you do need to use either the_subtitle()
or get_the_subtitle()
, they exist in the plugin and will give you a little bit more flexibility over your theme.
They work in the same way that the_title()
and get_the_title()
work, for example:
if ( function_exists( 'the_subtitle' ) ) {
the_subtitle( '<p class="entry-subtitle">', '</p>' );
}
Here's how using get_the_subtitle
would look:
if ( function_exists( 'get_the_subtitle' ) ) {
echo get_the_subtitle( 35 );
}
An ID isn't necessary for get_the_subtitle
, but will work for retrieving subtitles from posts that aren't currently being viewed.
By default Subtitles supports both bold and italicized text. If you want more control over this, you can take advantage of the subtitles_allowed_tags
filter.
function subtitles_mod_allowed_tags( $args ) {
$args = array(
'i' => array(), // italicized text
'em' => array(), // emphasized text
'strong' => array(), // strong text
'a' => array(
'href' => true, // links
),
);
return $args;
} // end function subtitles_mod_allowed_tags
add_filter( 'subtitles_allowed_tags', 'subtitles_mod_allowed_tags' );
Proceed with caution here. In some cases getting too cavalier with this may introduce HTML issues into your site.
All versions of Subtitles can be found on the Releases page.
edit_form_before_permalink
that allows us to move Subtitles into a more natural position, just underneath the post title. Let's use that and preserve backwards compatibility for older versions of WordPress (see issue).$id
parameter not being sent to the primary the_subtitles
method used throughout sites (see issue).$post
is set before proceeding with any title filtering for subtitles (see issue).single_post_title
(see issue).Two primary screenshots have been shown in this README.md file, one of the post screen and one of an example of what subtitles will look like on the front end of your website. The assets folder in this GitHub repository will be used to populate screenshots on the WordPress.org plugin site, and will not be included in the official plugin download from WordPress.org.
See the languages folder for more information on using Subtitles in your language. These are considered "Extras" and will usually be released when a version bump has happened to Subtitles, for example during a bug fix or enhancement round of updates.
We've done our best to adhere to Semantic Versioning for Subtitles.
Given a version number MAJOR.MINOR.PATCH, increment the:
Most of the updates for this plugin will be in the form of bug fixes and minor enhancements.
Most commits and pull requests will undergo automatic build testing via Travis CI. The build result for the most recent non-skipped commit for master is at the top of this README.