Minimal-mistakes: How to customize the category/tag pages generated by jekyll-archive?

[billgarrison]

• [x] This is a question about using the theme.
• [ ] I believe this to be a bug with the theme --- not Jekyll, GitHub Pages or one of the bundled plugins.
• [ ] This is a feature request.
• [x] I have updated all gems with bundle update.
• [x] I have tested locally with bundle exec jekyll build.

---

Environment informations

• *Minimal Mistakes version:4.2.1*
• *jekyll gem version:3.4.0*
  

  - Operating system:Mac OS 10.11.6

Expected behavior

I'd like to add an overlay header to the pages generated by the jekyll-archive plugin. My approach has been to override the theme's archive-taxonomy.html layout and add the relevant overlay image config to the front matter. It's not working for me.

A whack with a clue stick would be appreciated.

Steps to reproduce the behavior

jekyll-archive config

I have jekyll-archive installed and it is generating a page for each tag and category as expected, just not with the header image I'd like. Here's the relevant section of _config.yml

category_archive:
  type: jekyll-archives
  path: /categories/
tag_archive:
  type: jekyll-archives
  path: /tags/
jekyll-archives:
  enabled:
    - year
    - categories
    - tags
  layouts:
    category: archive-taxonomy
    tag: archive-taxonomy
  permalinks:
    year: /year
    category: /categories/:name/
    tag: /tags/:name/

theme layout override

To override the theme, made a local copy of archive-taxonomy.html, and added header: info to the layout's front matter.

layout: default
author_profile: false

header: 
       overlay_image: "/assets/images/brick-banner-3.png"
       overlay_filter: rgba(0, 0, 0, 0.15)
       cta_label: "Book Now"
       cta_url: "/booknow"
---

[mmistakes]

That layout doesn't have the Liquid code for headers. Take a look at the standard archive.html to see what code you'd need to add to the taxonomy one for them to work.

The YAML you're using is fine it just needs the layout code to make it show up.

[billgarrison]

OK. I did that, pulling in

{% if page.header.overlay_color or page.header.overlay_image or page.header.image %}
  {% include page__hero.html %}
{% elsif page.header.video.id and page.header.video.provider %}
  {% include page__hero_video.html %}
{% endif %}

No go. In doing some caveman debugging, it looks like thepage object doesn't have any header info in it. The generated category/tag pages have the following info for page:

page: {{ page }}

