Linking Markdown Documentation to Website Elements

The Result You Need

Write the guide for a human reader first. The technical key should wrap the words a visitor naturally looks for in a step-by-step instruction:

Click the <span data-ai-context-id="checkout.payment.submit">payment button</span>
to continue to order payment.

After upload, Senler AI extracts the key from the text and displays it in the document's Context keys for elements field. A separate ai_context_ids list in frontmatter is not required and does not replace inline markup.

The main principle: the same data-ai-context-id must exist on the page element and in the article text. Then the user reads a normal instruction, while the selected place is linked to the right interface step.

Setup Sequence

The site owner marks a button, field or card with the data-ai-context-id attribute.
The same key is specified in the Markdown document for this function.
The document is uploaded to the knowledge base.
The key is saved as a document context key.
The visitor selects an element in the widget and asks a question.
Senler AI receives the selected element as a chip beside the message. Page or other business-object chips may appear beside it.
Knowledge base search prioritizes documents where the "Context keys for elements" field contains this key.

Write a Human-Friendly Guide

Do not put keys into a separate technical list in the visible text. Wrap exact words such as “token field,” “payment button,” or “notification settings.” Each span must be closed correctly and appear in ordinary article text.

A key must contain at least two non-empty dot-separated parts, such as checkout.payment.submit, start with a letter or digit, and be no more than 120 characters. Use Latin letters, digits, _, and - within parts; lowercase keys are recommended for consistency. Import ignores a value without a dot, with an empty part such as checkout..submit, or with a space.

Put the Same Key on the Site

Set the same data-ai-context-id on the final button, field, or card. Do not use the element label, a translation, or a specific user ID as the key: text and data may change, while the semantic link should remain stable.

Upload the Markdown

Add the prepared .md, .mdc, or .markdown file to the knowledge base. For many documents, upload a ZIP archive that preserves the folder structure. Uploading Files and Archives explains file selection, image-recognition mode, name conflicts, and background-processing progress.

MD/ZIP import for .md, .mdc, and .markdown files reads initial frontmatter and inline data-ai-context-id markup in the article body. Frontmatter must be at the very beginning of the file between matching --- or +++ markers; simple fields and lists are recognized inside it. During import, Senler AI:

separates the initial frontmatter block from visible text;
stores recognized frontmatter properties as file metadata;
extracts correctly closed span data-ai-context-id values from the article body;
adds extracted values to the document context keys.

Markup inside fenced or inline code, indented code, an escaped fragment, or an HTML comment is not treated as a key. This lets an article show examples without creating a false interface link.

Markdown File Example

Frontmatter may hold article properties. The interface link lives directly in the human-readable phrase in the document body.

---
doc_id: "site.checkout.payment"
title: "Order Payment"
keywords:
 - "payment"
 - "card"
 - "order"
search_queries:
 - "how to pay for an order"
 - "why payment fails"
---

In the body of the document, link the phrase to the element:

<span data-ai-context-id="checkout.payment.submit">Click the payment button</span>
to continue to order payment.

Matching Site Markup Example

<form data-ai-area="form" data-ai-section="checkout-payment">
 <button
 data-ai-label="Pay for order"
 data-ai-kind="primary-action"
 data-ai-action="checkout.payment.submit"
 data-ai-context-id="checkout.payment.submit"
 data-ai-kb-query="how to pay for an order"
 >
 Pay
 </button>
</form>

Verify the Document After Upload

Click the Settings gear next to the project name, open Knowledge Base under Project data, then find the uploaded document and open it for editing. Check the Context keys for elements field and make sure the file or its folder is connected to the correct agent with read access.

In the screenshot, 1 marks the open document form, 2 the title, 3 the context keys, 4 the content, and 5 the create or save button. Keys extracted from inline markup appear in field 3 together with keys added manually.

Context-key field in a knowledge-base document

Opening this section and working with the material list are shown in the Knowledge Base guide. After a large ZIP upload, sample several files and always open at least one file that contains a new key.

When kb_query and kb_doc_id Are Needed

data-ai-context-id — the primary option: a stable link between an element and an exact place in the guide.
data-ai-kb-query — a natural-language search fallback when the exact link is not available yet.
data-ai-kb-doc-id — direct ID of the knowledge base document. Use with caution: the document's UUID may change after re-import or in another project.

If the Link Does Not Work

If a selected button does not find the expected instructions after an MD folder upload:

Check which data-ai-context-id is on the button.
Open the corresponding file in the knowledge base.
Check that the same key is inline data-ai-context-id inside the document or is already displayed in the "Context keys for elements" field.
Make sure the span is in ordinary text, closed correctly, and uses a valid key format.
Add data-ai-kb-query to the button as a natural-language search hint.
Make sure the agent is connected to the knowledge-base folder or file with read access.

If the article is intended for public reading, context keys should not interfere with the text. The visible part of the span should remain a human phrase: “Enter the Telegram token”, “Click Connect”, “Open notification settings”.

What to Verify Next

After upload, select the linked element on a test page and follow Element Selection, Highlighting, and Website Actions. A matching knowledge-base key does not by itself mean the element is present and available on the current screen.