Feature: Introductory text for autopages, etc.

[ibrado]

This implements an "intro" feature as discussed in #58.

Given the following in _config.yml:

pagination:
  intro: "intro.md"

creating a file with the name "intro.md" (or ending in "-intro.md") would insert that file as the introductory text for a collection, posts, etc. according to its location and/or filters (categories, tags, etc.). The file would be fully rendered (Liquid and Markdown) where the following is placed:

{{ paginator.intro }}

Using this could be as simple as dropping an "intro.md" into a collections folder, but the general rule is, as long as you can get an entry to appear uniquely in a pagination page/autopage, you can use it as an intro simply by renaming it and removing its layout:, if necessary.

For example, examples/03-tags/_romance could have a file histrom-intro.md as follows:

---
tags: historical, fiction
---

This is the intro for **Historical Romance** books.

and it will be rendered like so after adding {{ paginator.intro }} to _layouts/autopage_collection.html:

This also works for posts. Adding {{ paginator.intro }} to examples/01-typicalblog/_layouts/home.html and creating _posts/0000-00-00-main-intro.md as follows:

---
date: 2018-01-29 22:59:19 +0800
---

This is the introduction to the blog.

would render as follows:

[sverrirs]

I don't know about this feature. It honestly seems out of scope for this plugin. I would like to investigate ways to support this in a more Jekyll native way before adding this feature to the gem. The next thing that will be asked for it a text after the pagination. Feels like this should rather be handled by the layout template somehow (just not sure yet how to do it)

[ibrado]

Well, I did start on it because you said in #58 :

This actually sounds like a feature that is missing from the autopages at the moment (inclusion of some piece of text/html at the top of the pagination. If you feel up to making the feature I'll accept a PR.

Your decision, of course. I'm fine either way. :-)

[sverrirs]

eeps, this is my bad, I really didn't think this through... I'm sorry to yoyo like this :/
Thanks for putting in the effort, let me think about this a little bit. Maybe we can come up with something together that is a little more "flexible".

[mmistakes]

For what it's worth I do something similar with pure Liquid and a Jekyll data file to add introductory text to various tag pages generated with the Autopage module.

In the data file I add a set of key/value pairs with descriptive text.

# _data/taxonomy.yml

tag1:
  description: "This describes tag 1."

tag2:
  description: "This describes **tag 2**."

Then in my layout I use something like this to pull in the text (if available). If not it fallsback to some default text.

{% assign taxonomy = page.autopages.display_name | downcase | slugify %}
{% assign tag = site.data.taxonomy[taxonomy] %}

{% if tag.description %}
  {{ tag.description | markdownify }}
{% else %}
  <p>An archive of posts tagged <em>{{ page.autopages.display_name }}</em>.</p>
{% endif %}

[ibrado]

@mmistakes I also do something similar, for plaintext introductions. This patch still has some value if one needs Liquid and Markdown in the intro text.