> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SEO Best Practices

Optimize your HolyDocs documentation site for search engines with meta tags, structured data, sitemaps, and content strategies.

## 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:

**Meta Tags**

Generates `<title>`, `<meta name="description">`, and Open Graph tags from your page frontmatter.
  **Sitemap**

Auto-generates `sitemap.xml` at your docs root with all navigable pages.
  **JSON-LD**

Adds structured data (Article schema) to every page for rich search results.
  **OG Images**

Auto-generates Open Graph images for social sharing on Twitter, Slack, and Discord.
  **Canonical URLs**

Sets canonical URLs on every page to prevent duplicate content issues.
  **Semantic HTML**

Renders pages with proper heading hierarchy, semantic elements, and accessible markup.

## Writing Effective Frontmatter

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

```mdx
---
title: Custom Domains
description: 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 Notes
noindex: true
---
```

## Open Graph Images

HolyDocs auto-generates OG images at:

```
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 Reference
og: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

```
https://docs.yourcompany.com/sitemap.xml
https://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](/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](/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](/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.