Tags vs. roles vs. sections

The Knowledge Base has three ways to group articles outside the category tree, and they’re easy to confuse:

• Tags — Cross-cutting labels applied to articles — Filter chips on category pages, listed at the bottom of articles
• Sections — Curated or rule-driven groupings of articles — Headed blocks (“Most popular”, “For developers”) on the public help center
• Roles — Visibility tags that gate browsing — Role switcher on the homepage; selected role filters the entire help center

Pick the one that matches your intent:

• Describing an article → tag.
• Featuring a set of articles together → section.
• Hiding articles from audiences they don’t apply to → role.

Tags

A tag is a label. An article can have many tags. Customers can filter by them.

Use tags for:

• Topical labels — getting-started, troubleshooting, advanced, ai-features, analytics.
• Workflow labels — setup, migration, daily-ops.
• Cross-product labels — email, voice, chat.

Tags don’t affect search ranking on their own. They appear as filter chips on category pages so customers can narrow listings.

Created in Settings → Knowledge → Tags. Applied per article in the editor.

Sections

A section is a display construct. A section contains articles, and the articles can come from any category. Sections are rendered on the public help center via Section Grid, Section List, or Section Bar blocks.

Use sections for:

• Curated topics that span categories — “Returns and refunds” pulling from both Billing and Returns.
• Rule-driven views — “Most popular” (sort by views, limit 10), “Recently updated” (sort by updated date, limit 5), “For developers” (filter by tag = developer).
• Featured collections — “Onboarding essentials” — five articles you want first-time users to see.

A section can be filled manually (you pick the articles) or by rules (the section auto-fills based on category, tag, and sort filters).

Created in Settings → Knowledge → Sections. Rendered by dropping a Section block into the layout.

Roles

A role is a visibility tag. An article tagged with one or more roles is hidden from visitors filtered to other roles. Articles with no role tag are visible to everyone.

Use roles for:

• Multi-audience help centers — separating end-user, admin, and developer content.
• Internal vs. external — articles for resellers or partners that shouldn’t appear next to customer content.
• Audience entry points — letting visitors self-select what they care about, then filtering the whole help center.

Roles do not bias AI retrieval. They’re a public-site browsing affordance.

Created in Settings → Knowledge → Roles. Applied per article in the editor.

Common combinations

• Tag + Section — tag articles with troubleshooting, then create a “Troubleshooting” section that auto-fills from the tag. Customers see the section as a curated block; you maintain it by tagging.
• Role + Section — create a Developer role, tag developer articles with it, then build a “For developers” section filtering by that role’s articles. The section serves visitors who haven’t explicitly switched roles yet.
• Tag + Role — tag an article migration AND tag it with the admin role. Migrations are an admin task; the tag and role together place the article correctly in both navigation systems.

A quick mental model

Tags describe articles. Sections present articles. Roles gate articles.

If you find yourself using a tag to hide articles from end users, you actually want a role. If you find yourself creating a category that just lists articles tagged popular, you actually want a section. If you find yourself adding the same article to multiple categories, you want a section instead.