search

google / docsy

A set of Hugo doc templates for launching open source content.
https://docsy.dev
Apache License 2.0
2.62k stars 904 forks source link

Listing content by Taxonomy doesn't work #272

Open q5sys opened 4 years ago

q5sys commented 4 years ago

Hoping you can point me in the right direction. I've got Docsy installed and its working great. I wanted to add tagging into it, so I've edited my config.toml to add

[taxonomies]
tags = "tags"

and I then removed disableKinds = ["taxonomy", "taxonomyTerm"]

Ive written my tags partial, and added the partial to content.html. When I add the taxonomy to the front matter of a markdown file, the tags render properly.

However when I click one, I expect to get the list of all taxonomies in the typical way that Hugo does that, however all I ever get is a blank page. I'm trying to track down what in Docsy would be causing this, and the only thing I can come up with is that list.html has been changed. Would that be it, or is there something else in Docsy which would break Hugo from being able to display the list of taxonomies? From my understanding that's a built in feature of Hugo, and I've never had any problems using it before. Thanks!

LisaFC commented 4 years ago

Hmm, that's strange. It might need its own list.html layout to display the results. I'll take a look.

What version of Hugo are you using, as I think there's some newish Taxonomy stuff in recent versions.

q5sys commented 4 years ago

I'm currently using 0.69 and I've tested on 0.66 and 0.68 with the same results. I have yet to try out the newer 0.70 from last week. I've got some time later this week to try a few other things, so I'll report back if I figure anything else out.

q5sys commented 4 years ago

Sorry for the delay in responding, life has been busy.
I've finally gotten the time to test this the other day with the newest 0.72 extended release. but I'm still getting a blank page. I'm guessing it has to be something with the list.html file as mentioned before. At the bottom I'll append the list.html i've used before, but its not working with Docsy, it may be a simple issue, but i'm not seeing it.

Here's everything I've done with the default Docsy example site in this testing:

I edited config.toml and removed disableKinds = ["taxonomy", "taxonomyTerm"] and added:

[taxonomies]
products = "products"

I added {{ partial "article_meta.html" . }} as line 2 of ./docsy/layouts/_default/content.html

created ./docsy/layouts/partials/article_meta.html

<header class="article-meta clearfix">
  {{ partial "article_tags.html" . }}
</header>

I created ./docsy/layouts/partials/article_tags.html

{{ if isset .Params "products" }}
{{ if not (eq (len .Params.products) 0) }}
<div class="article-products">
  <span></span>
  {{ range .Params.products }}
  <a class="article-products-link" href="{{ $.Site.BaseURL }}/products/{{ . | urlize }}">{{ . }}</a>
  {{ end }}
</div>
{{ end }}
{{ end }}

Then in an article I add something like products: ["k8s"] to the frontmatter. When I run hugo, the tag shows up at the top of the article and it is clickable, if I click it I'm taking to the proper taxonomies page, but it will be blank. My expectation, and what I've gotten with other Hugo themes is that I get a list of all articles with that Taxonomy tag. However for a documentation site, Docsy is the best theme I've come across so Docsy is what I want to use.

My functioning list.html on other hugo sites:

{{ partial "head.html" . }}
<body>
  <header>
    {{ partial "header.html" . }}
  </header>
  <div id="container">
    <div id="main">
      {{ range .Data.Pages.GroupByDate "2006-01" }}
      <h2 id="{{ .Key }}">{{ .Key }}</h2>
      {{ range .Pages }}
      {{ partial "article.html" . }}
      {{ end }}
      {{ end }}
    </div>
    {{ partial "sidebar.html" . }}
  </div>
  <footer>{{ partial "footer.html" . }}</footer>
  {{ partial "after_footer.html" .}}
</body>
</html>
nlundquist commented 4 years ago

This is due to Docsy not defining any appropriate template for a single taxonomy or a taxonomy listing, e.g of the templates listed at the following: https://gohugo.io/templates/lookup-order/#examples-layout-lookup-for-taxonomy-pages

the only one defined by docsy is layouts/_default/list.html which is simply:

{{ define "main" }}
{{ with .Content }}
{{ . }}
{{ end }}
{{ end }}

Since taxonomy pages do not have defined .Content, they render blank.

Adding implementations of layouts/_default/tag.html & layouts/_default/tag.terms.html will result in better output.

LisaFC commented 4 years ago

Ahhhh, thanks for that. I'll have a play around with adding those templates and see if I can get it working.

q5sys commented 4 years ago

Interesting, none of the Hugo sites I've used before have a tag.html or tag.terms.html defined. Actually none of them have had anything special in any way that I can figure out which allows the taxonomies to work, but maybe I'm missing something obvious. https://github.com/chipzoller/hugo-clarity https://github.com/colorchestra/smol https://github.com/huyb1991/hugo-lamp https://github.com/coderzh/hugo-pacman-theme

q5sys commented 4 years ago

Ok, so I managed to get this working, but right now its raw and ugly so it doesn't fit into the rest of the nice docsy themeing I'll work on cleaning it up and then file a PR. Or If I cant manage to get the themeing cleaned up, I'll just push it to a fork and let you pull what you need.

b-jsshapiro commented 4 years ago

I was planning to add this as well, so if you feel inclined to share your new template files I'd sure appreciate it.

@nlundquist: Does the list template get used for pages that generate subdirectory listings? I haven't been entirely happy with how that currently works in Docsy, but wasn't entirely sure which template to touch.

q5sys commented 4 years ago

@b-jsshapiro hopefully I can get time this weekend to finish up the PR, then you can see exactly how I have the template set up.

honzik20 commented 3 years ago

Ok, so I managed to get this working, but right now its raw and ugly so it doesn't fit into the rest of the nice docsy themeing I'll work on cleaning it up and then file a PR. Or If I cant manage to get the themeing cleaned up, I'll just push it to a fork and let you pull what you need.

@q5sys Can you tell me how you got it working? I'm still coming up with blank pages...

q5sys commented 3 years ago

@honzik20 all my work is here: https://github.com/q5sys/docsy As mentioned in the PR I'd like to set a config param that could be used with an if statement in toc.html, to avoid someone having to edit the files to enable the tag cloud but I havent worked that out yet.

huehnerlady commented 3 years ago

Hi, I find this really interesting and would also like to use it. Is there any update on this? :)

narrenfrei commented 3 years ago

Hi @huehnerlady, yes I've started a new PR #554 which is ready to merge (since about 5-6 hours). I'm only waiting for some feedback (https://github.com/google/docsy/pull/554#issuecomment-850177326) and some issues with the google-cla bot have to been solved ;-)