# Configuring article SEO fields (Open Graph, JSON-LD)
Every Swarmica knowledge base article has a set of SEO fields. They help search engines (Google, Yandex), answer engines (AEO) and generative AI services (GEO) such as ChatGPT, Perplexity and YandexGPT understand what the article is about and show it to users.

## Where the SEO fields are

The SEO fields are on the **SEO** tab of the article editor. They are filled in separately for each language of the article.

The data is rendered in the `<head>` of the public knowledge base portal (help center) pages. This works only for published articles with **All** access. See [Configuring the SEO-optimized public knowledge base portal](https://support.swarmica.com/article/en/1040) for details on the help center.

:::tip
The `jsonld` and `html_head` fields are available starting from Swarmica v6.1.0.
:::

## Field reference

| Field | What is rendered on the page | Recommendations |
| --- | --- | --- |
| `seo_title` | `og:title`, `twitter:title`, `share:title` — the title in link previews in social networks and messengers | Up to 70 characters. State the question or problem the article solves. Do not add the site name. |
| `seo_description` | `description`, `og:description`, `twitter:description` | One or two sentences, up to 160 characters: what the article helps to do and for whom. No lists, quotes or Markdown. |
| `seo_url` | `og:url` | The relative address of the article in this language, for example `/article/en/205-creating-and-editing-an-article.html`. |
| `seo_image` | `og:image`, `twitter:image` and `twitter:card` with a large preview | The relative path to an image uploaded to the article, for example `/attachments/...`. |
| `seo_keywords` | `keywords` | 3 to 7 comma-separated words and short phrases a reader would search the article by. |
| `seo_type` | `og:type` | `article` for knowledge base articles. |
| `seo_locale` | `og:locale` | The language in the `language_REGION` format: `ru_RU`, `en_US`. |
| `jsonld` | `<script type="application/ld+json">` | Schema.org markup in JSON-LD format without the `<script>` wrapper. See [Configuring Schema.org markup](https://support.swarmica.com/article/en/2147). |
| `html_head` | Inserted into the page `<head>` as is | For advanced users only, see below. |

If a field is empty, the corresponding tag is not rendered.

## The html_head field

The content of the `html_head` field is inserted into the `<head>` of the article page as is, without validation. Use only tags allowed inside `<head>`: `<meta>`, `<link>`, `<script>`. For example:

```html
<meta name="robots" content="noindex">
```

This tag prevents search engines from indexing a specific article, while the article stays available to all users.

:::caution
An error in the `html_head` markup can break the page layout. After changing the field, open the article in the help center and make sure it is displayed correctly.
:::

## What Swarmica adds automatically

In addition to the SEO fields, the help center automatically publishes data for search engines and LLMs:

*   Every article page contains a `<link rel="alternate" type="text/markdown">` link to the Markdown version of the article, which is convenient for language models to read.
*   The `/llms.txt` and `/llms-full.txt` files with the list and texts of public articles — see [Enabling indexing of the public knowledge base portal for LLM (llms.txt)](https://support.swarmica.com/article/en/1483).
*   The `/robots/sitemap.xml` sitemap and the `robots.txt` file — see [sitemap.xml and robots.txt for the public knowledge base](https://support.swarmica.com/article/en/2149).

## Recommendations for the article text

Search engines and AI services evaluate not only the SEO fields but also the structure of the article itself.

*   **Do not use first-level headings (`#`) in the article text.** The article title is rendered as `<h1>` on the help center page, and a document should contain only one `<h1>` heading. Start the text structure with second-level headings (`##`); nested headings of the third and lower levels (`###`, `####`) are allowed. If your article templates contain first-level headings, replace them with `##` — see [Creating your own article templates](https://support.swarmica.com/article/en/522).
*   **Phrase the article title as a question or problem** — the way a user would phrase it.
*   **Give a direct answer at the start of the solution.** If the article follows the KCS structure, put a short direct answer in the first paragraph of the **Solution** section and give the details below. If there is no such section, give the direct answer in the first paragraph of the article. Answer engines and LLMs more often quote a short answer followed by details.
*   **One article — one problem.** Several unrelated topics in one article make it rank worse.
*   **Structure the text**: numbered steps, tables, code blocks for commands and configurations.
*   **Do not put internal information in the public text.** Use the internal part of the article for employees — it is not shown in the help center and does not get into the SEO fields.

## Automatic filling and quality control

The SEO fields can be filled in automatically by an AI agent — see [Using AI agents for SEO/GEO/AEO optimization of the knowledge base](https://support.swarmica.com/article/en/2148).

During [content quality checks](https://support.swarmica.com/article/en/214) (AQI), it is also recommended to check that the SEO fields are filled in and correct.

## Related articles

*   [Configuring Schema.org markup in articles (JSON-LD, microdata)](https://support.swarmica.com/article/en/2147)
*   [Using AI agents for SEO/GEO/AEO optimization of the knowledge base](https://support.swarmica.com/article/en/2148)
*   [sitemap.xml and robots.txt for the public knowledge base](https://support.swarmica.com/article/en/2149)
*   [Enabling indexing of the public knowledge base portal for LLM (llms.txt)](https://support.swarmica.com/article/en/1483)
*   [Creating and editing an article](https://support.swarmica.com/article/en/205)