page: {"layout"=>"archive-taxonomy", "posts"=>[#], "type"=>"tag", "title"=>"coupons", "date"=>nil, "name"=>"index", "path"=>"tags/coupons/index.html", "url"=>"/tags/coupons/"}

If I explicitly ask for page.header.overlay_image, I get nothing back in the generated page.

[mmistakes]

Think that's a causality of using Jekyll Archives. It has access to certain objects, page likely isn't one of them, at least not in the way you're trying to access it. I'm sure there's a way to do it but you might need to get creative.

I'd inquire with that plugin as I don't really know much more about it other than what they've documented here.

[billgarrison]

Thanks! I think you're right. Digging through the plugin code, it restricts Liquid to a fixed set of attributes on page, and doesn't pay any attention to extra data in the layout front matter.

That's fine. I spent a few hours learning how plugins work and how to debug Ruby. So, +1 for that! :-)

[billgarrison]

I solved this finally, by copying the relevant layout code from page__hero.html into a custom layout file for jekyll-archive to use. The generated category/tag pages match the styling of the rest of my site.

Thanks very much for the help. :-)

[billgarrison]

Captain's Log: Supplemental

After closing this issue, I read somewhere else that since Jekyll 3, layout front matter is no longer made accessible to Liquid via the page variable, but through layout.

So, I tried the approach of customizing archive.html to access the header front matter info through layout.header in the Liquid. Changing the jekyll-archive config to use my customized layout, that approach worked fine. I had to pull in sidebar.html and tweak it to access sidebar definitions through layout also.

Ultimately, it was a "6 of one, half dozen of the other" solution. Copying pieces of Liquid code out of archive.html & sidebar.html into new layout, versus copying layout files and modifying them to access info through the layout variable, both required about the same amount of work.

Just wanted to offer this up as a viable alternative solution to customizing pages generated by jekyll-archive.

[mmistakes]

There's probably some Liquid voodoo that might be possible to determine what layout is in use and then apply page. or layout. accordingly. Versus duplicating all of the includes into the Jekyll Archives just to make that minor change.

Would DRY things up some too. All hypothetical though as I haven't tested it :wink:

[ohadschn]

I wonder, has there been any news on this? Is there some simpler way to customize the category/tag pages generated by jekyll-archives (e.g. add a header image)?

[mmistakes]

@ohadschn Your best bet is opening a feature request on jekyll-archives to allow for it. There's really only a few variables exposed at the archive page level through the plugin... all of which are related to getting the title.

As I mentioned above, if you're properly motivated you can come up with some custom Liquid to do it. I did just this on one project.

For example say you're creating a set of tag archives and what a header image on them that corresponds with the current tag... let's call that foo.

What you can do is in your tag archive layout add something like:

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

What this does is take the page.title, which in this case will be Foo and does some normalizing (lowercase, replace spaces with -, etc.). If the title was "Foo Bar" you'd get foo-bar. This gives you a predictable value you can use as a "key" in a data file. In this case _data/taxonomy.yml.

Which looks something like:

foo:
  description: "Foo is an example of foo."
  image: /path-to-image-foo.jpg

foo-bar:
  description: "Foo Bar is an example of foo + bar."
  image: /path-to-image-foo-bar.jpg

Through the assigns above you can easily pull in this data into the tag archive layout now:

{% if tag.image %}
  <img src="{{ tag.image }}" alt="">
{% endif %}

I used this method to add detailed descriptions for each tag archive page. But you can use it to assign images and any other data you can dream up. You can see examples of my old tag archive layout and taxonomy.yml files here.

[ohadschn]

@mmistakes thank you for the detailed explanation!

I had something simpler in mind though, just a static header: image: foo.jpg to all archive pages. I was wondering if there were a simpler way to do that than the one outlined by @billgarrison above (I prefer to override as little as possible in order to enjoy the most of future updates), but I gather currently there is not, due to lack of access to the headers liquid code in that scope.

I opened an issue with jekyll-archives: https://github.com/jekyll/jekyll-archives/issues/107.

[mmistakes]

You could always just create your own jekyll-archives layout that has the page header image hard coded in it.

[ohadschn]

I'm confused, isn't this what the OP initially tried to do and failed because the archive-taxonomy.html layout doesn't have the Liquid code for headers? (I tried the same to verify, indeed it didn't work and no image was displayed)

[mmistakes]

Depends on what you want to do.

If you want all of the archive pages to have the same image you can just dump that into a new layout. If you want something more dynamic and unique for each page then my solution above will work. You'll add around 4 lines of Liquid to it, or you can wait for a feature add to jekyll-archives.

[mmistakes]

Also, even if that layout had the header logic, it would just comes across as null because Jekyll-archives has no concept of the page object to pass data.

You need to use my method above to assign data from a data file so it has something to populate the header with. Since that is highly custom it won't ever be included in the theme. That layout is fairly barebones so you'll be safe overriding it with your own custom logic.

[ohadschn]

So when you say "If you want all of the archive pages to have the same image you can just dump that into a new layout" you mean write the actual HTML into archive-taxonomy.html (e.g. img src), rather than use the header logic?

[mmistakes]

Correct.

[ohadschn]

Does this _layouts/archive-taxonomy.html override look about right (it seems to work)?

---
layout: default
author_profile: false
---

<div class="page__hero">
  <img src="{{url}}/images/my-shared-header-image.jpg" class="page__hero-image">
</div>

<div id="main" role="main">
  {% include sidebar.html %}

  <div class="archive">
    <h1 class="page__title">{{ page.title }}</h1>
    {% for post in page.posts %}
      {% include archive-single.html %}
    {% endfor %}
  </div>
</div>

[mmistakes]

{{url}} won't do anything, you'll probably want to switch that to {{ site.url }} or better yet leverage Jekyll's absolute or relative filters.

<img src="{{ '/images/my-shared-header-image.jpg' | absolute_url }}" class="page__hero-image">

[ohadschn]

BTW for anyone wondering how my initial link worked (using the non-existent {{url}}), it simply evaluated to nothing and /foo/resource works when your site is served off the root/apex of the domain...