Markdown "description" field unneeded?

[rschu1ze]

A typical header in markdown files looks like this:

---
slug: /en/development/build-osx
sidebar_position: 15
sidebar_label: Build on macOS for macOS
title: How to Build ClickHouse on macOS for macOS
description: How to build ClickHouse on macOS for macOS
---

"slug" is related to the path/location of the file, "sidebar_position" defines the relative order of pages in the sidebar, "sidebar_label" is ... the sidebar label, what "title" means is also clear.

Field "description" seems weird to me. It's definitely not rendered and it seems related to search engine optimization (SEO).

Some markdown files don't have a "description" at all, e.g. docs/en/operations/allocation-profiling.md

---
slug: /en/operations/allocation-profiling
sidebar_label: "Allocation profiling"
title: "Allocation profiling"
---

Other markdown files have a "description" field but it seems random and out-of-place, e.g. docs/en/operations/backup.md

---
slug: /en/operations/backup
description: In order to effectively mitigate possible human errors, you should carefully prepare a strategy for backing up and restoring your data.
---

or docs/en/operations/caches.md

---
slug: /en/operations/caches
sidebar_position: 65
sidebar_label: Caches
title: "Cache Types"
description: When performing queries, ClickHouse uses different caches.
---

My understanding is that search engines (Google) largely ignore embedded metadata (<meta> in HTML) these days. The inconsistent use of "description" doesn't help developers either.

Could you please check if "description" has any value, and if no, please remove it consistently from all doc pages?

[Blargian]

Hi @rschu1ze We're using the description tag in the KB articles specifically to render a short summary of the article:

{frontMatter.description} {/* truncate */}

Agree that it has no value for search but it has some other uses as well. We can use it to generate a landing page for all files within a folder for example:

In other places I added other non-standard tags:

https://github.com/ClickHouse/ClickHouse/blob/b5d84cb24b9b2e67dcfae95d413f70dcd74d13fe/docs/en/interfaces/formats/TabSeparated/TabSeparated.md?plain=1#L1-L8

I plan to generate the table here using those. At some point we might also want to add the ability to filter formats by input or output and those will come in handy.

Agree we should be consistent though. I could write a Github action to enforce that we have descriptions on all pages? (similar to how it's currently checking for tags on KB articles.)

[rschu1ze]

Okay, okay ... didn't know about landing pages. I don't bother too much except for consistency here 😄 A GitHub action sounds good but only if it doesn't require to maintain a list pages or folders which should have "descriptions" vs. others which should not.

[gingerwizard]

We should have descriptions everywhere. Ideally they would be our search result snippets @rschu1ze @Blargian