Update docs

This commit is contained in:
Michael Rose 2016-04-12 16:48:27 -04:00
parent 29a47da3f2
commit c1a9f8d9cb
11 changed files with 260 additions and 39 deletions

View file

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

View file

@ -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: 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. 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: 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 ```yaml
analytics: 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. 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 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. 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-paginate]: https://github.com/jekyll/jekyll-paginate
[jekyll-sitemap]: https://github.com/jekyll/jekyll-sitemap [jekyll-sitemap]: https://github.com/jekyll/jekyll-sitemap

View file

@ -38,7 +38,15 @@ A Jekyll layout that compresses HTML in pure Liquid.
## Single Layout ## 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" %} {% 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. 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. 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 ### Taxonomy Archive
@ -70,7 +132,15 @@ If you have the luxury of using Jekyll plugins the creation of category and tag
### Home Page ### 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 ```html
{% raw %}<!-- start index.html body --> {% 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> <figcaption>Home page post pagination example.</figcaption>
</figure> </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} {: .notice--info}
## Splash Page Layout ## 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) ![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 ## Headers
@ -138,10 +219,12 @@ header:
To overlay text on top of a header image you have a few more options: 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: With this YAML Front Matter:
@ -199,10 +282,12 @@ defaults:
Blocks of content can be added by using the following under `sidebar`: 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: Multiple blocks can also be added by following the example below:

34
_docs/10-posts.md Normal file
View file

@ -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}

47
_docs/11-pages.md Normal file
View file

@ -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
```

47
_docs/12-collections.md Normal file
View file

@ -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)

View file

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

View file

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

File diff suppressed because one or more lines are too long

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 248 KiB