plugin-category-cloud (A README Experience)

Oct 29, 2021

Category Cloud Screenshot

A plugin for Micro.blog that creates a page displaying links to your categories layed out as a category cloud. It is based upon the category cloud plugin you might already know and love that lives here.

Once installed, the generated page will be found at [SCHEME]://[HOSTNAME]/cloud/.

Let’s have a look at the parameters:

Plugin Parameters

The maximum and minum font sizes for the links are in rem units. The maximum and minimum font weights are expected to be integer values.

All of these values are optional. The defaults used when absent are those values used as placeholders in the plugin parameter fields.

The Cloud Exclusion List parameter is also optional. It’s default value is not the placeholder, but an empty string. If, however, you choose to place a , separated list of your categories such as my-awesome-category, Imma Be Anchorized; then, the plugin will skip over these categories when generating the cloud so that they do not appear in the output.

The page template lives at layouts/cloud/single.html. {{ define "main" }}

&#123;&#123; with site.Taxonomies.categories }}

{{/* Max and min page counts */}}
&#123;&#123; $max_count := mul (len (index .ByCount 0).Pages) 1.0 }}
&#123;&#123; $min_count := mul (len (index .ByCount.Reverse 0).Pages) 1.0 }}

{{/* Max and min font sizes in rem units */}}
&#123;&#123; $max_size := 1.34 }}
&#123;&#123; with site.Params.cloud_max_rem }}&#123;&#123; $max_size = . | float }}&#123;&#123; end }}
&#123;&#123; $min_size := 0.9 }}
&#123;&#123; with site.Params.cloud_min_rem }}&#123;&#123; $min_size = . | float }}&#123;&#123; end }}

{{/* Max and min font weights */}}
&#123;&#123; $max_weight := 800 }}
&#123;&#123; with site.Params.cloud_max_weight }}&#123;&#123; $max_weight = . | int }}&#123;&#123; end }}
&#123;&#123; $min_weight := 200 }}
&#123;&#123; with site.Params.cloud_min_weight }}&#123;&#123; $min_weight = . | int }}&#123;&#123; end }}

&#123;&#123; $exclusion_list := slice "" }}
&#123;&#123; with site.Params.cloud_exclusion_list }}
  &#123;&#123; $exclusion_list = apply (split . ",") "anchorize" "." }}
&#123;&#123; end }}

<div id="category-cloud">

&#123;&#123; range $name, $taxonomy := . }}

&#123;&#123; if not (in $exclusion_list $name )}}
  &#123;&#123; $page_count := len $taxonomy.Pages }}
  &#123;&#123; $percent_max_count := div $page_count ($max_count) }}
  &#123;&#123; $font_size := mul $max_size $percent_max_count }}
  &#123;&#123; if (lt $font_size $min_size) }}&#123;&#123; $font_size = $min_size }}&#123;&#123; end }}
  &#123;&#123; $font_weight := mul $max_weight $percent_max_count }}
  &#123;&#123; if (lt $font_weight $min_weight) }}&#123;&#123; $font_weight = $min_weight }}&#123;&#123; end }}
  &#123;&#123; $fract_weight := mod $font_weight 100 }}
  &#123;&#123; $font_weight = cond (eq $fract_weight 0) $font_weight (add (sub $font_weight $fract_weight) (cond (ge $fract_weight 50) 100 0)) }}

<a 
  href="&#123;&#123; "/categories/" | relLangURL }}&#123;&#123; $name | urlize }}"
  class="category-cloud-link"
  style="font-size:&#123;&#123; $font_size }}rem; font-weight:&#123;&#123; $font_weight }}"
  >&#123;&#123; $name }}(&#123;&#123; $page_count }})</a>
  
  &#123;&#123; end }}
&#123;&#123; end }}

</div>

&#123;&#123; end }}

&#123;&#123; end }}

The stylesheet used to layout the cloud leaves at static/assets/css/category-cloud.css.

#category-cloud { 
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  align-content: center;
  align-items: baseline;
  gap: 0px 10px;
  width: 90%;
  max-width: 900px;
  padding: 0px 20px;
  margin: 40px auto; 
}

.category-cloud-link { 
  color: #666; 
  margin: 0px;
  padding: 0px;
}

.category-cloud-link:hover { color: #000; }

The file living at content/cloud.md specifies the front matter for the page.

{
  "title": "Cloud",
  "description": "A category cloud weighted by posts per category.",
  "type": "cloud",
  "menu": {
    "main": {
      "name": "Cloud",
      "title": "Cloud",
      "identifier": "cloud",
      "url": "/cloud/",
      "weight": 110
    }
  }
}

Leave the type alone (as that is what points it to layouts/cloud/single.html). You can play with the title and description values. These set the values I would expect your theme to draw from when constructing the page <head>. The menu creates a menu item to include the page in your navigation. Leave the url alone (this is how the link’s target is derived). You can play around with the other values. You can adjust the value of weight to slide the menu item up or down your list of navigation items. You can remove the menu entry entirely if you do not want the page to show up in your navigation menu.