Override Post Title with First Content Heading

This plugin is developed at
Shepherd
Interactive for the benefit of the community. No support is available.
Please post any questions to the support
forum.

On a singular post/page, normally in The Loop the_title() returns
post_title; if, however, this needs to be overridden so that a
custom content heading is displayed (i.e. for SEO purposes), then an
h1 or h2 element may be supplied at the beginning of
the post_content and the contents of this heading element
will be returned by the_title() instead of post_title.

From a technical perspective, the site title in the main header should be
an h1 element and the page/post title should in an h2
element within an article, per HTML5:

Sections may contain headings of any rank, but authors are strongly
encouraged to either use only `h1` elements, or to use elements of the
appropriate rank for the section’s nesting level.

This is seen in the default WordPress theme and the HTML specifications. However,
SEO places higher priority on the contents of an h1 element, so if
every page of a site has the exact same h1 contents (the site name),
then search engines may not be as likely to rank the page based on the unique
contents of the h2. It has been suggested
therefore that the h1 and the h2 elements be swapped,
so that the site title appears in an h2 and so that the unique page
title appears in the h1. While the specifications don’t prefer this
arrangement, it is not incorrect, also per HTML5:

Both of the documents are semantically identical and would produce the same
outline in compliant user agents.

So if different heading levels are semantically equivalent, and if search
engines really place that much importance on h1, then SEO wins.

In both cases, content section headings should be coded with h3 and
below.

Technical note: If the $post object is not passed into the_title
filter, then the page’s the_title() must be called before every other
the_title() call in_the_loop()