Documentation not correct for jekyll-archives

[Sarafian]

• This is a question about using the theme.
• I have updated all gems with bundle update.
• I have tested locally with bundle exec jekyll build.

---

Environment informations

• Minimal Mistakes version:
• github-pages or jekyll gem version: github-pages 118
• Operating system: Windows 10

---

Expected behavior

/tags/ and /categories/ working

Steps to reproduce the behavior

Just forked and followed the instructions. But I couldn't get the instructions to work to generate tags and categories links.

I think the mistake is that the Gemfile is missing the reference to jekyll-archives and that the instructions do not mention that in the _config.yml has the `jekyll-archives section needs to uncommented.

# Archives
#  Type
#  - GitHub Pages compatible archive pages built with Liquid ~> type: liquid (default)
#  - Jekyll Archives plugin archive pages ~> type: jekyll-archives
#  Path (examples)
#  - Archive page should exist at path when using Liquid method or you can
#    expect broken links (especially with breadcrumbs enabled)
#  - <base_path>/tags/my-awesome-tag/index.html ~> path: /tags/
#  - <base_path/categories/my-awesome-category/index.html ~> path: /categories/
#  - <base_path/my-awesome-category/index.html ~> path: /
category_archive:
  type: liquid
  path: /categories/
tag_archive:
  type: liquid
  path: /tags/
# https://github.com/jekyll/jekyll-archives
# jekyll-archives:
#   enabled:
#     - categories
#     - tags
#   layouts:
#     category: archive-taxonomy
#     tag: archive-taxonomy
#   permalinks:
#     category: /categories/:name/
#     tag: /tags/:name/

[mmistakes]

The theme docs mention you need the Jekyll Archives plugin, which has a link to their instructions on how to install it. I just assumed anyone who wanted to go that route would read-up on the plugin and how to install/setup.

It's not installed by default because it doesn't work with GitHub Pages. To install gem install jekyll-archives or add it under the plugins group in your Gemfile

group :jekyll_plugins do
  gem "jekyll-archives"
end

Then run bundle install.

Happy to accept pull requests to make the theme docs more clear.

[Sarafian]

@mmistakes I need to work with GitHub pages. You can consider then this bug as wrong.
The reason I went for jekyll-pages is that as it is I can't get the /tags/ and /categories/ to work with the default.

[Sarafian]

I'm a real noob with Jekyll and in general not very good with html.
I had a very hard time getting basic tags/categories functionality and I think we should improve the doc here. Before I make a pull request I would like to ask for someone to check this commit that represents what I did to achieve my goal.

I can only support the /tags/#tag and /categories/#category.

[mmistakes]

You can certainly do it that way. For the theme I approached it with a slightly DRYer approach (Don't Repeat Yourself). Instead of creating layouts for the category page and another one for tags they both use the same _layouts/archive.html. Less files to maintain that way.

Then each page (categories/tags) use the group-by-array helper to construct the appropriate for loops. Both of these pages are provided as samples to get you started and are mentioned in the documentation. I could probably call them out more since they're often missed.

• Category archive (eg. /categories/#category)
• Tag archive (eg. /tags/#tag)

[Sarafian]

Thank you so much. To be honest, as a Jekyll novice, I've wasted many hours getting to those changes.
It was not clear from me from the docs that I could actually get those pages for the tags/categories functionality. I also searched but I missed it because the file name doesn't match the expectation because of the permlink

We can close this issue but I would consider making it more clear in the documentation, so other novices don't spend so much time on something as basic as tags/categories.

[PumpMagic]

Chiming in to say I was also having a hard time figuring out getting tags working with GH pages. I hadn't seen the sample pages @mmistakes mentioned, but those got me up and running. Big thanks to both of you.

This theme's documentation has been invaluable as a novice learning Jekyll.

[mmistakes]

Updated in latest release https://github.com/mmistakes/minimal-mistakes/releases/tag/4.2.2

[ohadschn]

I clarified the docs using the guidance above.

@mmistakes - can we get the "posts by category" experience using jekyll-archive (like https://mmistakes.github.io/minimal-mistakes/categories/)?

I have categories working (https://blog.ohadsoft.com/categories/uncategorized/) but this is a 404: https://blog.ohadsoft.com/categories/ (source: https://gitlab.com/ohadschn/ohadschn.gitlab.io).

[mmistakes]

@ohadschn Yeah you can. You have to manually add a "posts by category" page. Same for tags. The source for both are in the /docs/_pages folder (as mentioned a few comments above).

• https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/category-archive.html
• https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/tag-archive.html

[ohadschn]

@mmistakes Ah that works, thanks!

I'm confused now though. If I need to put those pages there myself anyway, what do I gain from using jekyll-archive?

[mmistakes]

You don't. jekyll-archives only generates archives for specific taxonomies (or dates if configured). It doesn't create an index page that lists all posts grouped by category or tag, which is what those links above do.

For example if you have a post with categories: foo, bar. Depending on your permalink structure you'll get something like /categories/foo/index.html and /categories/bar/index.html. What you won't get is /categories/index.html...

Make sense?

[ohadschn]

Ahhh, now I understand:

1. If I want a taxonomy (tag/category) index, I need _pages/category-archive.html and _pages/tag-archive.html as described above, regardless of whether I use jekyll-archives or not.
2. If I use pure liquid, taxonomy links would simply point to the corresponding index page above with a hash link, e.g.: https://mysite.com/categories/#foo (so that the entire index opens but the browser jumps to the corresponding section in the index).
3. If I use jekyll-archives, taxonomy items get their own proper page automatically generated pointed to by "real" (non-hash) links, e.g.: https://mysite.com/categories/foo (which is independent of the full taxonomy index).

[ohadschn]

@mmistakes what type do the jekyll-archives-generated discrete taxonomy pages have for the purposes of _config.yml Front Matter defaults? Neither posts nor pages seem to catch them...

[mmistakes]

That's a question for the maintainers of the jekyll-archives plugin. I've never tried to set front matter defaults on them, so not sure if it's even possible.

I've only ever set defaults on posts, pages, and collections.

[ohadschn]

jekyll/jekyll-archives#107

[ohadschn]

Also related: #832

[ghost]

Doesn't jekyll-archives accept another word for categories?

So, I'm not able to get it to work on a blog where I'm calling it topics instead of categories. Now I got the following set up:

In Gemfile

# Plugins
group :jekyll_plugins do
  gem 'jekyll-feed', '~> 0.6'
  gem 'jekyll-sitemap', '~> 1.2'
  gem 'jekyll-archives', '2.1.1'
  gem 'jekyll-seo-tag'
end

In _config.yml

# Archives
jekyll-archives:
  enabled: ['topics']
  layout: 'topics'
  permalinks:
    category: '/answers/topics/:name/'

And in a typical post:

---
title: How do you get the current year in Jekyll?
layout: default
date: 2018-02-17
topics: 
    - jekyll
---
This is really a Liquid template markup thing.

[How do you get the current year in Jekyll?](http://adam.garrett-harris.com/get-current-year-in-jekyll/){:target="_blank"}

When I serve the site, I don't see jekyll-archives working to produce a category or topic page for "jekyll" as site.com/answers/topics/jekyll/. Why's that? Is it just about the keyword categories or is there something else missing?

[mmistakes]

@kblife Jekyll Archives does not support topics

https://github.com/jekyll/jekyll-archives/blob/master/docs/configuration.md#enabled-archives

You can change the permalink structure to what you have, but your post front matter needs to use categories, not topics like you have.

You will also need to change these lines in your _config.yml so the category links in your posts resolve to the correct paths.

category_archive:
  type: jekyll-archives
  path: /answers/topics/

[ghost]

Thanks, @mmistakes so I've updated the keyword topics to categories in all post...then in my _config.yml here I'm somewhat confused, what's the right way to spell it out...I did the below which wouldn't work:

# Archives
jekyll-archives:
  enabled: 
    - categories
  layout: 'topics'
  permalinks:
    category: '/answers/topics/:name/'
  category_archive:
    type: jekyll-archives
    path: /answers/topics/

My intention is to have each category/topic display as "site.com/answers/topics/TOPICNAME" you get the idea? Because I wanna create a page of "Topics" where I'll loop through all the categories and display them topics, just so the permalink is parent-child.

Thanks.

[mmistakes]

@kblife Your jekyll-archives config is way off that's why it's not working. Topics isn't an array it knows anything about, nor Jekyll for that matter. It only works for tags and categories.

Your best bet is to use categories as topics (which I think you're trying to do), but to do that you need to configure it that way properly. Then use the permalink paths as you have so instead of "category" in the URL it'll have "answers/topics"

You're are setting a Jekyll Archives layout that the theme doesn't have, unless you've built that yourself. You'll want to repurpose the archive-taxonomy like so.

jekyll-archives:
  enabled:
    - categories
  layouts:
    category: archive-taxonomy
  permalinks:
    category: /answers/topics/:name/

If this doesn't work I'd suggest reading up on how the Jekyll Archives plugin works and reaching out for help with them. It appears to me you're having issues with that more than the theme. Which I don't support.

[asarkar]

@ihexon @ohadschn may I ask you guys to take a look at #1984 if you are able to?