Global metadata options don't seem to work?

[talonx]

I'm using Docusaurus to host a blog.

I'm trying to add global metadata to my site - the relevant part of my theme config looks like this

  themeConfig: {
    metadata: [
        {
            name: 'description',
            content: '......'
        },
    ],

However, the generated tags have something else. Note that I am seeing this problem with only the main page, not the individual posts. The individual posts pick up the description correctly from the post markdown.

<meta data-rh="true" name="description" content="Blog">

What am I missing?

[slorber]

TLDR: themeConfig.metadata is a default / fallback. It will only be used when a page doesn't declare a custom description (usually custom React pages using <Layout>, not pages provided by our theme like the blog pages).

---

The global metadata you declare this way is metadata that applies to your whole site, and can be overridden by your theme on a case-by-case basis (usually per-page basis).

It is not particularly a good practice to use the exact same description metadata for your whole site. After all, all pages of your site are different and should have a different description. So each individual page of our classic theme will override the description you add themeConfig.metadata to provide a custom one.

If you want to customize the page-specific description metadata that our theme provides, you'd have to swizzle the respective page components and provide your own logic.

For the blog home page, according to our current code, you should use blogOptions.blogDescription

function BlogListPageMetadata(props: Props): JSX.Element {
  const {metadata} = props;
  const {
    siteConfig: {title: siteTitle},
  } = useDocusaurusContext();
  const {blogDescription, blogTitle, permalink} = metadata;
  const isBlogOnlyMode = permalink === '/';
  const title = isBlogOnlyMode ? siteTitle : blogTitle;
  return (
    <>
      <PageMetadata title={title} description={blogDescription} />
      <SearchMetadata tag="blog_posts_list" />
    </>
  );
}

If you don't like this logic, you can swizzle the BlogListPage component and provide your own logic to override ours.

[talonx]

I have descriptions on the individual pages using markdown and they are picked up correctly.

I wanted to set the description for the index page (the home page of the blog). I was able to get this working using the blogDescription attribute under presets. However, the themeConfig.metadata approach still does not work (maybe I'm doing something wrong).

[slorber]

However, the themeConfig.metadata approach still does not work (maybe I'm doing something wrong).

This works to define a default. The default description you set this way gets overridden by blog pages on a case-by-case basis, that's why using themeConfig.metadata can't work for setting the description of most pages.

If you used themeConfig.metadata with any other meta (like "my-custom-description") you would see it added to the page successfully, because it wouldn't be overridden.

[talonx]

However, the themeConfig.metadata approach still does not work (maybe I'm doing something wrong).

This works to define a default. The default description you set this way gets overridden by blog pages on a case-by-case basis, that's why using themeConfig.metadata can't work for setting the description of most pages.

If you used themeConfig.metadata with any other meta (like "my-custom-description") you would see it added to the page successfully, because it wouldn't be overridden.

I understand that it gets overridden for the blog pages. But it should still work for the landing (main) page because that page does not correspond to a single post - rather, it has the list of posts - which was my original query.

[slorber]

The home of the blog is indeed a list of posts but still has a pre-defined description: the blogOptions.blogDescription. It also has a title.

In general, we try to give meaningful title/descriptions to all our pre-made theme-created pages, whenever possible.

Now, I agree that our default option value is not great: blogDescription: 'Blog'. We might as well have blogDescription: undefined instead so that themeConfig.metadata description can be used a site-wide fallback.

[talonx]

The home of the blog is indeed a list of posts but still has a pre-defined description: the blogOptions.blogDescription. It also has a title.

In general, we try to give meaningful title/descriptions to all our pre-made theme-created pages, whenever possible.

Now, I agree that our default option value is not great: blogDescription: 'Blog'. We might as well have blogDescription: undefined instead so that themeConfig.metadata description can be used a site-wide fallback.

I see, that makes sense.

[Ark-kun]

@slorber
The example from the Docusaurus' official docs does not work for us:
https://docusaurus.io/docs/seo#global-metadata

export default {
  themeConfig: {
    // Declare some <meta> tags
    metadata: [
      {name: "twitter:title", content: "Tangle"},
    ],
  },

No twitter:card etc is added to the main page.

Why doesn't this default work? Do we really have to put this metadata to every single page 1 by 1?

[Ark-kun]

The slug variant does not work too:

---
id: overview
title: Overview
slug: /
twitter:title: Tangle
metadata: [
  {name: "twitter:title", content: "Tangle"},
]
---

[Ark-kun]

Tried headTags - nothing

  headTags: [
    {
      tagName: 'meta',
      attributes: {name: "twitter:title", content: "Tangle"},
    },

[Ark-kun]

Or maybe this just does not work with local serving?

[slorber]

The metadata are usually useful for SEO and crawlers, and not really useful in dev.

In dev, we use Webpack dev server with a minimalist html page template, and render everything client-side. If you use <head> in md, or <Head> in JSX, this will work in dev after React renders, but it won't be "server-side rendered" because we don't do any SSG/SSR in dev.

In production builds (doing real static site generation), the APIs above will work and ensure that the correct metadata is present in the static pages, and available to crawlers even without running JS/React.

More info here: https://docusaurus.io/docs/seo

Note that the front matter you added is something you invented, not something we support nor document anywhere.