Link-rel Reference Guide

Learn how to reference your generated files in your website's HTML head using link-rel tags.

Each Geordy-generated file is referenced in your website's <head> via link-rel tags. This is the bridge between your live site and its structured data files — it tells AI crawlers exactly where to look.

How file paths work

Geordy generates files whose paths mirror your existing site structure. The base is always your Geordy subdomain (e.g. ai.yourdomain.com) or Geordy's hosted address (files.geordy.ai/yourdomain.com). Two files live at the root only: llms.txt and humans.txt. All other formats use an index.* naming convention for the homepage, and mirror your page path for inner pages.

Root-only files (homepage)

https://ai.yourdomain.com/llms.txt
https://ai.yourdomain.com/humans.txt

Homepage structured files

https://ai.yourdomain.com/index.md
https://ai.yourdomain.com/index.schema.json
https://ai.yourdomain.com/index.yaml
https://ai.yourdomain.com/index.og.json
https://ai.yourdomain.com/index.xml
https://ai.yourdomain.com/index.manifest.json

Inner page — e.g. /about/team

https://ai.yourdomain.com/about/team.md
https://ai.yourdomain.com/about/team.schema.json
https://ai.yourdomain.com/about/team.yaml
https://ai.yourdomain.com/about/team.og.json
https://ai.yourdomain.com/about/team.xml
https://ai.yourdomain.com/about/team.manifest.json

Don't have a custom subdomain? Replace ai.yourdomain.com with files.geordy.ai/yourdomain.com — the paths are identical.

Example — homepage link-rel block

Homepage <head>HTML
<!-- Geordy AI References -->
<link rel="llms" href="https://ai.yourdomain.com/llms.txt" type="text/plain" title="LLMs.txt" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/humans.txt" type="text/plain" title="Humans.txt" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/index.md" type="text/markdown" title="Markdown" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/index.schema.json" type="application/ld+json" title="Schema JSON-LD" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/index.yaml" type="application/yaml" title="YAML" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/index.og.json" type="application/json" title="Open Graph" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/index.xml" type="application/rss+xml" title="RSS Feed" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/index.manifest.json" type="application/json" title="Manifest" data-ai="true">

Example — inner page (/pricing)

