Update docs

_data/navigation.yml

@@ -48,11 +48,11 @@ docs:
   - title: Content
     children:
       - title: "Working with Posts"
-        path: working-with-posts
+        path: posts
       - title: "Working with Pages"
-        path: working-with-pages
+        path: pages
       - title: "Working with Collections"
-        path: working-with-collections
+        path: collections
       - title: "Helpers and Shortcodes"
         path: helpers-and-shortcodes
       - title: "Images"

_docs/05-configuration.md

@@ -131,10 +131,12 @@ If you add `read_time: false` to a post's YAML Front Matter it will override the
 
 Commenting for [**Disqus**](https://disqus.com/), [**Facebook**](https://developers.facebook.com/docs/plugins/comments), and **Google+** are built into the theme. First set the comment provider you'd like to use: 
 
-* `disqus`: Disqus
+|               | Comment Provider  |
-* `facebook`: Facebook Comments
+| ------------- | ----------------  |
-* `google-plus`: Google+
+| `disqus`      | Disqus            |
-* `custom`: other comment providers
+| `facebook`    | Facebook Comments |
+| `google-plus` | Google+ Comments  |
+| `custom`      | Other             |
 
 Then add `comments: true` to each document you want comments visible on.
 
@@ -310,11 +312,13 @@ social:
 
 Analytics is disabled by default. To enable globally select one of the following:
 
-* `google`: [Google Standard Analytics](https://www.google.com/analytics/)
+|                    | Analytics Provider                                              |
-* `google-universal`: [Google Universal Analytics](https://www.google.com/analytics/)
+| ------------------ | ------------------                                              |
-* `custom`: other analytics providers
+| `google`           | [Google Standard Analytics](https://www.google.com/analytics/)  |
+| `google-universal` | [Google Universal Analytics](https://www.google.com/analytics/) |
+| `custom`           | Other analytics providers                                       |
 
-For Google Analytics also add your Tracking Code:
+For Google Analytics add your Tracking Code:
 
 ```yaml
 analytics:
@@ -420,7 +424,7 @@ You'll also need to include some modified Liquid to properly use the paginator,
 
 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:
+```yaml
 timezone: America/New_York
 ```
 
@@ -428,11 +432,13 @@ timezone: America/New_York
 
 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.
+| Plugin                             | Description |
-* [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-paginate][jekyll-paginate] | Pagination Generator for Jekyll. |
-* [jekyll-feed][jekyll-feed] -- A Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts.
+| [jekyll-sitemap][jekyll-sitemap] |Jekyll plugin to silently generate a sitemaps.org compliant sitemap for your Jekyll site. |
-* [jemoji][jemoji] -- GitHub-flavored emoji plugin for Jekyll
+| [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

_docs/09-layouts.md

@@ -38,7 +38,15 @@ A Jekyll layout that compresses HTML in pure Liquid.
 
 ## Single Layout
 
-The layout you'll likely use the most --- sidebar and main content combo with the following optional modules: **social sharing links**, **comments**, and **related posts**.
+The layout you'll likely use the most --- sidebar and main content combo.
+
+**Includes:**
+
+* Optional header image with caption
+* Optional header overlay (solid color/image) + text and optional "call to action" button
+* Optional social sharing links module
+* Optional comments module
+* Optional related posts module
 
 {% include gallery id="single_layout_gallery" caption="Image header and meta info examples for `single` layout" %}
 
@@ -48,19 +56,73 @@ Assign with `layout: single`, or better yet apply as a [Front Matter default]({{
 
 Essentially the same as `single` with markup adjustments and some modules removed.
 
-![archive layout example]({{ base_path }}/images/mm-layout-archive.png)
+**Includes:**
+
+* Optional header image with caption
+* Optional header overlay (solid color/image) + text and optional "call to action" button
+* List and grid views
+
+<figure>
+  <img src="{{ base_path }}/images/mm-layout-archive.png" alt="archive layout example">
+  <figcaption>List view example.</figcaption>
+</figure>
 
 Below are sample archive pages you can easily drop into your project, taking care to rename `permalink`, `title`, or the filename to fit your site. Each is 100% compatible with GitHub Pages.
 
-* [All Posts Grouped by Category][posts-categories]
+* [All Posts Grouped by Category -- List View][posts-categories]
-* [All Posts Grouped by Tags][posts-tags]
+* [All Posts Grouped by Tags -- List View][posts-tags]
-* [All Posts Grouped by Year][posts-year]
+* [All Posts Grouped by Year -- List View][posts-year]
-* [All Posts Grouped by Collection][posts-collection]
+* [All Posts Grouped by Collection -- List View][posts-collection]
+* [Portfolio Collection -- Grid View][portfolio-collection]
 
-[posts-categories]: {{ site.gh_repo }}/blob/gh-pages/_pages/category-archive.html
+[posts-categories]: {{ site.gh_repo }}/gh-pages/_pages/category-archive.html
-[posts-tags]: {{ site.gh_repo }}/blob/gh-pages/_pages/tag-archive.html
+[posts-tags]: {{ site.gh_repo }}/gh-pages/_pages/tag-archive.html
-[posts-year]: {{ site.gh_repo }}/blob/gh-pages/_pages/year-archive.html
+[posts-year]: {{ site.gh_repo }}/gh-pages/_pages/year-archive.html
-[posts-collection]: {{ site.gh_repo }}/blob/gh-pages/_pages/collection-archive.html
+[posts-collection]: {{ site.gh_repo }}/gh-pages/_pages/collection-archive.html
+[portfolio-collection]: {{ site.gh_repo }}/gh-pages/_pages/portfolio-archive.html
+
+Post and page excerpts are auto-generated by Jekyll which grabs the first paragraph of text. To override this text with something more specific use the following YAML Front Matter:
+
+```yaml
+excerpt: "A unique line of text to describe this post that will display in an archive listing and meta description with SEO benefits."
+```
+
+### Grid View
+
+Adding `type=grid` to the `archive-single` helper will display archive posts in a 4 column grid. For example to create an archive displaying all documents in the portfolio collection:
+
+**Step 1:** Create a portfolio archive page (eg. `_pages/portfolio-archive.html`) with the following YAML Front Matter:
+
+```yaml
+---
+layout: archive
+title: "Portfolio"
+permalink: /portfolio/
+author_profile: false
+---
+```
+
+**Step 2:** Loop over all documents in the portfolio collection and output in a grid:
+
+```html
+{% raw %}{% include base_path %}
+
+<div class="grid__wrapper">
+  {% for post in site.portfolio %}
+    {% include archive-single.html type="grid" %}
+  {% endfor %}{% endraw %}
+</div>
+```
+
+To produce something like this:
+
+<figure>
+  <img src="{{ base_path }}/images/mm-archive-grid-view-example.jpg" alt="archive grid view example">
+  <figcaption>Grid view example.</figcaption>
+</figure>
+
+**Note:** More information on using this `_include` can be found under [**Helpers and Shortcodes**]({{ base_path }}/docs/helpers-and-shortcodes/).
+{: .notice--info}
 
 ### Taxonomy Archive
 
@@ -70,7 +132,15 @@ If you have the luxury of using Jekyll plugins the creation of category and tag
 
 ### Home Page
 
-Minimal Mistakes ships with an [`index.html`]({{ site.gh_repo }}/blob/master/index.html) in the root of the project for displaying the 5 most recent posts --- with pagination. It does this by assigning `layout: archive` in the YAML Front Matter and including the following Liquid in the body:
+Minimal Mistakes ships with an [`index.html`]({{ site.gh_repo }}/blob/master/index.html) in the root of the project for displaying recent posts. 
+
+**Includes:**
+
+* Optional header image with caption
+* Optional header overlay (solid color/image) + text and optional "call to action" button
+* Paginated posts
+
+Post pagination is achieved by assigning `layout: archive` in the YAML Front Matter and including the following Liquid in the body:
 
 ```html
 {% raw %}<!-- start index.html body -->
@@ -91,13 +161,24 @@ Minimal Mistakes ships with an [`index.html`]({{ site.gh_repo }}/blob/master/ind
   <figcaption>Home page post pagination example.</figcaption>
 </figure>
 
-**Note:** For more pagination relation settings check the [**Configuration**]({{ base_path }}/docs/configuration/#paginate) section.
+**Note:** For more pagination related settings check the [**Configuration**]({{ base_path }}/docs/configuration/#paginate) section.
 {: .notice--info}
 
 ## Splash Page Layout
 
+For full-width landing pages that need a little something extra add `layout: splash` to the YAML Front Matter.
+
+**Includes:**
+
+* Optional header image with caption
+* Optional header overlay (solid color/image) + text and optional "call to action" button
+* Feature blocks (`left`, `center`, and `right` alignment options)
+
 ![splash page layout example]({{ base_path }}/images/mm-layout-splash.png)
 
+Feature blocks can be assigned and aligned to the `left`, `right`, or `center` with a sprinkling of YAML. For full details on how to use the `feature_row` helper check the [**Content**]({{ base_path }}/docs/helpers-and-shortcodes/) section or review a [sample splash page]({{ site.gh_repo }}/gh-pages/_pages/splash-page.md).
+
+
 ---
 
 ## Headers
@@ -138,10 +219,12 @@ header:
 
 To overlay text on top of a header image you have a few more options:
 
-* `overlay_image` --- header image you'd like to overlay. Same rules as `header.image` from above.
+| Front Matter variable | Description |
-* `excerpt` --- auto-generated page excerpt is added to the overlay text or can be overridden.
+| --------------------- | ----------- |
-* `cta_label` --- call to action button text label (default is `more_label` in UI Text data file)
+| `overlay_image`       | Header image you'd like to overlay. Same rules as `header.image` from above. |
-* `cta_url` --- call to action button URL
+| `excerpt`             | Auto-generated page excerpt is added to the overlay text or can be overridden. |
+| `cta_label`           | Call to action button text label (default is `more_label` in UI Text data file). |
+| `cta_url`             | Call to action button URL. |
 
 With this YAML Front Matter:
 
@@ -199,10 +282,12 @@ defaults:
 
 Blocks of content can be added by using the following under `sidebar`:
 
-* `title` --- title or heading
+| Front Matter variable | Description                                                |
-* `image` --- image path placed in `/images/` folder or an external URL
+| --------------------- | -----------                                                |
-* `image_alt` --- alt description for image
+| `title`               | Title or heading.                                          |
-* `text` --- Markdown supported text
+| `image`               | Image path placed in `/images/` folder or an external URL. |
+| `image_alt`           | Alternate description for image.                           |
+| `text`                | Markdown supported text.                                   |
 
 Multiple blocks can also be added by following the example below:
 

_docs/10-posts.md

@@ -0,0 +1,34 @@
+---
+title: "Working with Posts"
+permalink: /docs/posts/
+excerpt:
+sidebar:
+  title: "v3.0"
+  nav: docs
+---
+
+{% include base_path %}
+
+Posts are stored in the `_posts` directory and named according to the `YEAR-MONTH-DAY-title.MARKUP` format as per [the usual](https://jekyllrb.com/docs/posts/).
+
+**Recommended Front Matter Defaults:**
+
+```yaml
+defaults:
+  # _posts
+  - scope:
+      path: ""
+      type: posts
+    values:
+      layout: single
+      author_profile: true
+      read_time: true
+      comments: true
+      share: true
+      related: true
+```
+
+Adding the above to `_config.yml` will assign the `single` layout and enable: *author profile*, *reading time*, *comments*, *social sharing links*, and *related posts*, for all posts.
+
+**ProTip:** Remember to write unique `excerpt` descriptions for each post for improved SEO and archive listings.
+{: .notice--info}

_docs/11-pages.md

@@ -0,0 +1,47 @@
+---
+title: "Working with Pages"
+permalink: /docs/pages/
+excerpt:
+sidebar:
+  title: "v3.0"
+  nav: docs
+---
+
+{% include base_path %}
+
+To better organize all of your pages you can centralize them into a single location similar to posts and collections.
+
+**Step 1:** Start by placing pages (`.md` or `.html` files) into a `_pages` directory. Meaningfully naming files should be the goal. Avoid patterns like `/about/index.md` as it makes distinguishing between multiple `index.md` files harder.
+
+```bash
+sample-project
+└── _pages/
+    ├── 404.md               # custom 404 page
+    ├── about.md             # about page
+    └── contact.md           # contact page
+```
+
+**Step 2:** Include pages to be sure Jekyll "sees" and processes the files inside of `_pages`. Add `include: ["_pages"]` to `_config.yml`.
+
+**Step 3:** Assign permalink overrides in the YAML Front Matter of each.
+
+Examples:
+
+| filename            | permalink              |
+| --------            | ---------              |
+| `_pages/about.md`   | `permalink: /about/`   |
+| `_pages/home.md`    | `permalink: /`         |
+| `_pages/contact.md` | `permalink: /contact/` |
+
+**Recommended Front Matter Defaults:**
+
+```yaml
+defaults:
+  # _pages
+  - scope:
+      path: ""
+      type: pages
+    values:
+      layout: single
+      author_profile: true
+```

_docs/12-collections.md

@@ -0,0 +1,47 @@
+---
+title: "Working with Collections"
+permalink: /docs/collections/
+excerpt:
+sidebar:
+  title: "v3.0"
+  nav: docs
+---
+
+{% include base_path %}
+
+Collections like posts and pages work as you'd expect. If you're new to them be sure to read [Jekyll's documentation](https://jekyllrb.com/docs/collections/).
+
+Minimal Mistakes has been built with collections in mind and you will find [several examples]({{ base_path }}/collection-archive/) on the demo site (portfolio, recipes, pets).
+
+---
+
+A popular use case for collections is to build a portfolio section as part of a personal site. Let's quickly walk through the steps to do that.
+
+**Step 1:** Configure the portfolio collection by adding the following to `_config.yml`.
+
+```yaml
+collections:
+  portfolio:
+    output: true
+    permalink: /:collection/:path/
+```
+
+These settings essentially say output `index.html` files for each portfolio document in `_portfolio` at `_site/portfolio/<document-filename>/`.
+
+Just like posts and pages you'll probably want to set some defaults for the Front Matter:
+
+```yaml
+defaults:
+  # _portfolio
+  - scope:
+      path: ""
+      type: portfolio
+    values:
+      layout: single
+      author_profile: false
+      share: true
+```
+
+And then create portfolio content like [`_portfolio/foo-bar-website.md`]({{ site.gh_repo }}/gh-pages/_portfolio/foo-bar-website.md), to end up with something like this.
+
+![portfolio collection example]({{ base_path }}/images/mm-portfolio-collection-example.jpg)

assets/_scss/_base.scss

@@ -129,7 +129,8 @@ pre {
 p > code,
 a > code,
 li > code,
-figcaption > code {
+figcaption > code,
+td > code {
   padding-top: 0.1rem;
   padding-bottom: 0.1rem;
   font-size: $type-size-6;

assets/_scss/_tables.scss

@@ -3,6 +3,7 @@
    ========================================================================== */
 
 table {
+  margin-bottom: 1em;
   width: 100%;
   font-family: $global-font-family;
   font-size: $type-size-6;