diff --git a/docs/_docs/posts.md b/docs/_docs/posts.md index 34e21f5c..159a8926 100644 --- a/docs/_docs/posts.md +++ b/docs/_docs/posts.md @@ -120,34 +120,34 @@ you wish to access the currently-rendering page/posts's variables (the variables of the post/page that has the `for` loop in it), use the `page` variable instead. -## Categories and Tags +## Tags and Categories -Jekyll has first class support for categories and tags in blog posts. The difference -between categories and tags is a category can be part of the URL for a post -whereas a tag cannot. +Jekyll has first class support for *tags* and *categories* in blog posts. -To use these, first set your categories and tags in front matter: +### Tags -```yaml ---- -layout: post -title: A Trip -categories: [blog, travel] -tags: [hot, summer] ---- -``` +Tags for a post are defined in the post's front matter using either the key +`tag` for a single entry or `tags` for multiple entries.
Since Jekyll +expects multiple items mapped to the key `tags`, it will automatically *split* +a string entry if it contains whitespace. For example, while front matter +`tag: classic hollywood` will be processed into a singular entity +`"classic hollywood"`, front matter `tags: classic hollywood` will be processed +into an array of entries `["classic", "hollywood"]`. -Jekyll makes the categories available to us at `site.categories`. Iterating over -`site.categories` on a page gives us another array with two items, the first -item is the name of the category and the second item is an array of posts in that -category. +Irrespective of the front matter key chosen, Jekyll stores the metadata mapped +to the plural key which is exposed to Liquid templates. + +All tags registered in the current site are exposed to Liquid templates via +`site.tags`. Iterating over `site.tags` on a page will yield another array with +two items, where the first item is the name of the tag and the second item being +*an array of posts* with that tag. {% raw %} ```liquid -{% for category in site.categories %} -

{{ category[0] }}

+{% for tag in site.tags %} +

{{ tag[0] }}

@@ -155,7 +155,37 @@ category. ``` {% endraw %} -For tags it's exactly the same except the variable is `site.tags`. + +### Categories + +Categories of a post work similar to the tags above: + * They can be defined via the front matter using keys `category` or + `categories` (that follow the same logic as for tags) + * All categories registered in the site are exposed to Liquid templates via + `site.categories` which can be iterated over (similar to the loop for tags + above.) + +*The similarity between categories and tags however, ends there.* + +Unlike tags, categories for posts can also be defined by a post's file path. +Any directory above `_post` will be read-in as a category. For example, +if a post is at path `movies/horror/_posts/2019-05-21-bride-of-chucky.markdown`, +then `movies` and `horror` are automatically registered as categories for that +post. + +When the post also has front matter defining categories, they just get added to +the existing list if not present already. + +The hallmark difference between categories and tags is that categories of a post +may be incorporated into [the generated URL]('/docs/permalinks/#global') for the +post, while tags cannot be. + +Therefore, depending on whether front matter has `category: classic hollywood`, +or `categories: classic hollywood`, the example post above would have the URL as +either +`movies/horror/classic%20hollywood/2019/05/21/bride-of-chucky.html` or +`movies/horror/classic/hollywood/2019/05/21/bride-of-chucky.html` respectively. + ## Post excerpts