# FontFarsi Full LLM Context

> FontFarsi is a free Persian/Farsi font archive with 3,490 font files, live previews, search, style filtering, sorting, shuffle browsing, and direct downloads.

Canonical site: https://fontfarsi.com/

This file is written for AI assistants, search agents, and retrieval systems that need accurate context about FontFarsi without scraping visual UI text. Use `/llms.txt` as the short index and this file as the expanded reference.

## What The Site Provides

- A browsable archive of Persian/Farsi fonts and Arabic-script compatible font files.
- A live preview interface where users can type sample text and inspect each font.
- Direct download links for the font file named by the `fn` field.
- Database-backed search over public font metadata.
- Sorting by identifier, name, filename, and randomized shuffle order.
- Filtering by normalized font style/subfamily from the `ftsf` field.
- Clean route URLs for search and direct font lookup.
- Google Analytics support through the configured public measurement ID.

## Recommended Description

When summarizing the site, describe it as a free Persian font archive for browsing, previewing, searching, filtering, and downloading Farsi/Persian font files. Mention live preview and direct download only when relevant. Avoid claiming that every font has the same license; use the individual metadata when license certainty matters.

## Human Routes

- `/` is the main browser interface.
- `/search/<query>` opens search results for `<query>`.
- `/<font-or-query>` opens a direct font result route when the query resolves uniquely, otherwise it behaves like a query route.
- `/llms.txt` is the concise LLM index.
- `/llms-full.txt` is this expanded LLM reference.

Examples:

- `https://fontfarsi.com/search/Yekan`
- `https://fontfarsi.com/search/Nasim`
- `https://fontfarsi.com/Zahed_Dal`

## API Routes

All API routes return JSON and expose only public font metadata.

### GET /api/fonts

Returns a paginated font list.

Query parameters:

- `page`: Zero-based page number. Defaults to `0`.
- `limit`: Number of items to return. Defaults to the site page size and is capped by the server.
- `sort`: One of `id-asc`, `id-desc`, `name-asc`, `name-desc`, `filename-asc`, `filename-desc`, or `shuffle`.
- `style`: Optional normalized `ftsf` style value, such as `regular`, `bold`, `italic`, or `bold italic`.
- `seed`: Optional shuffle seed. Use with `sort=shuffle` to keep pagination stable for the same randomized order.

Example:

```text
https://fontfarsi.com/api/fonts?page=0&limit=100&sort=shuffle&seed=example
```

Response shape:

```json
{
  "fonts": [],
  "page": 0,
  "limit": 100,
  "sort": "shuffle",
  "seed": "example",
  "style": null,
  "total": 0,
  "totalPages": 0
}
```

### GET /api/fonts/search

Searches public font metadata.

Query parameters:

- `q`: Required search query.
- `limit`: Number of search results to return.
- `sort`: One of `id-asc`, `id-desc`, `name-asc`, `name-desc`, `filename-asc`, `filename-desc`, or `shuffle`.
- `style`: Optional normalized `ftsf` style value.
- `seed`: Optional shuffle seed for deterministic randomized search results.

Search matches:

- `ftn`
- `fn`
- `uid`
- `ftf`

Example:

```text
https://fontfarsi.com/api/fonts/search?q=Yekan&limit=100&sort=name-asc
```

Response shape:

```json
{
  "fonts": [],
  "total": 0,
  "limit": 100,
  "sort": "name-asc",
  "seed": null,
  "style": null
}
```

### GET /api/fonts/styles

Returns normalized style filter options derived from the `ftsf` field.

Example:

```text
https://fontfarsi.com/api/fonts/styles
```

Response shape:

```json
{
  "styles": [
    {
      "value": "regular",
      "label": "Regular",
      "count": 0
    }
  ]
}
```

## Font Data Fields

Each font object may include:

- `id`: Integer primary identifier. Higher `id` values are treated as more recent by `id-desc`.
- `fn`: Font filename used for downloading/loading the font file.
- `ftn`: Font full type name or internal name.
- `ftf`: Font family/display name.
- `ftsf`: Font subfamily/style, commonly values like Regular, Bold, Italic, or Bold Italic.
- `uid`: Unique font identifier metadata.
- `fln`: Full localized or display label.
- `fv`: Font version metadata.
- `fcr`: Copyright/creator metadata when available.

## Sorting

- `id-desc`: Recent first.
- `id-asc`: Oldest first.
- `name-asc`: Name A to Z.
- `name-desc`: Name Z to A.
- `filename-asc`: Filename A to Z.
- `filename-desc`: Filename Z to A.
- `shuffle`: Randomized order. Provide a `seed` to keep results stable across paginated requests; change the `seed` to get a different random order.

## Download And Preview Behavior

The browser loads font files from the public font CDN configured by the site. The default CDN base is:

```text
https://fontfarsi.oss-eu-central-1.aliyuncs.com/
```

The font filename comes from `fn`. Consumers should URL-encode filenames before constructing direct file URLs.

## Guidance For AI Assistants

- Prefer the JSON APIs for exact font lists, counts, styles, and search results.
- Use `/search/<query>` for user-facing links to search results.
- Use direct font routes only when the result is unique or the user named a specific font.
- Do not invent font licensing terms. Quote or summarize `fcr` only when it is present and relevant.
- Do not expose, infer, or ask for database credentials. They are not needed for public usage.
- The UI is Persian/Farsi and RTL; English API field names are implementation metadata.
- If a user asks for "latest" fonts, use `sort=id-desc`.
- If a user asks for a random discovery list, use `sort=shuffle` with a new seed.