SEO для блога на FastAPI без плагинов: что на самом деле делает этот сайт

Опубликовано: 2026-06-05

Большинство руководств по SEO написаны для WordPress или SaaS-платформ, где достаточно поставить плагин и нажать "Сохранить". С собственным приложением на FastAPI это не работает. HTML полностью ваш, поэтому каждый мета-тег, каждый блок структурированных данных и каждую интеграцию с поисковиками приходится подключать руками. В этом посте - вся SEO-обвязка weblog.antonnovikov.com: что сделано, где это лежит в коде и что ломается, если ошибиться.


Задача

Блог работает на weblog.antonnovikov.com: FastAPI и шаблоны Jinja2, посты - Markdown-файлы, которые рендерятся на сервере. Языков два, английский и русский, у каждого своё дерево URL. Цели были простые:

  • Каждый пост попадает в индекс Google и Яндекса в течение нескольких часов после публикации
  • Поисковики правильно связывают языковые версии (без штрафов за дублированный контент)
  • Расширенные сниппеты в выдаче (тип статьи, даты, хлебные крошки)
  • Рабочие фиды для RSS-читалок

Само ничего из этого не появится. Всё нужно сделать руками.


Как это устроено

SEO-обвязка живёт в трёх местах: базовый шаблон Jinja2 (templates/base.html), шаблон поста (templates/blog/index.html) и роутер (app/routers/blog.py). У каждого слоя своя задача.

Мета-теги

Каждая страница получает <meta name="description"> из поля description в index.json. На страницах постов директива robots расширена:

html<meta name="robots" content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1">

max-snippet:-1 разрешает Google брать в сниппет всё описание целиком, без обрезки. max-image-preview:large включает большие превью картинок в Google Discover. Эти директивы нужно указывать явно: без них Google по умолчанию ставит консервативные ограничения.

В гайде по шаблонам длина описания ограничена 160 символами - примерно столько помещается в сниппет десктопной выдачи. Google этого не требует, но длинное описание в выдаче обрежут, так что лишнее писать незачем.

Canonical URL

На каждой странице есть явный <link rel="canonical">:

html<link rel="canonical" href="https://weblog.antonnovikov.com/2026-06-05-seo-fastapi-blog">

Шаблон строит canonical из переменной контекста og_url, а её заполняет _handle_blog_post:

python"og_url": f"{url_prefix}/{slug}",

Здесь url_prefix - это https://weblog.antonnovikov.com или https://weblog.antonnovikov.com/ru, в зависимости от языка. Это минимальный правильный вариант: canonical всегда указывает на основной URL, без параметров трекинга, токенов сессии и альтернативных форм.

Open Graph и Twitter Card

Страницы постов получают полный набор Open Graph для типа article:

html<meta property="og:type"              content="article">
<meta property="og:title"             content="...">
<meta property="og:description"       content="...">
<meta property="og:url"               content="...">
<meta property="og:site_name"         content="weblog.antonnovikov.com">
<meta property="og:locale"            content="ru_RU">
<meta property="og:locale:alternate"  content="en_US">
<meta property="og:image"             content="...">
<meta property="og:image:width"       content="1200">
<meta property="og:image:height"      content="630">
<meta property="og:image:alt"         content="...">
<meta property="article:published_time" content="2026-06-05T00:00:00Z">
<meta property="article:modified_time"  content="...">
<meta property="article:author"       content="https://antonnovikov.com/">
<meta property="article:section"      content="DevOps">

og:locale:alternate редко упоминают в документации, но для двуязычного сайта он важен: так скраперы узнают, что есть версия на другом языке. article:modified_time берётся из mtime файла на диске, а не прописан в коде. Поэтому, когда я правлю файл поста, время изменения обновляется само.

Twitter Card - summary_large_image с временем чтения:

html<meta name="twitter:card"    content="summary_large_image">
<meta name="twitter:label2"  content="Reading time">
<meta name="twitter:data2"   content="5 min">

Пары label/data показываются как дополнительные метаданные в превью ссылок в Twitter/X. Время чтения приходит из контекста шаблона как og_read_time: по умолчанию 5 мин, для отдельного поста его можно задать в index.json полем read_time.

Структурированные данные JSON-LD

Самая многословная часть. Каждая страница поста выводит два блока JSON-LD: BlogPosting и BreadcrumbList.

Схема BlogPosting:

json{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Заголовок поста",
  "description": "Описание поста",
  "url": "https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog",
  "mainEntityOfPage": "https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog",
  "datePublished": "2026-06-05T00:00:00Z",
  "dateModified": "...",
  "author": { "@type": "Person", "name": "Anton Novikov", "url": "https://antonnovikov.com/" },
  "publisher": { "@type": "Person", "name": "Anton Novikov", "url": "https://antonnovikov.com/" },
  "image": { "@type": "ImageObject", "url": "...", "width": 1200, "height": 630 },
  "keywords": "kubernetes, k0s, helm",
  "inLanguage": "ru",
  "isPartOf": { "@type": "Blog", "name": "Anton Novikov — weblog", "url": "https://weblog.antonnovikov.com/ru/" },
  "wordCount": 1240,
  "timeRequired": "PT6M"
}

