Add meta description tag

[allanbowe]

For improved documentation SEO it would be great to have the meta tag "Description" in the templates/html/header.html file, eg:

<meta name="Description" content="$projectbrief">

The problem is that $projectbrief would then be static on every page. Ideally it would pick up the @brief from the individual file IF it exists. Not every file will have a brief, as explained here: https://github.com/doxygen/doxygen/issues/8214#issuecomment-1187663069

Expected behavior Each page of doxygen will have the description metatag containing the file @brief (if it exists), else the $projectbrief.

Screenshots

To Reproduce New feature, nothing to reproduce

Version all versions

Stack trace n/a

Additional context See #8214 and #8215

[albert-github]

In the "HTML standard" I found (https://html.spec.whatwg.org/) I see:

description

The value must be a free-form string that describes the page. The value must be appropriate for use in a directory of pages, e.g. in a search engine. There must not be more than one meta element where the name attribute value is an ASCII case-insensitive match for description per document.

The question is: is is an empty string allowed? as doxygen pages don't have to have a brief description nor the project has to have a PROJECT_BRIEF. according to #8215:

I believe that without PROJECT_BRIEF the attribute will be empty, which is harmless (no worse than without it) it would be OK but this is not normative.

A solution I can imagine is to have instead of

<meta name="description" content="$brief_placeholder">

just to have

$brief_placeholder

and to replace this with the brief / project_brief including the <meta ... part.

Another problem is the fact that in a brief description it is possible to have makeup command which would result in a brief description e.g. like:

The <b>bold</b> brief.

in the meta this could be:

<meta name="description" content="The &lt;b%gt;bold&lt;/b&gt; brief.">

though the question is: is this allowed? and are there HTML tags that are not allowed here?

[allanbowe]

Thanks for looking into this! From my perspective / understanding:

1. I don't see anything to suggest that empty descriptions are invalid
2. Your proposed solution sounds ok to me, although I am by no means a doxy developer. I think you're saying that $brief_placeholder would be present in the header.html, and that it would be dynamically replaced when generating all the individual pages by either the page \brief or the \project_brief (or nothing) depending on which attributes are available?
3. Regarding the html markup in the content string, I agree this is a bit ugly, but a small price to pay for the significant benefit of having previews. Perhaps a workaround would be some additional page-level tags, eg:
   • \meta_description (replacement path becomes \meta_description -> \brief -> \project_brief -> nothing)
   • \meta_image (path or URL link to the preview image)

[albert-github]

(I just numbered your points in https://github.com/doxygen/doxygen/issues/9460#issuecomment-1193108566 for easier reference). ad 1. Indeed there is nothing that suggests against en empty string ad 2. Indeed (and include the <meta name="description" ... ad 3. Interesting thought, with the \meta_description. The \meta_image I don't get, where would this show, especially in search engines?

[allanbowe]

about the meta_image - the (big) benefit here is that it will show up as a preview image when being shared on social media sites.

For example, if you navigate here: https://www.linkedin.com/post-inspector/

And post a doxy link such as this one: https://core.sasjs.io/mp__getdbml_8sas.html

You can see how the page will preview, for LinkedIn at least (there are similar tools for facebook / reddit / other social media sites)

Being able to provide a unique image will enable more informative previews when sharing links to particular documentation pages.

[albert-github]

Do I understand it correctly that this is in the page https://core.sasjs.io/mp__getdbml_8sas.html the

<meta property="og:image" content="https://core.sasjs.io/Macro_core_website_1.png" />

is there a normative description of these property names? Would the image be unique for the project (so the PROJECT_LOGO can be used) or should it unique per separate page?

I see also

<meta name="og:description" content="Macros for SAS Application Developers" />

what is the difference between name="description" and name="og:description"?

[allanbowe]

The og:xxx tags are defined here and are used by many sites to extract metadata beyond the basic meta tags. Twitter take it further with their own tags, with fallbacks to OpenGraph. This is a handy site for playing with the settings: https://metatags.io/

It's really key to generate tags at page level. The ability to provide project level metadata already exists, as you just observed, by simply modifying the header.html.

I wonder if the following approach would make sense?

1. Introduce a new tag, eg \metatag <name> {content}, such that the following :

  \metatag og:image /path/to/image.png

  \metatag robots index, no follow

  \metatag twitter:card summary_large_image

would generate (for that page):

<meta name="og:image" content="/path/to/image.png" />
<meta name="robots" content="index, no follow" />
<meta name="twitter:card" content="summary_large_image">

2. Use either \metatag description else \brief else \project_brief else (nothing) to generate:

<meta name="description" content="$brief_placeholder" />

3. Use either \metatag og:description else \brief else \project_brief else (nothing) to generate:

<meta name="og:description" content="$brief_placeholder" />

4. For images, use \metatag og:image else FIRST image else PROJECT_LOGO else (doxygen logo?) to generate:

<meta name="og:image" content="/path/to/image.png" />