/pricing <head>HTML
<!-- Geordy AI References (inner pages don't include llms.txt and humans.txt) -->
<link rel="alternate" href="https://ai.yourdomain.com/pricing.md" type="text/markdown" title="Markdown" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/pricing.schema.json" type="application/ld+json" title="Schema JSON-LD" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/pricing.yaml" type="application/yaml" title="YAML" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/pricing.og.json" type="application/json" title="Open Graph" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/pricing.xml" type="application/rss+xml" title="RSS Feed" data-ai="true">
<link rel="alternate" href="https://ai.yourdomain.com/pricing.manifest.json" type="application/json" title="Manifest" data-ai="true">

Link-rel Tags Reference

Copy and paste these tags into your HTML <head> section

<head>
<title>Your Website</title>
<!-- Geordy AI References -->
<link rel="alternate" href="https://ai.yourdomain.com/llms.txt" type="text/plain">
<link rel="alternate" href="https://ai.yourdomain.com/humans.txt" type="text/plain">
<link rel="alternate" href="https://ai.yourdomain.com/index.md" type="text/markdown">
<link rel="alternate" href="https://ai.yourdomain.com/index.schema.json" type="application/ld+json">
<link rel="alternate" href="https://ai.yourdomain.com/index.yaml" type="text/yaml">
<link rel="alternate" href="https://ai.yourdomain.com/index.og.json" type="application/json">
<link rel="alternate" href="https://ai.yourdomain.com/index.xml" type="application/rss+xml">
<link rel="manifest" href="https://ai.yourdomain.com/index.manifest.json" type="application/json">
</head>
llms.txtHomepage only
rel="alternate" type="text/plain"
humans.txtHomepage only
rel="alternate" type="text/plain"
index.mdEvery page
rel="alternate" type="text/markdown"
index.schema.jsonEvery page
rel="alternate" type="application/ld+json"
index.yamlEvery page
rel="alternate" type="text/yaml"
index.og.jsonEvery page
rel="alternate" type="application/json"
index.xmlEvery page
rel="alternate" type="application/rss+xml"
index.manifest.jsonEvery page
rel="manifest" type="application/json"
Best Practice: Always use absolute URLs (including https://) for maximum compatibility with AI crawlers and search engines.

Dynamic sitewide implementation

Rather than adding tags manually to every page, use a reusable React component that automatically generates the correct file URLs based on the current page path. This ensures every page points to its own Geordy files.

components/geordy-tags.tsxTSX
// components/geordy-tags.tsx
import React from "react"

interface GeordyTagsProps {
  domain: string
  pagePath?: string
  /** Enable/disable specific formats. All enabled by default. */
  formats?: {
    yaml?: boolean
    markdown?: boolean
    llms?: boolean
    schema?: boolean
    rss?: boolean
    manifest?: boolean
    humans?: boolean
    og?: boolean
  }
}

export function GeordyTags({ 
  domain, 
  pagePath = "/",
  formats = {}
}: GeordyTagsProps) {
  const today = new Date().toISOString().slice(0, 10)
  const isRoot = pagePath === "/"
  // Preserve path structure: /about/team -> about/team
  const pathSegment = isRoot ? "index" : pagePath.replace(/^\//, "")
  const base = `https://files.geordy.ai/${domain}`

  // Default all formats to true if not specified
  const {
    yaml = true,
    markdown = true,
    llms = true,
    schema = true,
    rss = true,
    manifest = true,
    humans = true,
    og = true,
  } = formats

  return (
    <>
      {/* Per-page formats */}
      {yaml && (
        <link rel="alternate" type="application/yaml" href={`${base}/${pathSegment}.yaml`} title="YAML" data-ai="true" />
      )}
      {markdown && (
        <link rel="alternate" type="text/markdown" href={`${base}/${pathSegment}.md`} title="Markdown" data-ai="true" />
      )}
      {schema && (
        <link rel="alternate" type="application/ld+json" href={`${base}/${pathSegment}.schema.json`} title="Schema JSON-LD" data-ai="true" />
      )}
      {rss && (
        <link rel="alternate" type="application/rss+xml" href={`${base}/${pathSegment}.xml`} title="RSS Feed" data-ai="true" />
      )}
      {manifest && (
        <link rel="alternate" type="application/json" href={`${base}/${pathSegment}.manifest.json`} title="Manifest" data-ai="true" />
      )}
      {og && (
        <link rel="alternate" type="application/json" href={`${base}/${pathSegment}.og.json`} title="Open Graph" data-ai="true" />
      )}
      
      {/* Root-only formats - same URL regardless of current page */}
      {llms && (
        <link rel="llms" href={`${base}/llms.txt`} title="LLMs.txt" data-ai="true" data-version={today} />
      )}
      {humans && (
        <link rel="alternate" type="text/plain" href={`${base}/humans.txt`} title="Humans.txt" data-ai="true" />
      )}
    </>
  )
}
Usage in Next.jsTSX
// app/layout.tsx (for static paths)
import { GeordyTags } from "@/components/geordy-tags"

return function Layout({ children }) {
  return (
    <html>
      <head>
        <GeordyTags domain="yourdomain.com" pagePath="/about/team" />
      </head>
      <body>{children}</body>
    </html>
  )
}

// For dynamic routes (recommended):
"use client"
import { usePathname } from "next/navigation"
import { GeordyTags } from "@/components/geordy-tags"

export function DynamicGeordyTags({ domain }: { domain: string }) {
  const pathname = usePathname()
  return <GeordyTags domain={domain} pagePath={pathname} />
}

// To disable specific formats:
<GeordyTags 
  domain="yourdomain.com" 
  pagePath={pathname} 
  formats={{ rss: false, manifest: false }} 
/>

Best Practices

Always use absolute URLs

Use full URLs including the protocol and domain. Relative paths may not be correctly interpreted by AI crawlers.

✓ https://ai.yourdomain.com/index.md

✗ /index.md

Place in <head>, before scripts

Keep all link-rel tags inside <head> and above any <script> tags for optimal discovery.

llms.txt and humans.txt are root-level files

These files exist at the root only. Note that llms.txt uses rel="llms" (not "alternate") as per the llmstxt.org specification. You can include these tags on all pages since they point to the same root files.

Complete file reference

FileRelTypeScope
llms.txtllmstext/plainHomepage only
humans.txtalternatetext/plainHomepage only
[page].mdalternatetext/markdownEvery page
[page].schema.jsonalternateapplication/ld+jsonEvery page
[page].yamlalternateapplication/yamlEvery page
[page].og.jsonalternateapplication/jsonEvery page
[page].xmlalternateapplication/rss+xmlEvery page
[page].manifest.jsonalternateapplication/jsonEvery page

Troubleshooting

If your link-rel tags aren't working as expected, check the following:

  • Verify the URLs are accessible (return HTTP 200)
  • Ensure tags are placed in the <head> section
  • Check for typos in the href or type attributes
  • Confirm your custom domain is properly configured

For more help, see Tags or JSON-LD Missing.

Next Steps

Learn more about the JSON-LD Schema format and how it structures your content for search engines.

← Validation ToolsJSON-LD Schema Reference →