taxonomy support #272 #324 #539

[narrenfrei]

As mentioned in #272 and #324 I continued the development of support for taxonomies / tagging.
Because I've decided to code the taxonomy functionality from scratch, I've closed #539 and made a new PR.

You can catch a current preview at https://deploy-preview-554--docsydocs.netlify.app/docs/dev-test-content/
At the moment it's completely WIP and the special pages for taxonomies are very raw.
Some commits for this PR will follow the next days.

[narrenfrei]

A (very) first version of the taxonomy support is ready to get feedback ;-)

I think all needed basic functionality should work. But I'm still working on the layout.

[narrenfrei]

Also blog posts now support taxonomies: https://deploy-preview-554--docsydocs.netlify.app/blog/
The taxonomy page with all articles of a specific term shows with an icon, if the tagged article comes from the docs or blog section: https://deploy-preview-554--docsydocs.netlify.app/tags/tag-1/

I have to tidy up the code a little bit and write a manual, then the PR should be ready for merging.

Are there any comments or further wishes?

[LisaFC]

FINALLY! Thanks everyone for your patience and thanks so much to @RichieEscarez for figuring out what we needed to do.

[narrenfrei]

Thanks everyone for the help to get this PR merged.

[narrenfrei]

As the PR is ready from my side, I've removed the WIP in the label.

When merging you should exclude:

• config.toml

• userguide/content/blog

• userguide/content/en/docs/dev-test-content

• userguide/content/no

@LisaFC You habe merged also my test content into the master. Sorry that I have left it in the PR. I think it's easier for you, if I delete it myself before push it into the PR, isn't it?

[narrenfrei]

@LisaFC @emckean Same problem as in #518

After rebase on the current Docsy master the google-cla bot can't verify author consent.

From my side this PR would be ready, except deleting my dev content. And a comment to my questions above would be nice ;-)

Question block 1:

I've defined 2 quite common layouts for tags and also 1 showcase what's also possible with the taxonomies:

The taxonomy "fruits" is only a showcase, what you can do with taxonomies.

The taxonomy "text tags" shows a simple text tags layout.

All other taxonomies have tag typical layout.

==> What should be the standard layout for the taxonomies - example 2 or 3?

==> Should I make a switch in the settings to toggle between 2 and 3?

Here you can see the different layouts: https://deploy-preview-554--docsydocs.netlify.app/docs/dev-test-content/

Question block 2:

I had also to restructure the right sidebar a bit: Before my PR the the repository links where in the div.td-toc and the div.td-toc was the right sidebar itself. As we now get more content in the right sidebar, I restructured it a little bit:

• aside.td-sidebar-toc

• div.td-page-meta

• div.td-toc

• div.taxonomy-terms-cloud for each taxonomy shown in the sidebar

As I introduced a aside element for the right sidebar, I also changed the div from the left sidebar to a aside element. If adapted the CSS to get the old layout. But this may cause some problems, when a project have a customized stylesheet. But I think the markup is now a little bit more stringent.

@LisaFC Is this OK for you?

Question block 3:

Is there a possibility to show the taxonomy functionality within the userguide? This is also a general question for other new features. It think, it would be great when there would be a "showroom" within the userguide, wouldn't it?

For the taxonomy support this would mean, that we would have to enable taxonomies in the userguide. I don't know if you'd like this ;-)

@LisaFC Should I change anything in my original PR?

[LisaFC]

Ah, sorry I didn't notice the test data - I'll remove that now (unless you want to create a PR yourself to remove it?)

[LisaFC]

OK, test data now gone!

There are still some tags displayed and some taxonomy settings in config.toml

What is the "Cloud of categories" for?

It's nice to have some tag info in the userguide so users can see how it works, but I just want to make sure it's fairly tidy/obvious.

[narrenfrei]

@LisaFC I'm now going to bed with my kids. But I'll take a look a little bit later.

[narrenfrei]

@LisaFC
I've tried to explain the settings of the taxonomy support here: https://www.docsy.dev/docs/adding-content/taxonomy/#parameters

Per default, in the right sidebar "clouds" (= lists of all terms of a taxonomy) get generated for all defined taxonomies (Hugo default: tags and categories). The title of these tags would be per default also tags and categories, but because in the current config.toml of the master branch of the Docsy userguide there are still fragments of my old test content:

