mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
220 lines
9.4 KiB
Text
220 lines
9.4 KiB
Text
---
|
|
description: How to make your Docusaurus site maximally search-engine-friendly.
|
|
sidebar_label: SEO
|
|
keywords:
|
|
- seo
|
|
- positioning
|
|
---
|
|
|
|
# Search engine optimization (SEO)
|
|
|
|
import BrowserWindow from '@site/src/components/BrowserWindow';
|
|
|
|
Docusaurus supports search engine optimization in a variety of ways.
|
|
|
|
## Global metadata {#global-metadata}
|
|
|
|
Provide global meta attributes for the entire site through the [site configuration](./configuration.mdx#site-metadata). The metadata will all be rendered in the HTML `<head>` using the key-value pairs as the prop name and value. The `metadata` attribute is a convenient shortcut to declare `<meta>` tags, but it is also possible to inject arbitrary tags in `<head>` with the `headTags` attribute.
|
|
|
|
```js title="docusaurus.config.js"
|
|
export default {
|
|
themeConfig: {
|
|
// Declare some <meta> tags
|
|
metadata: [
|
|
{name: 'keywords', content: 'cooking, blog'},
|
|
{name: 'twitter:card', content: 'summary_large_image'},
|
|
],
|
|
},
|
|
headTags: [
|
|
// Declare a <link> preconnect tag
|
|
{
|
|
tagName: 'link',
|
|
attributes: {
|
|
rel: 'preconnect',
|
|
href: 'https://example.com',
|
|
},
|
|
},
|
|
// Declare some json-ld structured data
|
|
{
|
|
tagName: 'script',
|
|
attributes: {
|
|
type: 'application/ld+json',
|
|
},
|
|
innerHTML: JSON.stringify({
|
|
'@context': 'https://schema.org/',
|
|
'@type': 'Organization',
|
|
name: 'Meta Open Source',
|
|
url: 'https://opensource.fb.com/',
|
|
logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
|
|
}),
|
|
},
|
|
],
|
|
};
|
|
```
|
|
|
|
Docusaurus adds some metadata out-of-the-box. For example, if you have configured [i18n](./i18n/i18n-introduction.mdx), you will get a [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) alternate link.
|
|
|
|
To read more about types of meta tags, visit [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta).
|
|
|
|
## Single page metadata {#single-page-metadata}
|
|
|
|
Similar to [global metadata](#global-metadata), Docusaurus also allows for the addition of meta-information to individual pages. Follow [this guide](./guides/markdown-features/markdown-features-head-metadata.mdx) for configuring the `<head>` tag. In short:
|
|
|
|
```md title="my-markdown-page.mdx"
|
|
# A cooking guide
|
|
|
|
<head>
|
|
<meta name="keywords" content="cooking, blog" />
|
|
<meta name="twitter:card" content="summary_large_image" />
|
|
<link rel="preconnect" href="https://example.com" />
|
|
<script type="application/ld+json">
|
|
{JSON.stringify({
|
|
'@context': 'https://schema.org/',
|
|
'@type': 'Organization',
|
|
name: 'Meta Open Source',
|
|
url: 'https://opensource.fb.com/',
|
|
logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
|
|
})}
|
|
</script>
|
|
</head>
|
|
|
|
Some content...
|
|
```
|
|
|
|
Docusaurus automatically adds `description`, `title`, canonical URL links, and other useful metadata to each Markdown page. They are configurable through [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter):
|
|
|
|
```md
|
|
---
|
|
title: Title for search engines; can be different from the actual heading
|
|
description: A short description of this page
|
|
image: a thumbnail image to be shown in social media cards
|
|
keywords: [keywords, describing, the main topics]
|
|
---
|
|
```
|
|
|
|
When creating your React page, adding these fields in `Layout` would also improve SEO.
|
|
|
|
:::tip
|
|
|
|
Prefer to use [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter) for fields like `description` and `keywords`: Docusaurus will automatically apply this to both `description` and `og:description`, while you would have to manually declare two metadata tags when using the `<head>` tag.
|
|
|
|
:::
|
|
|
|
:::info
|
|
|
|
The official plugins all support the following [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter): `title`, `description`, `keywords` and `image`. Refer to their respective API documentation for additional [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter) support:
|
|
|
|
- [Docs front matter](./api/plugins/plugin-content-docs.mdx#markdown-front-matter)
|
|
- [Blog front matter](./api/plugins/plugin-content-blog.mdx#markdown-front-matter)
|
|
- [Pages front matter](./api/plugins/plugin-content-pages.mdx#markdown-front-matter)
|
|
|
|
:::
|
|
|
|
For JSX pages, you can use the Docusaurus [`<Head>`](docusaurus-core.mdx#head) component.
|
|
|
|
```jsx title="my-react-page.jsx"
|
|
import React from 'react';
|
|
import Layout from '@theme/Layout';
|
|
import Head from '@docusaurus/Head';
|
|
|
|
export default function page() {
|
|
return (
|
|
<Layout title="Page" description="A React page demo">
|
|
<Head>
|
|
<meta property="og:image" content="image.png" />
|
|
<meta name="twitter:card" content="summary_large_image" />
|
|
<link rel="preconnect" href="https://example.com" />
|
|
<script type="application/ld+json">
|
|
{JSON.stringify({
|
|
'@context': 'https://schema.org/',
|
|
'@type': 'Organization',
|
|
name: 'Meta Open Source',
|
|
url: 'https://opensource.fb.com/',
|
|
logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
|
|
})}
|
|
</script>
|
|
</Head>
|
|
{/* ... */}
|
|
</Layout>
|
|
);
|
|
}
|
|
```
|
|
|
|
:::tip
|
|
|
|
For convenience, the default theme `<Layout>` component accept `title` and `description` as props.
|
|
|
|
:::
|
|
|
|
## Static HTML generation {#static-html-generation}
|
|
|
|
Docusaurus is a static site generator—HTML files are statically generated for every URL route, which helps search engines discover your content more easily.
|
|
|
|
## Image meta description {#image-meta-description}
|
|
|
|
The alt tag for an image tells the search engine what the image is about, and is used when the image can't be visually seen, e.g. when using a screen reader, or when the image is broken. Alt tags are commonly supported in Markdown.
|
|
|
|
You may also add a title for your image—this doesn't impact SEO much but is displayed as a tooltip when hovering above the image, usually used to provide hints.
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
<BrowserWindow>
|
|
|
|
|
|
|
|
</BrowserWindow>
|
|
|
|
## Rich search information {#rich-search-information}
|
|
|
|
Docusaurus blogs support [rich search results](https://search.google.com/test/rich-results) out-of-the-box to get maximum search engine experience. The information is created depending on your meta information in blog/global configuration. In order to get the benefits of the rich search information, fill in the information about the post's publish date, authors, and image, etc. Read more about the meta-information [here](./blog.mdx).
|
|
|
|
## Robots file {#robots-file}
|
|
|
|
A `robots.txt` file regulates search engines' behavior about which should be displayed and which shouldn't. You can provide it as [static asset](./static-assets.mdx). The following would allow access to all sub-pages from all requests:
|
|
|
|
```text title="static/robots.txt"
|
|
User-agent: *
|
|
Disallow:
|
|
```
|
|
|
|
Read more about the robots file in [the Google documentation](https://developers.google.com/search/docs/advanced/robots/intro).
|
|
|
|
:::warning
|
|
|
|
**Important**: the `robots.txt` file does **not** prevent HTML pages from being indexed.
|
|
|
|
To prevent your whole Docusaurus site from being indexed, use the [`noIndex`](./api/docusaurus.config.js.mdx#noIndex) site config. Some [hosting providers](./deployment.mdx) may also let you configure a `X-Robots-Tag: noindex` HTTP header (GitHub Pages does not support this).
|
|
|
|
To prevent a single page from being indexed, use `<meta name="robots" content="noindex">` as [page metadata](#single-page-metadata). Read more about the [robots meta tag](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag).
|
|
|
|
:::
|
|
|
|
## Sitemap file {#sitemap-file}
|
|
|
|
Docusaurus provides the [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.mdx) plugin, which is shipped with `preset-classic` by default. It autogenerates a `sitemap.xml` file which will be available at `https://example.com/[baseUrl]/sitemap.xml` after the production build. This sitemap metadata helps search engine crawlers crawl your site more accurately.
|
|
|
|
:::tip
|
|
|
|
The sitemap plugin automatically filters pages containing a `noindex` [robots meta directive](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag).
|
|
|
|
For example, [`/examples/noIndex`](/examples/noIndex) is not included in the [Docusaurus sitemap.xml file](pathname:///sitemap.xml) because it contains the following [page metadata](#single-page-metadata):
|
|
|
|
```html
|
|
<head>
|
|
<meta name="robots" content="noindex, nofollow" />
|
|
</head>
|
|
```
|
|
|
|
:::
|
|
|
|
## Human readable links {#human-readable-links}
|
|
|
|
Docusaurus uses your file names as links, but you can always change that using slugs, see this [tutorial](./guides/docs/docs-create-doc.mdx#document-id) for more details.
|
|
|
|
## Structured content {#structured-content}
|
|
|
|
Search engines rely on the HTML markup such as `<h2>`, `<table>`, etc., to understand the structure of your webpage. When Docusaurus renders your pages, semantic markup, e.g. `<aside>`, `<nav>`, `<main>`, are used to divide the different sections of the page, helping the search engine to locate parts like sidebar, navbar, and the main page content.
|
|
|
|
Most [CommonMark](https://spec.commonmark.org/0.30/#atx-headings) syntaxes have their corresponding HTML tags. By using Markdown consistently in your project, you will make it easier for search engines to understand your page content.
|