Create an article

Articles live inside categories. Pick the category first, then create the article — that’s faster than creating an orphan and assigning it later.

1. Open the Knowledge Base

Go to Knowledge in the main navigation. The page has three panes: the category tree on the left, the article list in the middle, and the editor on the right.

If this is the first article you’re writing, the category tree may only have a default category. That’s fine — you can create more categories from the same screen, or follow Organize categories and subcategories first.

2. Pick a category

Click the category in the left pane where this article belongs. The middle pane updates to show the articles already in that category.

3. Click New article

The button sits above the article list. The editor opens with a blank article in draft status.

4. Fill in the basics

• Title — Yes — The headline customers and AI both see. Keep it task-shaped: “Update my payment method” beats “Payment management”.
• Slug — Auto — Generated from the title, and regenerated whenever the title changes — there is no separate slug field. Settle the title before publishing because permalinks bake it in.
• Summary — Recommended — One sentence under 160 characters. Shown in search results, category listings, and previews.
• Body — Yes — The article itself. The editor is rich-text — headings, lists, links, images, code blocks.
• Category — Yes — Already filled from step 2. Change it from the metadata panel if needed. If the warning under the category says no Agent Stack specialist can retrieve an article here, pick a subcategory one of them holds, or give a specialist this category in its knowledge scope.
• Subcategory — Optional — Use only when a category has enough articles to need a second level. A specialist reads it if its knowledge scope holds the whole category or this subcategory; one limited to other subcategories of the category won’t.
• Difficulty — Optional — Beginner, intermediate, or advanced. Filterable in the public site.
• Estimated reading time — Optional — In minutes. Shown on the article page so customers know what they’re getting into.
• Keywords — Optional — Extra search terms that aren’t in the body. The search reads them; readers don’t see them.
• Tags — Optional — Cross-cutting labels for filtering. Add tags through Settings → Knowledge if the one you want doesn’t exist.
• Status — Auto — Starts as draft and stays there until you’re ready to publish. See article statuses.

5. Write the body

Use the rich-text editor. A few rules of thumb:

• Lead with the answer. The first sentence should resolve the question in the title.
• Use headings. They become the table of contents on the article page when Show “On this page” is switched on.
• Link generously. When you mention a related article, link it. The “Related Articles” section at the bottom is where most readers go next.
• Avoid screenshots that go stale. Describe the path in words (“Settings → Knowledge → Markets & Languages”) instead of pasting an image of the menu.

6. Preview

The editor has a Preview button. Use it before publishing — what looks fine in the editor sometimes wraps strangely on the public site.

7. Publish

Change Status from draft to published. The article goes live on the public help center within a few seconds. The embedding pipeline picks it up on its next run, every 10 minutes — once the embedding job finishes, Agent Stack specialists that have its category or subcategory in their knowledge scope can retrieve it (calls can differ — see below).

If you’re not ready to publish but you want the article to be reviewed first, set status to needs-review instead. That keeps it invisible to the public while flagging it for a teammate.

What happens after publishing

• Public site — the article appears in its category, in tag listings, in any sections that match its rules, and in search results.
• AI agents — Capabilities, Sidekick, and Web Chat / voice agents start using it for retrieval. An Agent Stack specialist only retrieves it when its category or subcategory is in the specialist’s knowledge scope; a specialist with no categories in its scope reads them all. On calls, a voice stack with Knowledge base on calls switched on can search the knowledge base even when none of its specialists has knowledge switched on.
• Translations — if you have languages enabled beyond the default, a translation job is queued. See Manage languages.
• Search and AI retrieval — published articles enter the live retrieval pipeline after embedding finishes, so search can use the latest content and AI agents can retrieve it when it falls inside their knowledge scope.

Common gotchas

• The article isn’t showing up in search. Embedding runs every 10 minutes, so it can take that long after publish. Wait, then re-run your search.
• The slug feels wrong. Settle the title before publishing — the slug is regenerated from it. After publish, changing the title changes the slug and breaks any external links.
• The summary is too long. There is no hard cap, but some listings cut a long summary to two or three lines, and the Related Articles list to a single line, so keep it to one short sentence.
• It’s published but customers can’t find it. Check the status (must be published, not needs-review) and that its category is public — articles in a hidden or archived category are left out of public listings. Role assignments don’t hide an article; they only narrow the list when a visitor browses by role.