SEO Best Practices

Overview

HolyDocs includes several built-in SEO features that work automatically. This guide covers what is automatic, what you can configure, and best practices for maximizing your documentation's search visibility.

Automatic SEO Features

HolyDocs handles these SEO features out of the box with no configuration:

Writing Effective Frontmatter

The most important SEO optimization is writing good frontmatter on every page:

mdx
---title: Custom Domainsdescription: Configure a custom domain for your HolyDocs documentation site with automatic SSL certificate provisioning.---

Title Best Practices

• Keep titles under 60 characters to avoid truncation in search results
• Include the primary keyword near the beginning
• Make titles descriptive and specific (not "Getting Started" — but "Getting Started with HolyDocs")
• Each page should have a unique title

Description Best Practices

• Keep descriptions between 120-160 characters
• Include target keywords naturally
• Write a compelling summary that encourages clicks
• Each page should have a unique description

Every page should have both title and description in frontmatter. Pages without descriptions still render but miss the SEO meta tag, which can hurt click-through rates from search results.

Configuring SEO Settings

Meta Tags

Add global meta tags in docs.json:

json
{  "seo": {    "metatags": {      "og:site_name": "My API Docs",      "twitter:site": "@mycompany",      "twitter:card": "summary_large_image"    }  }}

Indexing Control

Control which pages search engines can index:

json
{  "seo": {    "indexing": "navigable"  }}

Value	Behavior
navigable	Only pages listed in navigation are indexed (recommended)
all	All pages are indexed, including unlisted ones

Per-Page Noindex

Exclude specific pages from search engines using frontmatter:

mdx
---title: Internal Notesnoindex: true---

Open Graph Images

HolyDocs auto-generates OG images at:

text
https://api.holydocs.com/api/v1/og-image/PROJECT_ID?path=/quickstart

The generated image includes:

• Page title in your configured heading font
• Page description
• Your project's primary color as accent
• Your logo (if configured)

Custom OG Images

Override the auto-generated image with a custom one in frontmatter:

mdx
---title: API Referenceog:image: /images/api-reference-og.png---

Sitemap

HolyDocs generates a sitemap.xml at your docs root. The sitemap:

• Includes all navigable pages with their last-modified dates
• Automatically updates on every deployment
• Uses the correct domain (custom domain or subdomain)
• Is referenced in a robots.txt file served at your docs root

text
https://docs.yourcompany.com/sitemap.xmlhttps://docs.yourcompany.com/robots.txt

Internal Linking

Good internal linking helps both search engines and readers:

• Link related pages from within your content using [text](/quickstart)
• Use descriptive anchor text (not "click here" — but "see the Custom Domains guide")
• Create a logical hierarchy with your navigation structure
• Use "Next Steps" card groups at the bottom of pages to guide readers

mdx
<CardGroup cols={2}>  <Card title="Custom Domains" icon="globe" href="/custom-domains">    Set up your own domain with automatic SSL.  </Card>  <Card title="Deployments" icon="rocket" href="/deployments">    Learn about the build pipeline and deployment statuses.  </Card></CardGroup>

Content Structure

Heading Hierarchy

Use proper heading levels (##, ###, ####) in a logical hierarchy. HolyDocs generates a table of contents from ## and ### headings, and search engines use heading structure to understand page organization.

URL Structure

Page URLs are derived from file paths:

• guides/setup.mdx → /guides/setup
• Keep URLs short, descriptive, and keyword-rich
• Use hyphens (not underscores) in file names
• Avoid deeply nested paths when possible

Redirects

When you rename or restructure pages, add redirects to preserve search engine rankings:

json
{  "redirects": [    {      "source": "/old-page",      "destination": "/new-page",      "permanent": true    }  ]}

Use permanent (301) redirects for moved pages — they tell search engines to transfer ranking signals to the new URL. See Redirects.

AI Search Engine Optimization

HolyDocs generates files that help AI search engines and LLMs find and cite your documentation:

File	Purpose
llms.txt	Concise summary with page titles and descriptions
llms-full.txt	Full text content of all pages
skill.md	Structured skill file for AI agent systems
agent-card.json	ERC-8004 agent card for AI discovery

These files are automatically generated on every deployment. See llms.txt for details.

Monitoring

Track your documentation's search performance:

1. Google Search Console — Submit your sitemap and monitor impressions, clicks, and rankings
2. HolyDocs Analytics — View which search queries readers use on your site
3. Zero-result queries — Check the dashboard for queries that returned no results and create content to fill gaps

Subfolder hosting (yoursite.com/docs) inherits your main domain's SEO authority, while subdomain hosting (docs.yoursite.com) is treated as a separate site by search engines. Choose subfolder hosting if SEO is a priority.