[languages.no.taxonomies]
tag = "tags"
category = "categories"
project = "projects"
"norsk tag" = "norsk tags"
[languages.no.params.taxonomy]
taxonomyCloud = ["tags", "categories"] # set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloudTitle = ["Norsk Tag Cloud", "Norsk Cloud of Catagories"] # if used, must have same lang as taxonomyCloud
taxonomyPageHeader = ["projects", "tags", "norsk tags"] # set taxonomyPageHeader = [] to hide taxonomies on the page headers

[params.taxonomy]
taxonomyCloud = ["fruits", "text tags", "tags", "categories"] # set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloudTitle = ["Fruits are healthy", "Simple Tags Layout", "Tag Cloud", "Cloud of Catagories"] # if used, must have same lang as taxonomyCloud
taxonomyPageHeader = ["fruits", "text tags", "projects", "tags", "categories"] # set taxonomyPageHeader = [] to hide taxonomies on the page headers

[taxonomies]
tag = "tags"
category = "categories"
project = "projects"
"text tag" = "text tags"
fruit = "fruits"

Shall I prepare a PR with a simple taxonomy example for the Docsy userguide?
Any wishes for such a PR?

And once more: I'm really sorry, that I've made this problems by leaving my dev content in the PR. I think, it would be better, when I delete my dev content from the PR instead of leaving you a message, which files shouldn't be merged into master, in future.

[huehnerlady]

I've tried to explain the settings of the taxonomy support here: https://www.docsy.dev/docs/adding-content/taxonomy/#parameters

@narrenfrei I have used this explanation to enable taxomonies in my blog and it worked, I found these instructions very good 🙂

[deining]

@narrenfrei: Great work, very useful, thanks a lot. Wile reading your instructions, I found a few typos which I corrected in #594. I could follow the instructions easily, this may partially owed to the fact that I German is my mother tongue 🙂. I think there is room for improvement here and there. Maybe @LisaFC can step in here? Again, thanks your your hard work, I really appreciate that!

[huehnerlady]

this may partially owed to the fact that I German is my mother tongue 🙂

@deining good point, my mother tongue is also German 😉

[narrenfrei]

Thanks for you comments.

After the message from @huehnerlady I also thougt about whether I should also point out our common mother tongue ;-)

[LisaFC]

Shall I prepare a PR with a simple taxonomy example for the Docsy userguide?
Any wishes for such a PR?

That would be excellent thanks! What do you think would be a good demonstration of the feature?

I'll take a look at the new docs - they look excellent on a quick read, possibly just a few tweaks (and I may have some questions).

[narrenfrei]

As tags and categories are the default taxonomies from Hugo, I would keep this taxonomies at least for https://www.docsy.dev/docs/adding-content/taxonomy/

But what shall do with the tag and category cloud in the right sidebar? By default they are visible on all docs and blog pages. At the moment I only can switch them on/off globally.

[huehnerlady]

What are the use-cases for those? For me personally I just need them in blogs, so for me the natural thing is to enable it in blog and disable it anywhere else.
but maybe that is an edge-case as theoretically every page in hugo can have tags/categories?

[narrenfrei]

As Docsy is specialist on documentation sites, most use cases will be in docs, I think.

Taxonomies can be used for a lot of (cool) things in docs - eg:

• assign development state
• topic specific responsible person
• collections for projects
• assign icons to content ;-) https://deploy-preview-554--docsydocs.netlify.app/fruits/

Every time when you want to give your content a additional dimension of structure you can use taxonomies and get so automatically pages for each taxonomy and taxonomy term. You can also serve additional content to this taxonomy term pages.

[huehnerlady]

I think for me that means adapting the docs page for now, which is fine by me, thank you for the explanation :)

[Symbolics]

If you don't mind, please let us know how you do this. I have the same requirement; tag clouds in blog, but not in docs.

[narrenfrei]

If you don't mind, please let us know how you do this. I have the same requirement; tag clouds in blog, but not in docs.

At the moment you would have to make for you project modified templates for the docs section and comment the taxonomy clouds on the right column out. The listing of assigned taxonomy terms per page shouldn't disturb, because they only get shown when the current page have assigned taxonomy terms.

For the next version of taxonomy support I plan a parameter in the config.toml to list the site sections, where to show the taxonomy infos or a page specific parameter to hide specific taxonomies. These parameter could get defined cascading, so all child pages also would use the same setting.