Lots of doc updates and such for v1.5

Changes

@@ -1,3 +1,7 @@
+1.5  2017-08-20
+
+     - Adding support for social-media metadata tags.
+
 1.45 2017-08-18
 
      - Emergency rollback of the UTF-8 "improving". O the embarrassment.

README.md

@@ -128,6 +128,10 @@ In this way you could, for example, compose and edit blog posts via Markdown in
 
 ## Advanced use
 
+### Customizing templates
+
+For a brief guide to the template files and how to customize them for your blog, please [see the Plerd wiki on GitHub](https://github.com/jmacdotorg/plerd/wiki/Plerd-template-guide).
+
 ### User-defined attributes
 
 You can add any attributes you'd like to your posts, and then refer to them from your templates via a hash named `attributes` attached to every post object. For example, if a post's metadata looks like this:
@@ -140,7 +144,7 @@ Then you can refer to `post.attributes.byline` to fetch that value from within t
 ### Social-media metatags
 
 By defining some extra attributes in both your blog's configuration file, you
-can direct Plerd to add [Open Graph](http://ogp.me) and [Twitter Card](https://dev.twitter.com/cards/overview)-enabling metadata tags to each of your posts.
+can direct Plerd to add [Open Graph](http://ogp.me) and [Twitter Card](https://dev.twitter.com/cards/overview)-enabling metadata tags to each of your posts. This will allow services like Facebook, Twitter, and Slack to present attractive little summaries of your blogposts when displaying links to them.
 
 These blog configuration options (all optional) are:
 

lib/Plerd.pm

@@ -1,6 +1,6 @@
 package Plerd;
 
-our $VERSION = '1.45';
+our $VERSION = '1.5';
 
 use Moose;
 use Template;
@@ -524,12 +524,24 @@ author_email
 
 =back
 
-And, optional keys, with defaults:
+And, optional keys:
 
 =over
 
 =item *
 
+facebook_id
+
+=item *
+
+image
+
+=item *
+
+twitter_id
+
+=item *
+
 recent_posts_maxsize I<Default value: 10>
 
 =back
@@ -542,17 +554,19 @@ recent_posts_maxsize I<Default value: 10>
 
 =over
 
-=item source_path
+=item base_uri
 
-The path to the filesystem directory containing this blog's source directory.
+L<URI> object representing the base URI for this blog, which the system will prepend
+to any absolute links it builds.
 
-=item template_path
+=item facebook_id
 
-The path to the filesystem directory containing this blog's templates directory.
+(Optional) This blog's Facebook app ID.
 
-=item publication_path
+=item image
 
-The path to the filesystem directory containing this blog's output directory.
+(Optional) L<URI> object representing this blog's default image, for use in
+social media metadata and such.
 
 =item path
 
@@ -562,14 +576,26 @@ The path to a filesystem directory within which Plerd will look for
 B<Caution:> If this is not defined I<and> any one of the previous three attributes
 is also undefined, then Plerd will die if you try to publish the blog.
 
+=item publication_path
+
+The path to the filesystem directory containing this blog's output directory.
+
+=item source_path
+
+The path to the filesystem directory containing this blog's source directory.
+
+=item template_path
+
+The path to the filesystem directory containing this blog's templates directory.
+
 =item title
 
 String representing this blog's title.
 
-=item base_uri
+=item twitter_id
 
-L<URI> object representing the base URI for this blog, which the system will prepend
-to any absolute links it builds.
+(Optional) This Twitter username associated with this blog. Does not include
+the leading '@' character.
 
 =item recent_posts_maxsize
 

lib/Plerd/Post.pm

@@ -542,23 +542,12 @@ A Path::Class::File object representing this post's Markdown source file.
 
 =over
 
-=item published_filename
-
-The local filename (without parent directory path) of the HTML file that this post
-will generate upon publication.
-
-=item uri
-
-The L<URI> of the of the HTML file that this post will generate upon publication.
-
-=item published_timestamp
-
-This post's date, in W3C format, set to midnight in the local timezone.
+=item newer_post
 
-=item updated_timestamp
+A Plerd::Post object representing the next-newer post to the blog.
 
-The modification time of this this post's source file, in W3C format, set to
-the local timezone.
+Is the current object represents the newest post in the blog, then this method
+returns undef.
 
 =item older_post
 
@@ -567,44 +556,70 @@ A Plerd::Post object representing the next-older post to the blog.
 Is the current object represents the oldest post in the blog, then this method
 returns undef.
 
-=item newer_post
+=item published_filename
 
-A Plerd::Post object representing the next-newer post to the blog.
+The local filename (without parent directory path) of the HTML file that this post
+will generate upon publication.
 
-Is the current object represents the newest post in the blog, then this method
-returns undef.
+=item published_timestamp
+
+This post's date, in W3C format, set to midnight in the local timezone.
 
 =item reading_time
 
 An estimated reading-time for this post, measured in whole minutes, and based
 on an assumed (and fairly conservative) reading pace of 200 words per minute.
 
+=item updated_timestamp
+
+The modification time of this this post's source file, in W3C format, set to
+the local timezone.
+
+=item uri
+
+The L<URI> of the of the HTML file that this post will generate upon publication.
+
 =back
 
 =head2 Read-write attributes
 
 =over
 
-=item title
+=item attributes
 
-String representing this post's title.
+A hashref of all the attributes defined in the source document's metadata
+section, whether or not Plerd takes any special meaning from them.
+
+For example, if a source document defines both C<title> and C<favorite_color>
+key-value pairs in its metadata, both keys and values will appear in this
+hashref, even though Plerd pays no mind to the latter key.
+
+=item body
+
+String representing the post's body text.
 
 =item date
 
 L<DateTime> object representing this post's presented publication date.
 
-=item body
+=item description
 
-String representing the post's body text.
+String representing a short, descriptive summary of this post. This value affects
+the metadata attached to this post, for use by social media and such.
 
-=item attributes
+If you don't set this value yourself by the time Plerd needs it, then it will
+set it to the first paragraph of the post's body text (with all markup removed).
 
-A hashref of all the attributes defined in the source document's metadata
-section, whether or not Plerd takes any special meaning from them.
+=item image
 
-For example, if a source document defines both C<title> and C<favorite_color>
-key-value pairs in its metadata, both keys and values will appear in this
-hashref, even though Plerd pays no mind to the latter key.
+(Optional) L<URI> object referencing an illustrative image for this post.
+
+Setting this value affects the metadata attached to this post, for use by social
+media and such.
+
+=item title
+
+String representing this post's title.
 
 =back