AkurAI-Framework / site/content/docs/seo.md

Latest change 68c23789cce8e807c988190dcb1e6a3699cd5ed6 - OLI-156: path-prefix locales, hreflang alternates, sitemap xhtml:link by Ólafur Búi Ólafsson

# SEO

The framework generates the basics search engines and social cards need —
`sitemap.xml`, `robots.txt`, and per-page metadata — from data you already have,
with nothing extra to maintain.

## Site URL

Set an optional `site_url` in `backend/page.json` so generated URLs are
absolute:

```json
{ "site_url": "https://example.com", "title": "…" }
```

Without it, the sitemap falls back to root-relative paths.

## sitemap.xml

`GET /sitemap.xml` returns a valid `<urlset>` built from the **static** routes in
`backend/routes.json`. Routes with a `:param` or `*wildcard` segment are skipped,
because they need data to enumerate. Special characters in URLs are escaped.

## robots.txt

`GET /robots.txt` allows crawling and points at the sitemap:

```text
User-agent: *
Allow: /

Sitemap: https://example.com/sitemap.xml
```

## Per-page metadata

A route in `routes.json` may carry `title` and `description`:

```json
{ "path": "/components", "template": "components",
  "title": "Components — MyApp",
  "description": "Server-rendered UI components." }
```

These are injected into the render context as `meta_title` / `meta_description`,
and the page `<head>` prefers them (with OpenGraph tags), falling back to the
global `title`/`description` from `page.json`. Routes without these fields render
exactly as before — it's fully backward compatible.

## Localised URLs and hreflang

With `"locale_prefix": true` in `routes.json` (see [i18n](/docs/i18n)), `/sitemap.xml` lists every static route once per locale, each `<url>` carrying `xhtml:link rel="alternate"` entries for all locales plus `x-default`. Pages expose the same set as `{{{ hreflang_links }}}` for the `<head>`. Set `site_url` in `page.json` so the URLs are absolute, as hreflang requires.