#2146: 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 for details on the help center.
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. |
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:
<meta name="robots" content="noindex">
This tag prevents search engines from indexing a specific article, while the article stays available to all users.
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.txtand/llms-full.txtfiles with the list and texts of public articles — see Enabling indexing of the public knowledge base portal for LLM (llms.txt). - The
/robots/sitemap.xmlsitemap and therobots.txtfile — see sitemap.xml and robots.txt for the public knowledge base.
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. - 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.
During content quality checks (AQI), it is also recommended to check that the SEO fields are filled in and correct.