# LLM Rank — Full Documentation

> Analyze how AI-ready your website is.

LLM Rank is a free web application that evaluates websites on their readiness for AI and large language model (LLM) consumption. Given any URL, it fetches the page and analyzes it across seven weighted categories, producing a score from 0 to 100 and a letter grade from A+ to F.

## Purpose

As AI models increasingly crawl and reference web content, website owners need to understand how well their sites can be parsed, understood, and cited by LLMs. LLM Rank provides actionable scores and detailed check-by-check breakdowns so you can improve your site's AI discoverability.

## How It Works

1. Submit a URL via the web interface or the `/api/score` endpoint.
2. LLM Rank fetches the page's HTML, robots.txt, llms.txt, and sitemap.xml.
3. It runs checks in each of the seven scoring categories.
4. Each check produces a score and optional details explaining the result.
5. Category scores are weighted and combined into an overall score.
6. A letter grade is assigned based on the overall score.

## Scoring Categories (Detailed)

### 1. Structured Data (20% weight)
Evaluates the presence and quality of machine-readable metadata:
- **JSON-LD**: Valid JSON-LD structured data blocks using schema.org vocabulary
- **Open Graph**: og:title, og:description, og:image, og:url, og:type tags
- **Meta Description**: A meaningful meta description tag
- **Schema.org Types**: Use of appropriate schema.org types (Article, Organization, WebPage, etc.)

### 2. Semantic HTML (12% weight)
Evaluates proper use of HTML elements for meaning:
- **Heading Hierarchy**: Logical h1-h6 structure with a single h1
- **Landmark Elements**: Use of header, nav, main, footer, aside, section, article
- **List Structure**: Proper use of ul, ol, dl for list content
- **Table Semantics**: Use of thead, tbody, th, caption for tabular data

### 3. Content Clarity (15% weight)
Evaluates how clear and readable the content is:
- **Plain Language**: Avoidance of jargon and overly complex sentences
- **Keyword Presence**: Clear topic indicators in headings and early paragraphs
- **Readability**: Grade-level readability score
- **Content Length**: Sufficient content depth for the topic

### 4. Machine-Readable (13% weight)
Evaluates technical discoverability signals:
- **robots.txt**: Presence and validity of robots.txt
- **sitemap.xml**: Presence and validity of XML sitemap
- **Canonical URL**: Proper use of rel="canonical"
- **Language Declaration**: html lang attribute set correctly
- **Character Encoding**: Proper UTF-8 declaration

### 5. LLM Directives (20% weight)
Evaluates AI-specific discoverability:
- **llms.txt**: Presence of /llms.txt file following the llms.txt specification
- **robots.txt AI Rules**: Specific rules for AI crawlers (GPTBot, Google-Extended, etc.)
- **AI Meta Tags**: Any AI-specific meta directives

### 6. Accessibility (10% weight)
Evaluates content accessibility which also aids AI understanding:
- **Image Alt Text**: Descriptive alt attributes on images
- **ARIA Labels**: Proper use of aria-label, aria-describedby
- **Link Quality**: Descriptive link text (avoiding "click here")
- **Form Labels**: Proper labeling of form elements

### 7. Content Extraction (10% weight)
Evaluates how easily main content can be isolated:
- **Main Content Identifiable**: Clear main element or article element wrapping primary content
- **Signal-to-Noise Ratio**: Proportion of content vs. navigation, ads, boilerplate
- **DOM Structure**: Clean, well-nested DOM without excessive wrapper divs
- **Text Density**: Good ratio of text content to HTML markup

## Grading Scale

| Score Range | Grade |
|-------------|-------|
| 97-100      | A+    |
| 93-96       | A     |
| 90-92       | A-    |
| 87-89       | B+    |
| 83-86       | B     |
| 80-82       | B-    |
| 77-79       | C+    |
| 73-76       | C     |
| 70-72       | C-    |
| 67-69       | D+    |
| 63-66       | D     |
| 60-62       | D-    |
| 0-59        | F     |

## API Reference

### POST /api/score

Score a website's AI-readiness.

**Request:**
```json
{
  "url": "https://example.com"
}
```

**Response (200 OK):**
```json
{
  "url": "https://example.com",
  "fetchedAt": "2026-03-15T00:00:00Z",
  "overallScore": 85,
  "grade": "B",
  "categories": [
    {
      "category": "structured-data",
      "label": "Structured Data",
      "score": 90,
      "weight": 0.2,
      "checks": [
        {
          "name": "JSON-LD",
          "description": "Valid JSON-LD structured data blocks",
          "score": 100,
          "maxScore": 100
        }
      ]
    }
  ]
}
```

**Error Response (400):**
```json
{
  "error": "INVALID_URL",
  "message": "Please provide a valid HTTP or HTTPS URL"
}
```

### GET /api/leaderboard

Browse pre-scored websites ranked by AI-readiness.

**Query Parameters:**
- `page` (number, default: 1): Page number
- `pageSize` (number, default: 20, max: 100): Results per page
- `sort` (string, default: "overallScore"): Sort field — "overallScore", "name", or "url"
- `order` (string, default: "desc"): Sort direction — "asc" or "desc"

**Response (200 OK):**
```json
{
  "sites": [
    {
      "url": "https://en.wikipedia.org",
      "name": "Wikipedia",
      "description": "Free online encyclopedia",
      "report": { "..." }
    }
  ],
  "total": 30,
  "page": 1,
  "pageSize": 20
}
```

## Technology Stack

- **Frontend**: React, Vite, TypeScript
- **Backend**: Azure Functions (Node.js)
- **Hosting**: Azure Static Web Apps
- **HTML Parsing**: Cheerio
- **Robots.txt Parsing**: robots-parser