From 0b07c20c84a5419541054ff4cd7b06d9bd6dbe58 Mon Sep 17 00:00:00 2001 From: Alex Sarafian Date: Thu, 9 Feb 2017 20:33:14 +0100 Subject: [PATCH] Improve the documentation for novice users (Tags+Categories and Pagination) (#826) * Enhanced the documentation with some tips for the tags, categories and paginator * Enhanced the documentation with some tips for the tags, categories and paginator * Update 05-configuration.md * Update 10-layouts.md --- docs/_docs/05-configuration.md | 8 +++++++- docs/_docs/10-layouts.md | 30 +++++++++++++++++++++++++++++- 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/_docs/05-configuration.md b/docs/_docs/05-configuration.md index 0c95ff5e340f..c9df3f642401 100644 --- a/docs/_docs/05-configuration.md +++ b/docs/_docs/05-configuration.md @@ -524,7 +524,13 @@ paginate: 5 You'll also need to include some Liquid and HTML to properly use the paginator, which you can find in the **Layouts** section under [Home Page]({{ "/docs/layouts/#home-page" | absolute_url }}). -**Please note:** [Jekyll's pagination](http://jekyllrb.com/docs/pagination/) may have unexpected results when used on pages other than the home page eg. `/blog/index.html`. +The paginator only works on files with name `index.html`. To use pagination in a subfolder --- for example `/recent/`, create `/recent/index.html` and set the `paginate_path` in `_config.yml` to this: + +```yaml +paginate_path: /recent/page:num/ +``` + +**Please note:** When using Jekyll's default [pagination plugin](http://jekyllrb.com/docs/pagination/) `paginator.posts` can only be called once. If you're looking for something more powerful that can paginate category, tag, and collection pages I suggest [**jekyll-paginate-v2**](https://github.com/sverrirs/jekyll-paginate-v2). {: .notice--info} ### Timezone diff --git a/docs/_docs/10-layouts.md b/docs/_docs/10-layouts.md index a8b60ced04d2..4fabef0d1bd3 100644 --- a/docs/_docs/10-layouts.md +++ b/docs/_docs/10-layouts.md @@ -155,10 +155,38 @@ To produce something like this: ### 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**]({{ "/docs/configuration/#archive-settings" | absolute_url }}) section. +If you have the luxury of using Jekyll plugins, the creation of category and tag archives is greatly simplified. Simply enable support for the [`jekyll-archives`](https://github.com/jekyll/jekyll-archives) plugin with a few `_config.yml` settings as noted in the [**Configuration**]({{ "/docs/configuration/#archive-settings" | absolute_url }}) section and you're good to go. ![archive taxonomy layout example]({{ "/assets/images/mm-layout-archive-taxonomy.png" | absolute_url }}) +If you're not using the `jekyll-archives` plugin then you need to create archive pages yourself. Sample taxonomy archives can be found by grabbing the HTML sources below and adding to your site. + +| Name | HTML Source | +| -------------------- | --- | +| [Categories Archive](https://mmistakes.github.io/minimal-mistakes/categories/) | [category-archive.html](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/category-archive.html) | +| [Tags Archive](https://mmistakes.github.io/minimal-mistakes/tags/) | [tag-archive.html](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/tag-archive.html) | + +The **Tags Archive** page that responds to urls such as `/tags/#tips` looks something like this: + +```html +--- +layout: archive +permalink: /tags/ +title: "Posts by Tags" +author_profile: true +--- + +{% include group-by-array collection=site.posts field="tags" %} + +{% for tag in group_names %} + {% assign posts = group_items[forloop.index0] %} +

{{ tag }}

+ {% for post in posts %} + {% include archive-single.html %} + {% endfor %} +{% endfor %} +``` + ### Home Page A derivative archive page layout to be used as a simple home page. It is built to show a paginated list of recent posts based off of the [pagination settings]({{ "/docs/configuration/#paginate" | absolute_url }}) in `_config.yml`.