[Feature request] Tag support

[noraj]

Feature idea

Adding tags (keywords) in frontmatter (meta-data) will generate a page referencing all pages containing this page.

Example:

In frontmatter you add (in YAML for example):

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com*
tags:
    - dev
    - python
---

So it will create a endpoint http://example.org/tag/#dev and http://example.org/tag/#python referencing, respectively, all pages containing the dev tag and the python tag.

Then on the page of the documentation where there is such a tags frontmatter, the page will contain some tag link #dev and #python respectively referencing the previously mentioned endpoints.

Related

The feature already exists in Jekyll, there is just to use it in the theme :)

A more heated discussion on why it is useful to have tags on documentation : https://github.com/mkdocs/mkdocs/issues/1828

Similar issue in Jekyll documentation themes:

• https://github.com/pmarsceill/just-the-docs/issues/255

Example

This feature is already introduced in Documentation Next Jekyll theme.

See https://idratherbewriting.com/documentation-theme-jekyll-next-version/sample1.html

[vsoch]

hey @noraj ! I'd be glad to think about this for you - a few notes!

• The feature doesn't just exist in jekyll, it requires some custom hack (or we can call it an implementation) to make a tag page, and then div ids that render the links to each one so that the /tag#tagname link works as expected. As an example, here is a tag page that I implemented to do that. Other strategies might include custom gems (not supported by GitHub pages) or having some data or collection (or similar) item render into a page for each tag (requiring manual specification). Anyway, you can't just add the tags and have the page magically appear. :)
• I purposefully didn't add this tags page (linking to tags on the site itself) because of the feature to link to related search content. In fact, you can look at the example pages and see that tags are already there, and they link to the AskCyberinfrastructure site. So given the need for both these functionalities, how would you propose the two features live alongside one another?

Happy Thanksgiving! And if you don't celebrate, I hope you had a good day anyway.

[noraj]

hi @vsoch There is no ThanksGiving in my country but happy ThanksGiving to you!

On most statig generator you have several options:

• access tags from front-matter global variable, so with Jekyll from page.tags variable and then iterate through it to list them all.
• some statuc generators such as Hexo have some method helpers, see list-tags in Hexo.

In both case you can retrieve the tags from the article in your template. Then each tag need to link to a tag page, in Hexo the hexo-generator-tag official default plugin. So for jekyll we can use the jekyll-tagging plugin to create the tag pages. Finally we can also create a tag list page to list all tags. Yes plugins are forbidden in the embedded GitHub Jekyll but it sucks in all case because every one use plugins anyway. The way to do on Github is the GitLab way:

• on GitLab: GitLab CI (build and deploy) + GitLab Pages (serve)
• on Github: GitHub Action (build and deploy) + GitHub Pages (serve)

GitHub pages only serve static assets (html, css, js) and is not dynamic in anyway, so using a CD/CI to build and deploy our Jekyll is the way to do to be free rather than the integrated limited Jekyll. Before GitHub sucked for that compared to GitLab because you were forced to use an external CI like Travis, CirleCI, etc... but now tehre is the integrated GitHub Action CI. For an example see: https://github.com/helaili/jekyll-action

[vsoch]

hey @noraj - no need to mansplain here, I already linked you to a page that shows I'm fully aware about implementing tags. I've easily done it for 20-30 jekyll sites.

As I mentioned, tag gems like the one you linked aren't supported on GitHub pages. Adding the requirement for a custom build (when there doesn't need to be one) is not something I'm going to do, but I'd be happy to add static generation of the tags page.

Which again leads me to the question that I'm still looking for feedback from you - as I mentioned the tags on the pages (that already exist) are already serving a purpose. How would you propose these two features exist alongside one another?

Please take careful note of my question above - I have implemented tags a thousand times and the implementation isn't the issue. I'm asking how you see this feature fitting within what is already here. Thanks!

[vsoch]

Anyway if you don't have any ideas, let me sleep on it and I'll put something together tomorrow. It's definitely a great idea, and something I'm happy to support :)

[vsoch]

@noraj here is a pull request for your review:

https://github.com/vsoch/docsy-jekyll/pull/8

Notes about how it works, and how to test, are included in the PR.

[noraj]

I should review that quick.

[vsoch]

Thanks again @noraj ! I hope that docsy jekyll is useful to you.

[noraj]

@vsoch idea of tag sidebar plugin

from https://github.com/artemsheludko/galada/blob/74756dcff2af3b6f2d5d0e595244c8c3029017c7/_includes/sidebar.html#L82-L93

[vsoch]

It's a nice little cloud indeed!

In that docsy jekyll aims to mirror Docsy, and Docsy does not have this cloud, I don't see adding this to the official template. But it looks fairly easy in terms of code, so you could easily add to your instance! If you do use it, please share a screen shot! :)

[noraj]

It's true your theme totally looks like docsy

[vsoch]

It's intended to be exactly the same :) Just with support for jekyll, so users can deploy on GitHub pages. Docsy uses Hugo, which is a static site generator implemented in GoLang.