vsoch / docsy-jekyll

A Jekyll version of the beautiful Docsy!
https://vsoch.github.io/docsy-jekyll/
Apache License 2.0
196 stars 141 forks source link

[Feature request] Tag support #7

Closed noraj closed 4 years ago

noraj commented 4 years ago

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:

Example

This feature is already introduced in Documentation Next Jekyll theme.

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

vsoch commented 4 years ago

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

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

noraj commented 4 years ago

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

On most statig generator you have several options:

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:

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

I should review that quick.

vsoch commented 4 years ago

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

noraj commented 4 years ago

@vsoch idea of tag sidebar plugin

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

vsoch commented 4 years ago

It's a nice little cloud indeed!

image

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 commented 4 years ago

It's true your theme totally looks like docsy

vsoch commented 4 years ago

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.