wordCount считается по сырому Markdown (простой .split()) во время рендера и передаётся в контекст шаблона. timeRequired записан в формате длительности ISO 8601: PT6M значит 6 минут. Google использует wordCount и timeRequired для метаданных расширенных сниппетов, их видно в проверке расширенных результатов в Search Console.

Блок BreadcrumbList даёт хлебные крошки в выдаче:

json{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "weblog", "item": "https://weblog.antonnovikov.com/ru/" },
    { "@type": "ListItem", "position": 2, "name": "Заголовок поста", "item": "https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog" }
  ]
}

Главная страница блога и страницы тегов и серий вместо BlogPosting получают схемы WebSite, Blog и CollectionPage.

hreflang для двуязычного контента

Каждый пост, который есть на обоих языках, получает hreflang-ссылки в <head>:

html<link rel="alternate" hreflang="en" href="https://weblog.antonnovikov.com/2026-06-05-seo-fastapi-blog">
<link rel="alternate" hreflang="ru" href="https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog">
<link rel="alternate" hreflang="x-default" href="https://weblog.antonnovikov.com/2026-06-05-seo-fastapi-blog">

Те же пары есть и в sitemap: Google советует указывать hreflang в обоих местах. Генератор sitemap (generate_sitemap_xml()) ищет посты, которые есть на обоих языках, через пересечение множеств слагов:

pythonen_slugs = {p.get("slug") for p in en_posts}
ru_slugs = {p.get("slug") for p in ru_posts}
both_slugs = en_slugs & ru_slugs

Для двуязычных постов внутрь блока <url> добавляются элементы <xhtml:link>:

xml<url>
  <loc>https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog</loc>
  <lastmod>2026-06-05</lastmod>
  <changefreq>never</changefreq>
  <priority>0.8</priority>
  <xhtml:link rel="alternate" hreflang="en"        href="https://weblog.antonnovikov.com/2026-06-05-seo-fastapi-blog"/>
  <xhtml:link rel="alternate" hreflang="ru"        href="https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog"/>
  <xhtml:link rel="alternate" hreflang="x-default" href="https://weblog.antonnovikov.com/2026-06-05-seo-fastapi-blog"/>
</url>

У постов changefreq=never: опубликованный пост не меняет содержимое, меняются только метаданные. lastmod берётся из поля date в index.json.

Навигация по серии: rel=prev / rel=next

Посты из серии получают ссылки rel=prev и rel=next на соседние посты серии (по дате, от старых к новым):

html<link rel="prev" href="https://weblog.antonnovikov.com/ru/2026-06-03-fastapi-s3-yandex-cloud">

Google перестал использовать эти ссылки для пагинации в 2019 году, но они всё ещё полезны для Яндекса и RSS-читалок, которые понимают последовательную навигацию.

Atom-фид

Фидов Atom 1.0 два: /feed.xml (EN) и /ru/feed.xml (RU). В каждом последние 20 постов с полным HTML:

xml<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Anton Novikov — weblog (ru)</title>
  <link href="https://weblog.antonnovikov.com/ru/"/>
  <entry>
    <id>https://weblog.antonnovikov.com/ru/2026-06-05-seo-fastapi-blog</id>
    <title>SEO для самохостируемого блога на FastAPI</title>
    <updated>2026-06-05T00:00:00Z</updated>
    <summary>...</summary>
    <content type="html">...отрендеренный HTML...</content>
    <category term="seo"/>
  </entry>
</feed>

Полный текст в фиде (а не только описание) удобнее для читалок, и некоторые агрегаторы его индексируют. Фид кэшируется в памяти на 1 час (_FEED_TTL = 3600) через TTLCache.

Ссылка на фид объявлена в <head> каждой страницы:

html<link rel="alternate" type="application/atom+xml"
      title="Anton Novikov — weblog (RU)"
      href="https://weblog.antonnovikov.com/ru/feed.xml">

IndexNow

Когда я публикую новый пост через admin API, приложение отправляет IndexNow-пинг в Bing и Яндекс:

pythonasync def _indexnow_ping(urls: list[str]) -> None:
    payload = {
        "host": "weblog.antonnovikov.com",
        "key": "0c887d6665c1de09334e138e0c31962c",
        "keyLocation": "https://weblog.antonnovikov.com/0c887d6665c1de09334e138e0c31962c.txt",
        "urlList": urls[:10000],
    }
    endpoints = [
        "https://api.indexnow.org/indexnow",
        "https://yandex.com/indexnow",
    ]
    async with httpx.AsyncClient(timeout=10.0) as client:
        for ep in endpoints:
            r = await client.post(ep, json=payload, ...)

Файл для проверки ключа лежит в корне проекта по пути /0c887d6665c1de09334e138e0c31962c.txt и отдаётся как статика. Без него поисковики отклонят запрос: они скачивают этот файл, чтобы убедиться, что сайт ваш. Пинг работает по принципу fire-and-forget: ошибки пишутся в лог как warning и не влияют на ответ API.

