Boltdocs Logo
GuidesIntegrationsAPIPluginsComponentsReleases

SEO & Robots

Automatic sitemap, robots.txt, meta tags, and Open Graph images for search engines and social media.

Boltdocs automatically generates SEO metadata for every page. This includes sitemap.xml, robots.txt, canonical URLs, Open Graph tags, and Twitter Cards.

SEO Configuration ReferenceLink

SeoConfigLink

PropertyTypeDefaultDescription
indexing'all' | 'public' | 'none' | string'all'Controls the <meta name="robots"> tag. 'all' and 'public' emit index,follow; 'none' emits noindex,nofollow. Custom strings are emitted as-is.
thumbnailsThumbnailConfig—Open Graph image configuration.
defaultImagestring—Fallback OG image for pages without frontmatter.

ThumbnailConfigLink

PropertyTypeDescription
backgroundstringPath to the background image for OG cards.
theme'light' | 'dark'Theme for auto-generated thumbnails.

Robots Configuration ReferenceLink

PropertyTypeDescription
rulesRobotRule[]Array of crawling rules.
sitemapsstring[]URLs of sitemap.xml files.

RobotRuleLink

PropertyTypeDescription
userAgentstringTarget user agent (e.g. '*' for all).
allowstring | string[]Paths to allow.
disallowstring | string[]Paths to disallow.
crawlDelaynumberDelay between requests (in seconds).

Auto-Generated FilesLink

sitemap.xmlLink

Generated at build time. Contains all indexed routes with:

  • loc — Full URL
  • lastmod — Last modified date (from git or file mtime)
  • changefreq — Page update frequency
  • priority — Computed from the sidebar position

Generated robots.txtLink

Generated from your robots configuration. Example output:

text
User-Agent: *
Allow: /
Disallow: /private/
Sitemap: https://docs.example.com/sitemap.xml

Structured Data (JSON-LD)Link

Structured data is metadata for search engines and crawlers. It's independent of Boltdocs' internal search index. Use JSON-LD to describe your site, articles, and breadcrumbs via a schema.org-compatible graph.

Global site dataLink

Use the Node-safe helpers from boltdocs in boltdocs.config.ts:

ts
import {
  createWebSiteStructuredData,
  defineConfig,
  defineStructuredData,
} from 'boltdocs'

export default defineConfig({
  siteUrl: 'https://docs.example.com',
  seo: {
    structuredData: defineStructuredData(
      createWebSiteStructuredData({
        name: 'Example Docs',
        url: 'https://docs.example.com',
        description: 'Product documentation',
      }),
    ),
  },
})

Page-specific dataLink

Add structuredData inside seo in the MDX frontmatter:

mdx
---
title: Getting Started
seo:
  structuredData:
    '@context': https://schema.org
    '@type': TechArticle
    headline: Getting Started
---

In external React pages, render <StructuredData data={...} /> from boltdocs/client. The createArticleStructuredData and createBreadcrumbStructuredData helpers cover the most common article and navigation graphs.

StructuredData ReferenceLink

APIPurpose
defineStructuredData(data)Preserves typed JSON-LD objects in configuration files.
createWebSiteStructuredData(options)Creates a WebSite graph, with optional search action.
createArticleStructuredData(options)Creates an Article graph with author, dates, image, and description.
createBreadcrumbStructuredData(items)Creates a BreadcrumbList graph from named URLs.
<StructuredData data={...} />Emits a safe application/ld+json script from an external page.

Per-Page SEO OverrideLink

Override global SEO settings in frontmatter:

md
---
title: Internal Page
seo:
  noindex: true
  og:image: /custom-og.png
  twitter:card: summary
---
PropertyTypeDescription
noindexbooleanAdds a noindex meta tag.
og:imagestringCustom Open Graph image.
og:typestringOpen Graph type (default: 'website').
twitter:cardstringTwitter card type.

Open Graph ImagesLink

Boltdocs auto-generates OG images using seo.thumbnails.background. Every page gets a generated image with:

  • Your background image
  • The page title overlaid
  • The site name in the corner

Manual OG ImageLink

Override per page:

md
---
seo:
  og:image: /assets/my-custom-og.png
---

Or globally:

ts
export default defineConfig({
  seo: {
    defaultImage: '/default-og.png',
  },
})

Canonical URLsLink

Canonical URLs are automatically generated for every page based on siteUrl + page path. This helps consolidate duplicate content issues.

TroubleshootingLink

sitemap.xml missingLink

Make sure siteUrl is configured.

Duplicate contentLink

Check the canonical URLs in the page source. Use permalink in frontmatter to set consistent URLs.

OG images not showingLink

Verify that seo.thumbnails.background points to a valid image. Check card validators for social networks:

Jesús Alcalá
Last updated on October 18, 2026

Was this page helpful?