Skip to content

Draft: Set a description if not set in the front matter

Achilleas Pipinellis requested to merge axil-excerpt into main

A description meta tag shows up in link previews in applications like Slack. Up until now, we used the generic Documentation for GitLab Community Edition, GitLab Enterprise Edition, Omnibus GitLab, and GitLab Runner. text, unless description is defined in the YAML front matter.

Ideally, we would add a description item in all pages YAML front matter, but we can use a clever solution to extract the first 15 words (arbitrary number, we can change) of the introductory paragraph after the H1.

How to solve

I tried different variations, and this seems the most straightforward.

When description is missing from the YAML front matter, automatically add it by taking the first 15 words after the H1.

We basically perform the following:

  1. Remove the H1 title.
  2. Choose the first 15 words.
  3. Replace any Markdown links with the content inside brackets ([]).
  4. Add three dots at the end.

Edge cases

  • If a page has version history notes under H1, those are picked.
  • Some descriptions might include parts of the H2. This is because there's less than 15 words after the H1 and words from H2 are picked.
  • A page might not have any text under H1, which makes the H2 to be picked.
  • If a note/warning is after the H1, this is picked.

Examples of the above:

Test

  • Pick a page from the review app, view its source HTML, and see how the description tag is populated.
  • Drop a page from the review app in Slack and see how it unfurls.

Related issues

Edited by Amy Qualls

Merge request reports