DOCUSAURUS SEO AUDIT · MDX METADATA · SITEMAP PLUGIN · AI VISIBILITY
Free Docusaurus SEO Audit
Docusaurus generates static HTML — great for SEO — but meta descriptions often default to auto-extracted first paragraphs, sitemap plugin configuration needs tuning, and AI visibility requires explicit setup. DeepSEOAnalysis audits Docusaurus sites for metadata coverage, sitemap quality, and AI search visibility.
WHAT WE CHECK
6 Docusaurus-specific SEO checks
Beyond the 80+ general checks, the engine applies Docusaurus-aware analysis — detecting frontmatter metadata gaps, URL depth patterns from file-system routing, sitemap plugin configuration, robots.txt in the static/ directory, and AI visibility signals — with Docusaurus config keys and MDX frontmatter field names for each fix.
MDX frontmatter metadata coverage
Docusaurus documentation pages use MDX files with YAML frontmatter for per-page metadata. The key fields: `title` (sets both the `<h1>` and `title` tag), `description` (sets the `meta name="description"` and `meta property="og:description"` tags), `keywords` (comma-separated keywords for the `meta name="keywords"` tag — low SEO value but harmless), and `image` (the OG image for social sharing). Without `description` in frontmatter, Docusaurus falls back to extracting the first paragraph of the page content as the meta description — this often produces descriptions that are too long, don\'t start with the primary keyword, or begin with site navigation text. The audit checks every crawled docs page for a unique, non-empty meta description in the static HTML and flags pages using the auto-extracted first-paragraph fallback when that fallback produces non-optimised descriptions (very long, starts with code, or identical across multiple pages).
Docs URL structure and breadcrumb depth
Docusaurus generates URLs from the file system structure of the `docs/` directory. A file at `docs/api/authentication/oauth.md` generates `/docs/api/authentication/oauth`. Deep nesting beyond 3 levels (`/docs/category/subcategory/sub-subcategory/page`) creates high click depth and long URL paths that reduce keyword density per segment. The recommended structure: keep docs at 2–3 levels deep (`/docs/category/page`), use `slug` frontmatter to override file-system-derived URLs for pages where the generated URL is sub-optimal. For versioned docs (`/docs/2.x/page`), older version URLs may duplicate content from the current version — add the version-specific `noindex` frontmatter (`custom_edit_url: null` and a custom `<Head><meta name="robots" content="noindex" /></Head>`) to older archived versions to prevent duplicate content dilution. The audit detects URL depth patterns and flags pages beyond depth 4 from the root.
Sitemap plugin configuration
`@docusaurus/plugin-sitemap` generates `sitemap.xml` at build time and is included in `@docusaurus/preset-classic` by default. Configuration options in `docusaurus.config.ts` under the `sitemap` plugin config: `changefreq` (default `weekly`) and `priority` (default `0.5`) are set per-site but ignored by Google (documented in the plugin); `ignorePatterns` is the important one — use it to exclude tag pages (`/tags/**`), category index pages with thin content, and any non-canonical paths. Draft pages (frontmatter `draft: true`) are automatically excluded. The generated sitemap is placed at `/sitemap.xml` in the static build output. Common gaps: `ignorePatterns` not configured, so tag index pages and empty category listings are included in the sitemap; the `Sitemap:` directive is absent from `static/robots.txt`; versioned docs pages from old versions are included with duplicate content. The audit checks sitemap URL count vs crawled pages and the Sitemap directive.
robots.txt configuration
Place `robots.txt` in Docusaurus\'s `static/` directory — it\'s copied verbatim to the build output root and served at `/robots.txt`. A minimal but complete `robots.txt` for a Docusaurus documentation site: allow all crawlers, disallow tag/category utility pages that don\'t benefit from indexing (`Disallow: /tags/`), include the `Sitemap:` directive (`Sitemap: https://yourdomain.com/sitemap.xml`), and explicitly allow AI crawlers. Common gaps: `static/robots.txt` doesn\'t exist (Docusaurus serves a 404 at `/robots.txt`, which Googlebot treats as "no restrictions" but is technically incorrect); AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Applebot-Extended) are blocked by a broad `Disallow: /` from a security template; the `Sitemap:` directive is missing; docs search index routes (`/search`) are not mentioned. The audit checks the file at `/robots.txt`, all AI crawler user-agents, and the Sitemap directive.
Static HTML output and Core Web Vitals
Docusaurus generates static HTML at build time — every docs page is pre-rendered to HTML and deployed as a static file. Googlebot receives the full page content on the first HTTP response with no JavaScript rendering delay. This is the correct SEO baseline. Core Web Vitals on Docusaurus sites are typically good but can degrade with: large embedded code blocks (syntax highlighting libraries add JS weight); custom React components added to MDX that include heavy third-party dependencies; embedded iframes (video embeds, interactive demos) that delay LCP or cause CLS; and theme customisations that add render-blocking CSS or JavaScript. The built-in Docusaurus theme is performant. Custom themes and plugin additions introduce the most performance risk. The audit uses real CrUX field data (LCP, INP, CLS from actual Chrome users) for your Docusaurus site, segmented by mobile and desktop.
AI visibility for Docusaurus documentation sites
Serve `llms.txt` by placing it in Docusaurus\'s `static/` directory (`static/llms.txt` → `/llms.txt`). For documentation sites, `llms.txt` is especially valuable: AI assistants frequently cite technical documentation, and `llms.txt` guides them to the correct canonical URLs and context for your project. FAQPage JSON-LD for documentation FAQ pages: add a custom React component or MDX block that renders `script type="application/ld+json"` with FAQPage schema in the page\'s static HTML. In Docusaurus, you can add JSON-LD in MDX using a raw `script` tag (Docusaurus renders raw HTML in MDX) or via a custom Swizzled theme component that reads structured data from frontmatter and injects it into the head. Article JSON-LD for individual docs pages can be added via the `@docusaurus/plugin-sitemap`\'s related structured data hooks or a custom plugin. The audit checks all five AI visibility signals with Docusaurus-specific implementation patterns.
HOW IT WORKS
Audit your Docusaurus site in 60 seconds
- Enter your Docusaurus site URL. Works with any Docusaurus version (v2, v3) deployed on any host: GitHub Pages, Netlify, Vercel, Cloudflare Pages, AWS S3, or self-hosted. No access to the source MDX files or `docusaurus.config.ts` needed — the audit crawls the live static site.
- We crawl and analyse. The engine crawls up to 50 pages (free) or 1,000 pages (paid), checks frontmatter metadata coverage per page, detects auto-extracted vs frontmatter-defined descriptions, validates JSON-LD structured data in the static HTML, tests sitemap configuration and the Sitemap directive in robots.txt, measures CrUX Core Web Vitals, and evaluates all five AI visibility signals.
- You get a prioritised report. Docusaurus-specific issues first — frontmatter description gaps, URL depth, sitemap plugin ignorePatterns, robots.txt in static/, llms.txt — then general SEO, each with Docusaurus config keys, frontmatter field names, and static/ directory paths for the fix.
FAQ
Questions about the Docusaurus SEO audit
Is Docusaurus good for SEO?
Yes — Docusaurus generates static HTML at build time (SSG), delivering complete page content to Googlebot on the first HTTP response with no rendering delay. The `@docusaurus/plugin-sitemap` generates `sitemap.xml` automatically from your docs structure. The `@docusaurus/plugin-ideal-image` handles image optimisation. Per-page metadata is configured via MDX frontmatter (`title`, `description`, `keywords`, `image`) or React Helmet in custom pages. The main SEO gaps on Docusaurus sites: missing or duplicate meta descriptions across docs pages (many pages use the first paragraph as description, which is often not an optimised meta description); shallow internal linking from docs pages to related docs; and AI visibility signals that need explicit configuration (llms.txt, FAQPage schema).
How do I set meta titles and descriptions in Docusaurus?
In Docusaurus MDX files, use frontmatter: `---\\ntitle: "Page Title"\\ndescription: "Meta description for this page (150-160 characters)."\\n---`. The `title` becomes both the page\'s `<h1>` and the `title` tag; you can separate them with `title` (for H1) and a custom `head` block for the `title` tag if needed. For the site-level default title format, configure `themeConfig.navbar.title` and `titleDelimiter` in `docusaurus.config.ts`. Custom React pages use the `<Head>` component from `@docusaurus/Head` (a wrapper around React Helmet): `import Head from \'@docusaurus/Head\'; <Head><title>Custom Title</title><meta name="description" content="..." /></Head>`. The audit checks every crawled docs page for a unique, non-empty title and meta description in the static HTML.
Does Docusaurus generate a sitemap automatically?
Yes — `@docusaurus/plugin-sitemap` is included in the preset and generates `sitemap.xml` at build time from all public docs pages. Configuration in `docusaurus.config.ts`: the plugin is included via `preset: \'@docusaurus/preset-classic\'` by default; configure it in the `presets` array under `sitemap: { changefreq: \'weekly\', priority: 0.5, ignorePatterns: [\'/tags/**\'] }`. Draft docs pages (those with `draft: true` in frontmatter) are excluded from the sitemap automatically. The `Sitemap:` directive in `robots.txt` should reference the generated sitemap URL. The audit checks sitemap presence, URL coverage relative to crawled pages, and the Sitemap directive.
Is the Docusaurus SEO audit free?
Yes. The complete audit is free with no signup and no email gate. Paid plans add saved history, scheduled monitoring, larger crawls (up to 1,000 pages), and agency workflows.