---
id: head-metadata
description: Declaring page-specific head metadata through MDX
slug: /markdown-features/head-metadata
---

# Head metadata

## Customizing head metadata {#customizing-head-metadata}

Docusaurus automatically sets useful page metadata in `<html>`, `<head>` and `<body>` for you. It is possible to add extra metadata (or override existing ones) with the `<head>` tag in Markdown files:

```md title="markdown-features-head-metadata.mdx"
---
id: head-metadata
title: Head Metadata
---

<!-- highlight-start -->
<head>
  <html className="some-extra-html-class" />
  <body className="other-extra-body-class" />
  <title>Head Metadata customized title!</title>
  <meta charSet="utf-8" />
  <meta name="twitter:card" content="summary" />
  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
</head>
<!-- highlight-end -->

# Head Metadata

My text
```

```mdx-code-block
<head>
  <html className="some-extra-html-class" />
  <body className="other-extra-body-class" />
  <title>Head Metadata customized title!</title>
  <meta charSet="utf-8" />
  <meta name="twitter:card" content="summary" />
  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
</head>
```

This `<head>` declaration has been added to the current Markdown doc as a demo. Open your browser DevTools and check how this page's metadata has been affected.

:::note

This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.mdx#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.

:::

:::tip You don't need this for regular SEO

Content plugins (e.g. docs and blog) provide front matter options like `description`, `keywords`, and `image`, which will be automatically applied to both `description` and `og:description`, while you would have to manually declare two metadata tags when using the `<head>` tag.

:::

## Markdown page description {#markdown-page-description}

The Markdown pages' description metadata may be used in more places than the head metadata. For example, the docs plugin's [generated category index](../docs/sidebar/items.mdx#generated-index-page) uses the description metadata for the doc cards.

By default, the description is the first content-ful line, with some efforts to convert it to plain text. For example, the following file...

```md
# Title

Main content... May contain some [links](./file.mdx) or **emphasis**.
```

...will have the default description "Main content... May contain some links or emphasis". However, **it's not designed to be fully functional**. Where it fails to produce reasonable descriptions, you can explicitly provide one through front matter:

```md
---
description: This description will override the default.
---

# Title

Main content... May contain some [links](./file.mdx) or **emphasis**.
```
