hacks-guide-minimal-mistake.../_docs/09-layouts.md

---
title: "Layouts"
permalink: /docs/layouts/
excerpt:
sidebar:
  title: "v3.0"
  nav: docs
single_layout_gallery:
  - image_path: mm-layout-single-header.png
    alt: "single layout with header example"
  - image_path: mm-layout-single-meta.png
    alt: "single layout with comments and related posts"
---

{% include base_path %}
{% include toc icon="columns" title="Included Layouts" %}

The bread and butter of any theme. Below you'll find the layouts included with Minimal Mistakes, what they look like and the type of content they've been built for.

## Default Layout

The base layout all other layouts inherit from. There's not much to this layout apart from pulling in several `_includes`:

* `<head>` elements
* masthead navigation links
* {% raw %}`{{ content }}`{% endraw %}
* page footer
* scripts

**Note:** You won't ever assign this layout directly to a post or page. Instead all other layouts will build off of it by setting `layout: default` in their YAML Front Matter.
{: .notice--warning}

## Compress Layout

A Jekyll layout that compresses HTML in pure Liquid.

* [Documentation](http://jch.penibelst.de/)

## Single Layout

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" %}

Assign with `layout: single`, or better yet apply as a [Front Matter default]({{ base_path }}/docs/configuration/#front-matter-defaults) in `_config.yml`.

## Archive Layout

Essentially the same as `single` with markup adjustments and some modules removed.

**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 -- List View][posts-categories]
* [All Posts Grouped by Tags -- List View][posts-tags]
* [All Posts Grouped by Year -- List View][posts-year]
* [All Posts Grouped by Collection -- List View][posts-collection]
* [Portfolio Collection -- Grid View][portfolio-collection]

[posts-categories]: {{ site.gh_repo }}/gh-pages/_pages/category-archive.html
[posts-tags]: {{ site.gh_repo }}/gh-pages/_pages/tag-archive.html
[posts-year]: {{ site.gh_repo }}/gh-pages/_pages/year-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

If you have the luxury of using Jekyll plugins the creation of category and tag archives is greatly simplified. Enable support for the [`jekyll-archives`](https://github.com/jekyll/jekyll-archives) plugin with a few `_config.yml` settings as noted in the [**Configuration**]({{ base_path }}/docs/configuration/#archive-settings) section.

![archive taxonomy layout example]({{ base_path }}/images/mm-layout-archive-taxonomy.png)

### Home Page

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 -->
{% include base_path %}

<h3 class="archive__subtitle">Recent Posts</h3>

{% for post in paginator.posts %}
  {% include archive-single.html %}
{% endfor %}

{% include paginator.html %}
<!-- end index.html body -->{% endraw %}
```

<figure>
  <img src="{{ base_path }}/images/mm-home-post-pagination-example.jpg" alt="home page post pagination example">
  <figcaption>Home page post pagination example.</figcaption>
</figure>

**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

To add some visual punch to a post or page, a large full-width header image can be included.

**Note:** Be sure to resize your header images. `~1280px` is a good medium if you aren't [responsively serving up images](http://alistapart.com/article/responsive-images-in-practice). Through the magic of CSS they will scale up or down to fill the container. If you go with something too small it will look like garbage when upscaled, and something too large will hurt performance.
{: .notice--warning}

![single layout header image example]({{ base_path }}/images/mm-single-header-example.jpg)

Place your images in the `/images/` folder and add the following YAML Front Matter:

```yaml
header:
  image: image-filename.jpg
```

For externally hosted images include the full image path instead of just the filename:

```yaml
header:
  image: http://some-site.com/image.jpg
```

To include a caption or attribution for the image:

```yaml
header:
  image: unsplash-image-1.jpg
  caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
```

**ProTip:** Captions written in Markdown are supported, so feel free to add links, or style text. Just be sure to wrap it in quotes.
{: .notice--info}

### Header Overlay

To overlay text on top of a header image you have a few more options:

| Name              | Description | Default |
| ----              | ----------- | ------- |
| **overlay_image** | Header image you'd like to overlay. Same rules as `header.image` from above. | |
| **excerpt**       | Auto-generated page excerpt is added to the overlay text or can be overridden. | |
| **cta_label**     | Call to action button text label. | `more_label` in UI Text data file |
| **cta_url**       | Call to action button URL. | |

With this YAML Front Matter:

```yaml
excerpt: "This post should display a **header with an overlay image**, if the theme supports it."
header:
  overlay_image: unsplash-image-1.jpg
  caption: "Photo credit: [**Unsplash**](https://unsplash.com)"
  cta_label: "More Info"
  cta_url: "https://unsplash.com"
```

You should get an header image overlaid with text and a call to action button.

![single layout header overlay example]({{ base_path }}/images/mm-single-header-overlay-example.jpg)

You also have the option of specifying a solid background-color to use instead of an image.

![single layout header overlay with background fill]({{ base_path }}/images/mm-single-header-overlay-fill-example.jpg)

```yaml
excerpt: "This post should display a **header with a solid background color**, if the theme supports it."
header:
  overlay_color: "#333"
```

---

## Sidebars

The space to the left of a page's main content is blank by default, but has the option to show an author profile (name, short biography, social media links), custom content, or both.

### Author Profile

Add `author_profile: true` to a post or page's YAML Front Matter.

![single layout example]({{ base_path }}/images/mm-layout-single.png)

Better yet, enable it with Front Matter Defaults set in `_config.yml`.

```yaml
defaults:
  # _posts
  - scope:
      path: ""
      type: posts
    values:
      author_profile: true
```

**Note:** To disable the author sidebar profile for a specific post or page, add `author_profile: false` to the YAML Front Matter instead.
{: .notice--warning}

### Custom Sidebar Content

Blocks of content can be added by using the following under `sidebar`:

| Name          | Description                                                |
| ----          | -----------                                                |
| **title**     | Title or heading.                                          |
| **image**     | Image path placed in `/images/` folder or an external URL. |
| **image_alt** | Alternate description for image.                           |
| **text**      | Text. Markdown is allowed.                                 |

Multiple blocks can also be added by following the example below:

```yaml
sidebar:
  - title: "Title"
    image: http://placehold.it/350x250
    image_alt: "image"
    text: "Some text here."
  - title: "Another Title"
    text: "More text here."
```

<figure>
  <img src="{{ base_path }}/images/mm-custom-sidebar-example.jpg" alt="custom sidebar content example">
  <figcaption>Example of custom sidebar content added as YAML Front Matter.</figcaption>
</figure>

**ProTip:** Custom sidebar content added to a post or page's YAML Front Matter will appear above the author profile if enabled with `author_profile: true`.
{: .notice--info}
Add screenshots of various layouts included with the theme 2016-04-10 04:06:16 +02:00			`---`
			`title: "Layouts"`
			`permalink: /docs/layouts/`
			`excerpt:`
			`sidebar:`
			`title: "v3.0"`
			`nav: docs`
Update layout docs 2016-04-12 18:04:16 +02:00			`single_layout_gallery:`
			`- image_path: mm-layout-single-header.png`
			`alt: "single layout with header example"`
			`- image_path: mm-layout-single-meta.png`
			`alt: "single layout with comments and related posts"`
Add screenshots of various layouts included with the theme 2016-04-10 04:06:16 +02:00			`---`

			`{% include base_path %}`
Update docs 2016-04-11 22:19:43 +02:00			`{% include toc icon="columns" title="Included Layouts" %}`

			`The bread and butter of any theme. Below you'll find the layouts included with Minimal Mistakes, what they look like and the type of content they've been built for.`

Update archive layout docs 2016-04-12 19:09:05 +02:00			`## Default Layout`
Update docs 2016-04-11 22:19:43 +02:00
			The base layout all other layouts inherit from. There's not much to this layout apart from pulling in several `_includes`:

			* `<head>` elements
			`* masthead navigation links`
			* {% raw %}`{{ content }}`{% endraw %}
			`* page footer`
			`* scripts`

			Note: You won't ever assign this layout directly to a post or page. Instead all other layouts will build off of it by setting `layout: default` in their YAML Front Matter.
			`{: .notice--warning}`

Update archive layout docs 2016-04-12 19:09:05 +02:00			`## Compress Layout`
Update docs 2016-04-11 22:19:43 +02:00
			`A Jekyll layout that compresses HTML in pure Liquid.`

			`* [Documentation](http://jch.penibelst.de/)`
Add screenshots of various layouts included with the theme 2016-04-10 04:06:16 +02:00
Update archive layout docs 2016-04-12 19:09:05 +02:00			`## Single Layout`
Add screenshots of various layouts included with the theme 2016-04-10 04:06:16 +02:00
Update docs 2016-04-12 22:48:27 +02:00			`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`
Update docs 2016-04-11 22:19:43 +02:00
Update layout docs 2016-04-12 18:04:16 +02:00			{% include gallery id="single_layout_gallery" caption="Image header and meta info examples for `single` layout" %}

Update archive layout docs 2016-04-12 19:09:05 +02:00			Assign with `layout: single`, or better yet apply as a [Front Matter default]({{ base_path }}/docs/configuration/#front-matter-defaults) in `_config.yml`.
Update docs 2016-04-11 22:19:43 +02:00
Update archive layout docs 2016-04-12 19:09:05 +02:00			`## Archive Layout`

			Essentially the same as `single` with markup adjustments and some modules removed.

Update docs 2016-04-12 22:48:27 +02:00			`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>`
Update archive layout docs 2016-04-12 19:09:05 +02:00
			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.

Update docs 2016-04-12 22:48:27 +02:00			`* [All Posts Grouped by Category -- List View][posts-categories]`
			`* [All Posts Grouped by Tags -- List View][posts-tags]`
			`* [All Posts Grouped by Year -- List View][posts-year]`
			`* [All Posts Grouped by Collection -- List View][posts-collection]`
			`* [Portfolio Collection -- Grid View][portfolio-collection]`

			`[posts-categories]: {{ site.gh_repo }}/gh-pages/_pages/category-archive.html`
			`[posts-tags]: {{ site.gh_repo }}/gh-pages/_pages/tag-archive.html`
			`[posts-year]: {{ site.gh_repo }}/gh-pages/_pages/year-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`
			`---`
			```
Update archive layout docs 2016-04-12 19:09:05 +02:00
Update docs 2016-04-12 22:48:27 +02:00			`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}`
Update archive layout docs 2016-04-12 19:09:05 +02:00
			`### Taxonomy Archive`

			If you have the luxury of using Jekyll plugins the creation of category and tag archives is greatly simplified. Enable support for the [`jekyll-archives`](https://github.com/jekyll/jekyll-archives) plugin with a few `_config.yml` settings as noted in the [Configuration]({{ base_path }}/docs/configuration/#archive-settings) section.

			`![archive taxonomy layout example]({{ base_path }}/images/mm-layout-archive-taxonomy.png)`

			`### Home Page`

Update docs 2016-04-12 22:48:27 +02:00			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:
Update archive layout docs 2016-04-12 19:09:05 +02:00
			```html
			`{% raw %}<!-- start index.html body -->`
			`{% include base_path %}`

			`<h3 class="archive__subtitle">Recent Posts</h3>`

			`{% for post in paginator.posts %}`
			`{% include archive-single.html %}`
			`{% endfor %}`

			`{% include paginator.html %}`
			`<!-- end index.html body -->{% endraw %}`
			```

			`<figure>`
			`<img src="{{ base_path }}/images/mm-home-post-pagination-example.jpg" alt="home page post pagination example">`
			`<figcaption>Home page post pagination example.</figcaption>`
			`</figure>`

Update docs 2016-04-12 22:48:27 +02:00			`Note: For more pagination related settings check the [Configuration]({{ base_path }}/docs/configuration/#paginate) section.`
Update archive layout docs 2016-04-12 19:09:05 +02:00			`{: .notice--info}`

			`## Splash Page Layout`

Update docs 2016-04-12 22:48:27 +02:00			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)

Update archive layout docs 2016-04-12 19:09:05 +02:00			`![splash page layout example]({{ base_path }}/images/mm-layout-splash.png)`

Update docs 2016-04-12 22:48:27 +02:00			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).


Update archive layout docs 2016-04-12 19:09:05 +02:00			`---`

			`## Headers`
Update docs 2016-04-11 22:19:43 +02:00
			`To add some visual punch to a post or page, a large full-width header image can be included.`

			Note: Be sure to resize your header images. `~1280px` is a good medium if you aren't [responsively serving up images](http://alistapart.com/article/responsive-images-in-practice). Through the magic of CSS they will scale up or down to fill the container. If you go with something too small it will look like garbage when upscaled, and something too large will hurt performance.
			`{: .notice--warning}`

			`![single layout header image example]({{ base_path }}/images/mm-single-header-example.jpg)`

			Place your images in the `/images/` folder and add the following YAML Front Matter:

			```yaml
			`header:`
			`image: image-filename.jpg`
			```

			`For externally hosted images include the full image path instead of just the filename:`

			```yaml
			`header:`
			`image: http://some-site.com/image.jpg`
			```

			`To include a caption or attribution for the image:`

			```yaml
			`header:`
			`image: unsplash-image-1.jpg`
			`caption: "Photo credit: [Unsplash](https://unsplash.com)"`
			```

			`ProTip: Captions written in Markdown are supported, so feel free to add links, or style text. Just be sure to wrap it in quotes.`
			`{: .notice--info}`

			`### Header Overlay`

			`To overlay text on top of a header image you have a few more options:`

Update table 2016-04-13 17:29:09 +02:00			`\| Name \| Description \| Default \|`
			`\| ---- \| ----------- \| ------- \|`
			\| overlay_image \| Header image you'd like to overlay. Same rules as `header.image` from above. \| \|
			`\| excerpt \| Auto-generated page excerpt is added to the overlay text or can be overridden. \| \|`
			\| cta_label \| Call to action button text label. \| `more_label` in UI Text data file \|
			`\| cta_url \| Call to action button URL. \| \|`
Update docs 2016-04-11 22:19:43 +02:00
			`With this YAML Front Matter:`

			```yaml
			`excerpt: "This post should display a header with an overlay image, if the theme supports it."`
			`header:`
			`overlay_image: unsplash-image-1.jpg`
			`caption: "Photo credit: [Unsplash](https://unsplash.com)"`
			`cta_label: "More Info"`
			`cta_url: "https://unsplash.com"`
			```

			`You should get an header image overlaid with text and a call to action button.`

			`![single layout header overlay example]({{ base_path }}/images/mm-single-header-overlay-example.jpg)`

			`You also have the option of specifying a solid background-color to use instead of an image.`

			`![single layout header overlay with background fill]({{ base_path }}/images/mm-single-header-overlay-fill-example.jpg)`

			```yaml
			`excerpt: "This post should display a header with a solid background color, if the theme supports it."`
			`header:`
			`overlay_color: "#333"`
			```

Update archive layout docs 2016-04-12 19:09:05 +02:00			`---`

			`## Sidebars`
Update layout docs 2016-04-12 18:04:16 +02:00
			`The space to the left of a page's main content is blank by default, but has the option to show an author profile (name, short biography, social media links), custom content, or both.`

Update archive layout docs 2016-04-12 19:09:05 +02:00			`### Author Profile`
Update layout docs 2016-04-12 18:04:16 +02:00
			Add `author_profile: true` to a post or page's YAML Front Matter.
Update docs 2016-04-11 22:19:43 +02:00
Add screenshots of various layouts included with the theme 2016-04-10 04:06:16 +02:00			`![single layout example]({{ base_path }}/images/mm-layout-single.png)`

Update layout docs 2016-04-12 18:04:16 +02:00			Better yet, enable it with Front Matter Defaults set in `_config.yml`.

			```yaml
			`defaults:`
			`# _posts`
			`- scope:`
			`path: ""`
			`type: posts`
			`values:`
			`author_profile: true`
			```

			Note: To disable the author sidebar profile for a specific post or page, add `author_profile: false` to the YAML Front Matter instead.
			`{: .notice--warning}`

Update archive layout docs 2016-04-12 19:09:05 +02:00			`### Custom Sidebar Content`
Add screenshots of various layouts included with the theme 2016-04-10 04:06:16 +02:00
Update layout docs 2016-04-12 18:04:16 +02:00			Blocks of content can be added by using the following under `sidebar`:

Update table 2016-04-13 17:29:09 +02:00			`\| Name \| Description \|`
			`\| ---- \| ----------- \|`
			`\| title \| Title or heading. \|`
			\| image \| Image path placed in `/images/` folder or an external URL. \|
			`\| image_alt \| Alternate description for image. \|`
			`\| text \| Text. Markdown is allowed. \|`
Update layout docs 2016-04-12 18:04:16 +02:00
			`Multiple blocks can also be added by following the example below:`

			```yaml
			`sidebar:`
			`- title: "Title"`
			`image: http://placehold.it/350x250`
			`image_alt: "image"`
			`text: "Some text here."`
			`- title: "Another Title"`
			`text: "More text here."`
			```

			`<figure>`
			`<img src="{{ base_path }}/images/mm-custom-sidebar-example.jpg" alt="custom sidebar content example">`
			`<figcaption>Example of custom sidebar content added as YAML Front Matter.</figcaption>`
			`</figure>`

			ProTip: Custom sidebar content added to a post or page's YAML Front Matter will appear above the author profile if enabled with `author_profile: true`.
Update archive layout docs 2016-04-12 19:09:05 +02:00			`{: .notice--info}`