6 files changed, 271 insertions(+), 12 deletions(-)

M _config.yml
M _docs/05-configuration.md
A images/facebook-share-example.jpg
A images/mm-author-sidebar-example.jpg
A images/mm-twitter-card-summary-image.jpg
A images/mm-twitter-card-summary-large.jpg

@@ 33,13 33,13 @@ alexa_site_verification  :
 yandex_site_verification :
 
 # Social Sharing
-og_image                 : "site-logo.png" # Open Graph/Twitter default site image
 twitter:
   username               : &twitter "mmistakes"
 facebook:
   username               : &facebook "michaelrose"
   app_id                 :
   publisher              :
+og_image                 : "site-logo.png" # Open Graph/Twitter default site image
 # For specifying social profiles
 # - https://developers.google.com/structured-data/customize/social-profiles
 social:


@@ 126,9 126,6 @@ markdown_ext: "markdown,mkdown,mkdn,mkd,md"
 # Conversion
 markdown: kramdown
 highlighter: rouge
-sass:
-  sass_dir: _sass
-  style: compressed
 lsi: false
 excerpt_separator: "\n\n"
 incremental: false


@@ 220,6 217,13 @@ defaults:
       share: true
 
 
+# Outputting
+permalink: /:categories/:title/
+paginate: 5 # amount of posts to show
+paginate_path: /page:num/
+timezone: America/New_York # http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+
+
 # Plugins
 gems:
   - jekyll-paginate


@@ 238,13 242,6 @@ whitelist:
   - jemoji
 
 
-# Outputting
-permalink: /:categories/:title/
-paginate: 5 # amount of posts to show
-paginate_path: /page:num/
-timezone: America/New_York # http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-
-
 # Archives
 #  Type
 #  - GitHub Pages compatible archive pages built with Liquid ~> type: liquid (default)

@@ 225,6 225,87 @@ Into `_config.yml`
 yandex_site_verification: "2132801JL"
 ```
 
+#### Twitter Cards and Facebook Open Graph
+
+To improve the appearance of links shared from your site to social networks like Twitter and Facebook be sure to configure the following.
+
+##### Site Twitter Username
+
+Twitter username for the site. For documents that have custom author Twitter accounts assigned in YAML Front Matter or a data file, those will be attributed as a **creator** in the Twitter Card. 
+
+For example if my site's Twitter account is @mmistakes-theme I would add the following to `_config.yml`
+
+```yaml
+twitter:
+  username: "mmistakes-theme"
+```
+
+And if I assign `@mmistakes` as an author account it will appear in the Twitter Card along with `@mmistakes-theme` attributed as a creator or document being shared.
+
+**Note**: You need to [apply for Twitter Cards](https://dev.twitter.com/docs/cards) and validate they're working on your site before they will begin showing up.
+{: .notice--warning}
+
+##### Facebook Open Graph
+
+If you have Facebook ID or publisher page add them:
+
+```yaml
+facebook:
+  app_id:  # A Facebook app ID
+  publisher:  # A Facebook page URL or ID of the publishing entity
+```
+
+While not part a part of Open Graph, you can also add your Facebook username for use in the sidebar and footer.
+
+```yaml
+facebook:
+  username: "michaelrose"  # ref. page https://www.facebook.com/michaelrose
+```
+
+**ProTip:** To debug Open Graph data use [this tool](https://developers.facebook.com/tools/debug/og/object?q=https%3A%2F%2Fmademistakes.com) to test your pages. If content changes aren't reflected you will probably have to hit the **Fetch new scrape information** button to refresh.
+{: .notice--info}
+
+##### Open Graph Default Image
+
+For documents who don't have a `header.image` assigned in their YAML Front Matter, `site.og_image` will be used as a fallback. Your logo, icon, or avatar are something else that is meaningful. Just make sure it is place in the `/images/` folder, a minimum size of 120px by 120px, and less than 1MB in file size. *The image will be cropped to a square on all platforms.*
+
+```yaml
+og_image: "site-logo.png"
+```
+
+<figure>
+  <img src="{{ base_path }}/images/mm-twitter-card-summary-image.jpg" alt="Twitter Card summary example">
+  <figcaption>Example of a image placed in a Summary Card.</figcaption>
+</figure>
+
+Documents who have a `header.image` assigned in their YAML Front Matter will appear like this when shared on Twitter and Facebook.
+
+<figure>
+  <img src="{{ base_path }}/images/mm-twitter-card-summary-large.jpg" alt="page shared on Twitter">
+  <figcaption>Shared page on Twitter with header image assigned.</figcaption>
+</figure>
+
+<figure>
+  <img src="{{ base_path}}/images/facebook-share-example.jpg" alt="page shared on Facebook">
+  <figcaption>Shared page on Facebook with header image assigned.</figcaption>
+</figure>
+
+##### Include your social profile in search results
+
+Use markup on your official website to add your [social profile information](https://developers.google.com/structured-data/customize/social-profiles#adding_structured_markup_to_your_site) to the Google Knowledge panel in some searches. Knowledge panels can prominently display your social profile information.
+
+```yaml
+social:
+  type :  # Person or Organization (defaults to Person)
+  name :  # If the user or organization name differs from the site's name
+  links:
+    - "https://twitter.com/yourTwitter"
+    - "https://facebook.com/yourFacebook"
+    - "https://instagram.com/yourProfile"
+    - "https://www.linkedin.com/in/yourprofile"
+    - "https://plus.google.com/your_profile"
+```
+
 #### Analytics
 
 Analytics is disabled by default. To enable globally select one of the following:


@@ 243,4 324,185 @@ analytics:
 
 To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/analytics-providers/custom.html`.
 
