Docsalot home pagelight logo
  1. Improve Dev Experience
  2. SEO

Docsalot automatically handles many SEO best practices, including:

  • Meta tag generation
  • Sitemap and robots.txt file generation
  • Semantic HTML structure
  • Mobile optimization

You can fully customize your site’s meta tags by adding the metatags field to your docs.json or a page’s frontmatter.

​
Automatically generated meta tags

Docsalot generates the following meta tags for every page. You can override these meta tags by specifying them in your docs.json or a page’s frontmatter.

Basic metadata:

  • charset: utf-8 - Character encoding
  • og:type: website - Open Graph type
  • og:site_name - Your documentation site name
  • twitter:card: summary_large_image - Twitter card type

Page-specific metadata:

  • title - Page title, formatted as “Page Title - Site Name”
  • og:title - Open Graph title, same as page title
  • twitter:title - Twitter title, same as page title
  • description - Page description
  • og:description - Open Graph description, same as page description
  • twitter:description - Twitter description, same as page description

URL and canonical:

  • canonical - Automatically built from page URL
  • og:url - Set to canonical URL

SEO and indexing:

  • robots - Generated from page metadata
  • noindex - Generated from page metadata
  • keywords - Generated from page metadata

Images:

  • og:image - Open Graph image, og:image:width set to 1200 and og:image:height 630
  • twitter:image - Twitter image, twitter:image:width set to 1200 and twitter:image:height 630

Browser and app metadata:

  • applicationName - Your documentation site name
  • generator: Docsalot - Identifies the site generator as Docsalot
  • apple-mobile-web-app-title - iOS home screen app name
  • msapplication-TileColor - Windows tile color
  • Favicons and icons from your config
  • Sitemap reference link

Any meta tags in your docs.json seo.metatags configuration are also automatically injected into every page, such as google-site-verification for search console validation.

​
Global meta tags

To set default meta tags for all pages, add the metatags field to your docs.json.

theme={null}
"seo": {
    "metatags": {
        "og:image": "link to your default meta tag image"
    }
}

​
Set a canonical URL

If you’re using a custom domain, set the canonical meta tag to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

theme={null}
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}

​
Page-specific meta tags

To set page-specific meta tags, add them to a page’s frontmatter.

The following meta tags are supported at the page level:

  • title - Page title
  • description - Page description appears below the title on the page and in some search engine results
  • keywords - Comma-separated keywords
  • og:title - Open Graph title for social sharing
  • og:description - Open Graph description
  • og:image - Open Graph image URL
  • og:url - Open Graph URL
  • og:type - Open Graph type like “article” or “website”
  • og:image:width - Open Graph image width
  • og:image:height - Open Graph image height
  • twitter:title - Twitter card title
  • twitter:description - Twitter card description
  • twitter:image - Twitter card image
  • twitter:card - Twitter card type like “summary” or “summary_large_image”
  • twitter:site - Twitter site handle
  • twitter:image:width - Twitter image width
  • twitter:image:height - Twitter image height
  • noindex - Set to true to prevent search engine indexing
  • robots - Robots meta tag value
theme={null}
---
title: "Your example page title"
description: "Page-specific description"
"og:image": "link to your meta tag image"
"og:title": "Social media title"
keywords: ["keyword1", "keyword2"]
---

Meta tags with colons must be wrapped in quotes. The keywords field must be formatted as a YAML array.

​
Common meta tags reference

Below is a comprehensive list of meta tags you can add to your docs.json. These meta tags help improve your site’s SEO, social sharing, and browser compatibility.

The og:image adds a background image that Docsalot automatically overlays with your logo, page title, and description when generating social media previews.

You can preview how your meta tags will appear on different platforms using metatags.io.