Эндпоинт sitemap

Sitemap генерируется на лету по адресу /weblog/sitemap.xml функцией generate_sitemap_xml(): она читает кэши индексов в памяти и собирает полный XML. В нём есть:

  • Статические страницы (antonnovikov.com, cv.antonnovikov.com, weblog.antonnovikov.com)
  • Все EN- и RU-посты с lastmod, changefreq=never, priority=0.8
  • Страницы всех известных тегов с changefreq=weekly, priority=0.5

Для главного домена antonnovikov.com (моей домашней страницы) в корне репозитория лежит отдельный статический sitemap.xml. Это обычный файл, приложение его не генерирует.

robots.txt

textUser-agent: *
Allow: /

Disallow: /weblog/api/
Disallow: /weblog/stats
Disallow: /*.json$
Allow: /weblog/index.json
Allow: /weblog/index-ru.json

User-agent: GPTBot
Disallow: /

User-agent: ChatGPT-User
Disallow: /

AI-краулеры, которые собирают данные для обучения моделей (GPTBot, ChatGPT-User, CCBot, anthropic-ai), заблокированы полностью. API-эндпоинты тоже закрыты: индексировать там нечего, а в выдаче они выглядели бы как странные URL. Файлы index.json снова разрешены после общего запрета *.json$, потому что это публичные индексы постов.


Как это собрано в FastAPI

Весь контекст шаблона для страницы поста собирается в _handle_blog_post():

pythonctx: dict = {
    "og_title":       meta.get("title", slug),
    "og_description": meta.get("description", ""),
    "og_url":         f"{url_prefix}/{slug}",
    "og_date":        meta.get("date", ""),
    "og_modified":    og_modified,      # из mtime файла
    "og_tags":        meta.get("tags", []),
    "og_read_time":   meta.get("read_time", 5),
    "og_word_count":  word_count or 0,  # посчитан из сырого markdown
    "og_slug":        slug,
    "og_image":       meta.get("cover_image", ""),
    "og_body":        body_html,
    "og_series_prev": og_series_prev,
    "og_series_next": og_series_next,
}

Словарь meta берётся из _slug_index_en / _slug_index_ru. Это обычные словари Python, которые перестраиваются из index.json при каждом обновлении кэша индекса (раз в 5 минут). Ни запросов к базе, ни stat по файловой системе на каждый запрос, только поиск по словарю.

og_modified собирается из mtime файла:

pythonmtime = md_path.stat().st_mtime
og_modified = email.utils.formatdate(mtime, usegmt=False)[:16].rstrip()

Получается строка вида "Wed, 05 Jun 2026", она попадает в dateModified в блоке JSON-LD. Это не настоящая дата ISO 8601, но валидатору структурированных данных её хватает.


Что может пойти не так

Нет файла ключа IndexNow. Если задеплоить приложение без 0c887d6665c1de09334e138e0c31962c.txt, каждый IndexNow-пинг будет возвращать 403 Forbidden. В логах появится IndexNow https://api.indexnow.org/indexnow → 403. Проверка:

bashcurl -I https://weblog.antonnovikov.com/0c887d6665c1de09334e138e0c31962c.txt

Ответ должен быть 200 OK. В файле достаточно одной строки с ключом.

hreflang есть в <head>, но нет в sitemap, или наоборот. Google советует держать оба места согласованными. Если пост есть на английском, но нет на русском, hreflang-блоки не выводятся вообще (за это отвечает пересечение both_slugs). Если добавить RU-пост без парного EN, hreflang у него тоже не будет, а в sitemap он появится как отдельный URL. Это правильное поведение, а не баг.

Canonical и слеш в конце URL. Canonical главной страницы блога - https://weblog.antonnovikov.com/ (со слешем). У страниц постов слеша на конце нет. Если их перепутать, в Search Console появятся ошибки soft 404. Шаблон всегда берёт og_url ровно в том виде, в каком его передал роутер. Если роутер соберёт URL неправильно, canonical тоже будет неправильным. Проверка:

bashcurl -sI https://weblog.antonnovikov.com/some-slug | grep canonical

<link rel="canonical"> в HTML ответа должен совпадать с запрошенным URL.


Итого

  • Мета-описание, директивы robots и canonical берутся из метаданных index.json и mtime файла
  • OG-теги типа article и Twitter Card генерируются для каждого поста; главная страница блога получает типы website/blog
  • JSON-LD выдаёт BlogPosting + BreadcrumbList для постов и WebSite + Blog для индексных страниц
  • hreflang проставляется и в <head>, и в sitemap; альтернативы получают только посты, которые есть на обоих языках
  • Atom-фиды содержат полный HTML и кэшируются в памяти на 1 час
  • IndexNow при публикации отправляет пинг в Bing и Яндекс; для этого нужен файл ключа по известному URL
  • robots.txt блокирует AI-краулеры и API-эндпоинты и явно разрешает JSON-индексы постов