-#### Twitter Cards and Open Graph Data
+## Site Author
+
+Used as the defaults for defining what appears in the author sidebar.
+
+![author sidebar example]({{ base_path }}/images/mm-author-sidebar-example.jpg)
+
+**Note:** For sites with multiple authors these values can be overridden post by post with custom YAML Front Matter and a data file. For more information on how that see below.
+{: .notice--info}
+
+```yaml
+author:
+  name   : "Your Name"
+  avatar : "bio-photo.jpg"  # placed in /images/
+  bio    : "My awesome biography constrained to a sentence or goes here."
+  email  : # optional
+  uri    : "http://your-site.com"
+```
+
+Social media links are all optional, include the ones you want visible. In most cases you just need to add the username. If you're unsure double check `_includes/author-profile.html`.
+
+## Reading Files
+
+Nothing out of the ordinary here. `include` and `exclude` may be the only things you need to alter.
+
+## Conversion and Markdown Processing
+
+Again nothing out of the ordinary here as the theme adheres to the defaults used by GitHub Pages. [**Kramdown**](http://kramdown.gettalong.org/) for Markdown conversion, [**Rouge**](http://rouge.jneen.net/) syntax highlighting, and incremental building disabled.
+
+## Front Matter Defaults
+
+To save yourself time setting [Front Matter Defaults](https://jekyllrb.com/docs/configuration/#front-matter-defaults) for posts, pages, and collections is the way to go. Sure you can assign layouts and toggle settings like **reading time**, **comments**, and **social sharing** in each file, but that's not ideal.
+
+Using the `default` key in `_config.yml` you could set the layout and enable author profiles, reading time, comments, social sharing, and related posts for all posts.
+
+```yaml
+defaults:
+  # _posts
+  - scope:
+      path: ""
+      type: posts
+    values:
+      layout: single
+      author_profile: true
+      read_time: true
+      comments: true
+      share: true
+      related: true
+```
+
+Pages Front Matter defaults can be scoped like this:
+
+```yaml
+defaults:
+  # _pages
+  - scope:
+      path: ""
+      type: pages
+    values:
+      layout: single
+```
+
+And collections like this:
+
+```yaml
+defaults:
+  # _foo
+  - scope:
+      path: ""
+      type: foo
+    values:
+      layout: single
+```
+
+And of course any default value can be overridden by settings in a post, page, or collection file. All you need to do is specify the settings in the YAML Front Matter. For more examples be sure to check out the demo site's [`_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/gh-pages/_config.yml).
+
+## Outputting
+
+The default permalink style used by Minimal Mistakes is `permalink: /:categories/:title/`. If you have a post named `2016-01-01-my-post.md` with `categories: foo` in the YAML Front Matter, Jekyll will generate `/foo/my-post/index.html`.
+
+**Note:** If you plan on enabling breadcrumb links --- including category names in permalinks is a big part of how those are created.
+{: .notice--warning}
+
+### Paginate
+
+If [using pagination](https://github.com/jekyll/jekyll-paginate) on the homepage you can change the amount of posts shown with:
+
+```yaml
+paginate: 5
+```
+
+You'll also need to include some modified Liquid to properly use the paginator, which you can find in the **Content** section or gleam from the demo site's [`index.html`](https://github.com/mmistakes/minimal-mistakes/blob/gh-pages/index.html).
+
+### Timezone
+
+Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the [IANA Time Zone Database](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) is valid. The default is the local time zone, as set by your operating system.
+
+```yaml:
+timezone: America/New_York
+```
+
+## Plugins
+
+When hosting with GitHub Pages a small [set of gems](https://pages.github.com/versions/) have been whitelisted for use. The theme uses a few of them which can be found under `gems`. Additional settings and configurations are documented in the links below.
+
+* [jekyll-paginate][jekyll-paginate] -- Pagination Generator for Jekyll.
+* [jekyll-sitemap][jekyll-sitemap] -- Jekyll plugin to silently generate a sitemaps.org compliant sitemap for your Jekyll site.
+* [jekyll-gist][jekyll-gist] -- Liquid tag for displaying GitHub Gists in Jekyll sites.
+* [jekyll-feed][jekyll-feed] -- A Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts.
+* [jemoji][jemoji] -- GitHub-flavored emoji plugin for Jekyll
+
+[jekyll-paginate]: https://github.com/jekyll/jekyll-paginate
+[jekyll-sitemap]: https://github.com/jekyll/jekyll-sitemap
+[jekyll-gist]: https://github.com/jekyll/jekyll-gist
+[jekyll-feed]: https://github.com/jekyll/jekyll-feed
+[jemoji]: https://github.com/jekyll/jemoji
+
+If you're hosting elsewhere then you don't really have to worry about that and are free to include whatever [Jekyll plugins](https://jekyllrb.com/docs/plugins/) you desire.
+
+## Archive Settings
+
+Minimal Mistakes ships with support for taxonomy (category and tag) pages. GitHub Pages hosted sites get strip down Liquid only approach while those hosting elsewhere can use plugins like [**jekyll-archives**][jekyll-archives] to generate these pages automatically.
+
+[jekyll-archives]: https://github.com/jekyll/jekyll-archives
+
+The default `type` is set to use Liquid.
+
+```yaml
+categories:
+  type: liquid
+  path: /categories/
+tags:
+  type: liquid
+  path: /tags/
+```
+
+Which would create category and tag links in the breadcrumbs and page meta like: `/categories/#foo` and `/tags/#foo`.
+
+**Note:** for these links to resolve category and tag index pages need to exist at [`/categories/index.html`](https://github.com/mmistakes/minimal-mistakes/blob/gh-pages/_pages/category-archive.html) and [`/tags/index.html`](https://github.com/mmistakes/minimal-mistakes/blob/gh-pages/_pages/tag-archive.html). Examples with the necessary Liquid code can be taken from the demo site.
+{: .notice--warning}
+
+If you have the luxury of using Jekyll Plugins then [**jekyll-archives**][jekyll-archives] will make your life much easier as category and tag pages are created for you.
+
+Change `type` to `jekyll-archives` and apply the following [configurations](https://github.com/jekyll/jekyll-archives/blob/master/docs/configuration.md):
+
+```yaml
+categories:
+  type: jekyll-archives
+  path: /categories/
+tags:
+  type: jekyll-archives
+  path: /tags/
+jekyll-archives:
+  enabled:
+    - categories
+    - tags
+  layouts:
+    category: archive-taxonomy
+    tag: archive-taxonomy
+  permalinks:
+    category: /categories/:name/
+    tag: /tags/:name/
+```
+
+**Note:** The `archive-taxonomy` layout used by jekyll-archives is provided with the theme and can be found in the `_layouts` folder.
+{: .notice--info}
+
+## HTML Compression
+
+If you care at all about performance (and really who doesn't) compressing the HTML files generated by Jekyll is a good thing to do.
+
+Now if you're hosting with GitHub Pages there aren't many options afforded to you unless commit compiled files to your repo instead. Thankfully there is some Liquid wizardry you can use to strip whitespace and comments.
+
+There's a variety of configurations and cavets to using the `compress` layout, so be sure to read through the [documentation](http://jch.penibelst.de/) if you decide to make changes to anything, but here's the settings I've found work well:
+
+```yaml
+compress_html:
+  clippings: all
+  ignore:
+    envs: development  # disable compression in dev environment
+```
+
+**Caution:** Inline JavaScript comments can cause problems with `compress.html`, so be sure to `/* comment this way */` and avoid `// these sorts of comments`.<
\ No newline at end of file