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.