Update docs
This commit is contained in:
Michael Rose
parent
29a47da3f2
commit
c1a9f8d9cb
11 changed files with 260 additions and 39 deletions
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
* `facebook`: Facebook Comments
|
||||
* `google-plus`: Google+
|
||||
* `custom`: other comment providers
|
||||
| | Comment Provider |
|
||||
| ------------- | ---------------- |
|
||||
| `disqus` | Disqus |
|
||||
| `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/)
|
||||
* `google-universal`: [Google Universal Analytics](https://www.google.com/analytics/)
|
||||
* `custom`: other analytics providers
|
||||
| | Analytics Provider |
|
||||
| ------------------ | ------------------ |
|
||||
| `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.
|
||||
* [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
|
||||
| Plugin | Description |
|
||||
| ------ | ----------- |
|
||||
| [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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
**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 Tags][posts-tags]
|
||||
* [All Posts Grouped by Year][posts-year]
|
||||
* [All Posts Grouped by Collection][posts-collection]
|
||||
* [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 }}/blob/gh-pages/_pages/category-archive.html
|
||||
[posts-tags]: {{ site.gh_repo }}/blob/gh-pages/_pages/tag-archive.html
|
||||
[posts-year]: {{ site.gh_repo }}/blob/gh-pages/_pages/year-archive.html
|
||||
[posts-collection]: {{ site.gh_repo }}/blob/gh-pages/_pages/collection-archive.html
|
||||
[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
|
||||
|
||||
|
|
@ -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)
|
||||
|
||||
|
||||
|
||||
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.
|
||||
* `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
|
||||
| Front Matter variable | Description |
|
||||
| --------------------- | ----------- |
|
||||
| `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 (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
|
||||
* `image` --- image path placed in `/images/` folder or an external URL
|
||||
* `image_alt` --- alt description for image
|
||||
* `text` --- Markdown supported text
|
||||
| Front Matter variable | Description |
|
||||
| --------------------- | ----------- |
|
||||
| `title` | Title or heading. |
|
||||
| `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:
|
||||
|
||||
|
|
|
|||
34
_docs/10-posts.md
Normal file
34
_docs/10-posts.md
Normal 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
47
_docs/11-pages.md
Normal 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
47
_docs/12-collections.md
Normal 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.
|
||||
|
||||
|
||||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
========================================================================== */
|
||||
|
||||
table {
|
||||
margin-bottom: 1em;
|
||||
width: 100%;
|
||||
font-family: $global-font-family;
|
||||
font-size: $type-size-6;
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
BIN
images/mm-archive-grid-view-example.jpg
Normal file
BIN
images/mm-archive-grid-view-example.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
BIN
images/mm-portfolio-collection-example.jpg
Normal file
BIN
images/mm-portfolio-collection-example.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 248 KiB |
Loading…
Reference in a new issue