document

README.md

@@ -52,17 +52,22 @@ The SEO tag will respect any of the following if included in your site's `_confi
 * `title` - Your site's title (e.g., Ben's awesome site, The GitHub Blog, etc.)
 * `description` - A short description (e.g., A blog dedicated to reviewing cat gifs)
 * `url` - The full URL to your site. Note: `site.github.url` will be used by default.
+* `author` - global author information (see below)
 * `twitter:username` - The site's Twitter handle. You'll want to describe it like so:
+
   ```yml
   twitter:
     username: benbalter
   ```
+
 * `facebook:app_id` (A Facebook app ID for Facebook insights), and/or `facebook:publisher` (A Facebook page URL or ID of the publishing entity). You'll want to describe one or both like so:
+
    ```yml
    facebook:
      app_id: 1234
      publisher: 1234
    ```
+
 * `logo` - Relative URL to a site-wide logo (e.g., `assets/your-company-logo.png`)
 * `social` - For [specifying social profiles](https://developers.google.com/structured-data/customize/social-profiles). The following properties are available:
   * `type` - Either `person` or `organization` (defaults to `person`)
@@ -75,4 +80,58 @@ The SEO tag will respect the following YAML front matter if included in a post,
 * `title` - The title of the post, page, or document
 * `description` - A short description of the page's content
 * `image` - Relative URL to an image associated with the post, page, or document (e.g., `assets/page-pic.jpg`)
-* `author` - The username of the post, page, or document author
+* `author` - Page-, post-, or document-specific author information (see below)
+
+### Author information
+
+Author information is used to propagate the `creator` field of Twitter summary cards. This is should be an author-specific, not site-wide Twitter handle (the site-wide username be stored as `site.twitter.username`).
+
+*TL;DR*: In most cases, put `author: [your Twitter handle]` in the document's front matter, for sites with multiple authors. If you need something more complicated, read on.*
+
+There are several ways to convey this author-specific information. Author information is found in the following order of priority:
+
+1. An `author` object, in the documents's front matter, e.g.:
+
+  ```yml
+  author:
+    twitter: benbalter
+  ```
+
+2. An `author` object, in the site's `_config.yml`, e.g.:
+
+  ```yml
+  author:
+    twitter: benbalter
+  ```
+
+3. `site.data.authors[author]`, if an author is specified in the document's front matter, and a corresponding key exists in `site.data.authors`. E.g., you have the following in the document's front matter:
+
+  ```yml
+  author: benbalter
+  ```
+
+  And you have the following in `_data/authors.yml`:
+
+  ```yml
+  benbalter:
+    picture: /img/benbalter.png
+    twitter: jekyllrb
+
+  potus:
+    picture: /img/potus.png
+    twitter: whitehouse
+  ```
+
+  In the above example, the author `benbalter`'s Twitter handle will be resolved to `@jekyllrb`. This allows you to centralize author information in a single `_data/authors` file for site with many authors that require more than just the author's username.
+
+4. An author in the document's front matter (the simplest way), e.g.:
+
+  ```yml
+  author: benbalter
+  ```
+
+5. An author in the site's `_config.yml`, e.g.:
+
+  ```yml
+  author: benbalter
+  ```