Feature: Tags Listing Show "summary"

[misilot]

Context

We are working on building a service catalog for our documentation, and it would be great if we could have a "summary" metadata on the page that gets fed into the tag listing.

Description

Add a "summary" similar to "include" the include where we can specify the page metadata tag to use.

where it would be

• A - summary text
• B - summary text
• C - summary text
  or even the option of creating it as a definition list instead of a list?

Related links

• https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing-configuration

Use Cases

Author, creates a summary of the page, and it shows up in the tag listing.

Visuals

No response

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! I'm sorry, but I don't fully understand what you're aiming for. Could you maybe create some mockups or add some screenshots that shows the final thing + where the data is coming from?

or even the option of creating it as a definition list instead of a list?

I'm not sure I understand this either. What is created as a definition list? Is this a second feature request? Please provide more and detailed input, so we and others can decide whether this would be a useful feature request for our users ☺️

[misilot]

Sorry, I am hoping this helps explain it better

Screenshots (Where the tags would be hyperlinks, like the normal tag list)

Example page (it's in markdown)

---
hide:
    - toc
---
# Service Catalog

## Based on Tags
<!-- material/tags { include: [service], scope: true} -->


## Front Matter example

---
title: DSpace
tags:
   - service
summary: DSpace is an Institional Repository that we manage for the submission and long term storage of ETDR as well as pre- and post- print papers.
---


## Mock Up (1)

Simple tag list with the expanded summary

Pull from "summary"

* DSpace - DSpace is an Institional Repository that we manage for the submission and long term storage of ETDR as well as pre- and post- print papers.
* Matomo - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis...
* PrivateBin - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. ...
* Redmine - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad mi...


## Mock Up (2)

Definition list instead of the already existing bullets of "tags"

`DSpace`

:   DSpace is an Institional Repository that we manage for the submission and long term storage of ETDR as well as pre- and post- print papers.

`Matomo`

:  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis...

`PrivateBin`

:  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. ...

`Redmine`

:  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad mi...

It was the same idea, just two different ways of presenting it.

[kamilkrzyskow]

There is an undocumented layout option, which allows to select a custom layout of a listing:

• https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing-configuration
  

  mkdocs-material/src/plugins/tags/structure/listing/config.py

  Lines 47 to 53 in 3b6ae8e

  	layout = Optional(Type(str))
  	"""
  	The layout to use for rendering the listing.
  	This setting allows to override the global setting for the layout. If this
  	setting is not specified, the global `listings_layout` setting is used.
  	"""

  
  

  mkdocs-material/src/plugins/tags/config.py

  Line 63 in 3b6ae8e

  listings_layout = Type(str, default = "default")

The mapping items are Page/Link objects, so it should be possible to access their page.meta.summary, but from your description it should likely be the description property as it's the default metadata key also used for SEO meta tags, I see no reason to separate it out into summary 🤔

mkdocs-material/src/templates/fragments/tags/default/listing.html

Line 29 in 3b6ae8e

{{ mapping.item.title }}

So using customization it should be possible to add a custom listing layout which also renders additional text apart of the title:

• https://squidfunk.github.io/mkdocs-material/customization/#overriding-partials
• https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/fragments/tags/default/listing.html

[misilot]

@kamilkrzyskow thank you! This worked great, I didn't know about this hidden feature! I did have to copy the tags.html to the same directory as listings.html

I've got a docs_overrides/fragments/tags/service-catalog/{listing,tag}.html path to add the service-catalog template.

I'm going to close this as I think this does what I need.

[squidfunk]

Thanks for investigating a way to solve this, @kamilkrzyskow! It's not documented, because it's still considered experimental/unstable. I don't expect it to break, but I just want to set expectations.

[squidfunk]

I'm reopening this feature request, because I think the idea might be useful to support without customization, or at least offer an official way to solve it. We'll investigate once we're done with the current foundational work efforts.