expandable theme={null}
"seo": {
    "metatags": {
      "robots": "noindex",
      "charset": "UTF-8",
      "viewport": "width=device-width, initial-scale=1.0",
      "description": "Page description",
      "keywords": "keyword1, keyword2, keyword3",
      "author": "Author Name",
      "robots": "index, follow",
      "googlebot": "index, follow",
      "google": "notranslate",
      "google-site-verification": "verification_token",
      "generator": "Docsalot",
      "theme-color": "#000000",
      "color-scheme": "light dark",
      "canonical": "https://your-custom-domain-here.com",
      "format-detection": "telephone=no",
      "referrer": "origin",
      "refresh": "30",
      "rating": "general",
      "revisit-after": "7 days",
      "language": "en",
      "copyright": "Copyright 2024",
      "reply-to": "faizank@docsalot.dev",
      "distribution": "global",
      "coverage": "Worldwide",
      "category": "Technology",
      "target": "all",
      "HandheldFriendly": "True",
      "MobileOptimized": "320",
      "apple-mobile-web-app-capable": "yes",
      "apple-mobile-web-app-status-bar-style": "black",
      "apple-mobile-web-app-title": "App Title",
      "application-name": "App Name",
      "msapplication-TileColor": "#000000",
      "msapplication-TileImage": "path/to/tile.png",
      "msapplication-config": "path/to/browserconfig.xml",
      "og:title": "Open Graph Title",
      "og:type": "website",
      "og:url": "https://example.com",
      "og:image": "https://example.com/image.jpg",
      "og:description": "Open Graph Description",
      "og:site_name": "Site Name",
      "og:locale": "en_US",
      "og:video": "https://example.com/video.mp4",
      "og:audio": "https://example.com/audio.mp3",
      "twitter:card": "summary",
      "twitter:site": "@username",
      "twitter:creator": "@username",
      "twitter:title": "Twitter Title",
      "twitter:description": "Twitter Description",
      "twitter:image": "https://example.com/image.jpg",
      "twitter:image:alt": "Image Description",
      "twitter:player": "https://example.com/player",
      "twitter:player:width": "480",
      "twitter:player:height": "480",
      "twitter:app:name:iphone": "App Name",
      "twitter:app:id:iphone": "12345",
      "twitter:app:url:iphone": "app://",
      "article:published_time": "2024-01-01T00:00:00+00:00",
      "article:modified_time": "2024-01-02T00:00:00+00:00",
      "article:expiration_time": "2024-12-31T00:00:00+00:00",
      "article:author": "Author Name",
      "article:section": "Technology",
      "article:tag": "tag1, tag2, tag3",
      "book:author": "Author Name",
      "book:isbn": "1234567890",
      "book:release_date": "2024-01-01",
      "book:tag": "tag1, tag2, tag3",
      "profile:first_name": "John",
      "profile:last_name": "Doe",
      "profile:username": "johndoe",
      "profile:gender": "male",
      "music:duration": "205",
      "music:album": "Album Name",
      "music:album:disc": "1",
      "music:album:track": "1",
      "music:musician": "Artist Name",
      "music:song": "Song Name",
      "music:song:disc": "1",
      "music:song:track": "1",
      "video:actor": "Actor Name",
      "video:actor:role": "Role Name",
      "video:director": "Director Name",
      "video:writer": "Writer Name",
      "video:duration": "120",
      "video:release_date": "2024-01-01",
      "video:tag": "tag1, tag2, tag3",
      "video:series": "Series Name"
  }
}

​
Sitemaps and robots.txt files

Docsalot automatically generates a sitemap.xml file and a robots.txt file. You can view your sitemap by appending /sitemap.xml to your documentation site’s URL.

Only pages included in your docs.json are included by default. To include hidden links, add seo.indexing to your docs.json:

theme={null}
"seo": {
    "indexing": "all"
}

​
Custom sitemaps and robots.txt files

To add a custom sitemap.xml or robots.txt file, create a sitemap.xml or robots.txt file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.

​
Disabling indexing

If you want to stop a page from being indexed by search engines, you can include the following in the frontmatter of your page:

---
noindex: true
---

You can also specify noindex for all pages in your docs by setting the metatags.robots field to "noindex" in your docs.json:

theme={null}
"seo": {
    "metatags": {
      "robots": "noindex"
    }
  }

​
SEO best practices