Add category pages

[timwis]

Given #139 may require we switch the deployment workflow to GitHub Actions first, I thought it might make sense to split the features out, and implement the "category pages" feature separately from the "progressive enhancement" feature. It may not, though—I haven't had enough coffee yet. But at least this hopefully illustrates what I meant about not needing the generate script anymore, @BryanQuigley.

I've cherry-picked Luke's commit on top of the latest v2 branch. I think the only other thing this feature needs is to fix the netlify-cms.yml config to use the categories collection instead of the data file.

[timwis]

Thanks. The only other thing I wanted to flag was that Jekyll has a built-in concept of categories, but they're for posts, and they work differently to how we want to use them. So we're overriding the site.categories namespace here, which I worry slightly about. I've posted this to the Jekyll forum to see if anyone can foresee any issues with it.

Also, I went down a bit of a rabbit hole writing a Jekyll plugin to migrate categories.yml into separate YAML files. This command is run via jekyll convert_categories:

class ConvertCategories < Jekyll::Command
  def self.init_with_program(prog)
    prog.command(:convert_categories) do |c|
      c.action do |args, options|
        add_build_options(c)
        jekyll_options = configuration_from_options(options)
        site = Jekyll::Site.new(jekyll_options)

        file_path = "#{site.config["data_dir"]}/categories.yml"
        data_reader = Jekyll::DataReader.new(site)
        categories = data_reader.read_data_file(file_path)

        categories["items"].each do |category|
          slug = Jekyll::Utils.slugify(category["name"])
          file_path = "_categories/#{slug}.md"
          File.write(file_path, "#{category.to_yaml}---")
        end
      end
    end
  end
end

Obviously it's not too hard to do that manually, but it got me thinking that we could turn it into a jekyll upgrade_jkan command if there ends up being anything particularly involved about upgrading to v2.

[BryanQuigley]

Quick thought on the categories namespace issue - just use a different name? OpenDataPhilly actually calls them topics CKAN looks like it switched to just be generic groups (https://demo.ckan.org/group/)

I don't have any personal preference on what it gets called..

[timwis]

Interesting...I swore the JKAN schema was based on the CKAN schema. Maybe CKAN used to use category? Would love to find the discussion on why they changed it, if so. It looks like the data.json schema uses theme these days as well.

Well, that's a pretty significant change—you'd have to update the key in all the datasets, which would definitely require a migration script. If we're going to make that level of change, it would be good to base it on an open standard.

[timwis]

Wait a minute, I'm making this far more complicated than it needs to be. The only conflict with Jekyll is the site.categories namespace. So we can just call the collection dataset_categories. We may even still be able to use the _categories directory. And we can certainly maintain the /categories URL namespace without causing a conflict.

[timwis]

Okay, I've changed the collection name to dataset_categories. Gosh, I've got to say, I really dislike calling it that! But I can't think of any better alternatives. Going to merge into v2 so we can pick up the progressive enhancement feature.