Knowledge Base

Organizing with Categories

Build the category tree your readers navigate — creating, nesting, reordering, filing articles, and what happens when you delete a category.

What categories do

Categories are the navigation your readers use. They appear as a tree down the left of the Library, the Manage surface, and the customer Help center.

If your category names run long, drag the right edge of the category panel on the Library or Manage articles page to make it wider or narrower. Both pages share the width, and your browser remembers it for next time; double-click the edge to put it back to the default.

The Library and Manage articles list only the current tab's categories on each of their three tabs. See The category panel for which tab lists a category.

A category does three jobs:

  1. Groups articles so readers can browse instead of searching.
  2. Controls customer visibility for everything inside it — see Who can see an article.
  3. Holds a curated order, so you decide what readers see first rather than the alphabet deciding for you.

Creating a category

Categories are managed on the Manage articles surface only, and every change requires the Publish knowledge-base articles permission. Members without it see the tree but cannot alter it.

Top-level category: click the + button (titled New category) beside the Categories heading.

Subcategory: open a category's ⋯ menu and choose New subcategory.

A new category starts on the tab you are on: the dialog opens with Audience set to Internal on Internal Articles, and with This category holds specs on under Specifications. Under a parent that already decides the tab (an Internal parent, or one that holds specs), the dialog leaves that setting alone, because the parent carries it for everything beneath it. Change either setting before you save and the category is listed on the tab that matches.

In the dialog:

  • Name — required, 1–120 characters, and must be unique among its siblings. The placeholder suggests e.g. Getting started.
  • Parent category — leave blank for a top-level category. Choosing a parent here is the way to nest an existing category under another one.
  • Audience — Portal (customers) or Internal. See Who can see an article.
  • Clients may submit drafts here — off by default. When on, signed-in customers can write draft specs in this category from the portal, private to their own company until your team publishes them. Each subcategory has its own setting. See Client spec drafts.
  • This category holds specs — off by default. When on, the articles in this category and in all its subcategories are specs: the customer portal lists them on its own Specs page, apart from help articles, and leaves them out of the Help center's list, search and category tree. Who can see each article does not change. Unlike the other two switches, subcategories inherit it. See Specs in the customer portal.
  • Changes to published articles need approval — off by default. When on, editing a published article filed directly in this category saves a proposed change that a publisher must approve before it goes live. Each subcategory has its own setting. See Approval for published changes.

Click Save.

A category's Parent category, Audience and This category holds specs settings help decide which tab lists its articles, so saving can move articles between tabs. The same three settings decide which tab lists the category itself, so it can leave the panel you are looking at; when that happens to the category you had selected, the list goes back to All Articles. The list refreshes when you save.

The rules the server enforces

You will meet these as error messages, so they are worth knowing in advance:

RuleWhat you will see
Maximum 5 levels of nestingKB categories cannot be nested more than 5 levels deep
Sibling names must be unique, ignoring caseA sibling KB category named "Billing" already exists
A category cannot move inside its own subtreeMoving a KB category under itself or one of its descendants would create a cycle

Sibling uniqueness is case-insensitive — Billing and billing collide. It is also per-parent, so the same name under two different parents is fine, which is what you want for a FAQ under each product area.

The depth limit applies to the whole subtree you are moving, not just the category you grabbed. Dragging a three-deep branch under a category that is already at level 3 is rejected, because the leaves would land at level 6.

Nesting, moving, and reordering

Drag the grip on a category row to move it. In a long tree, hold the row near the top or bottom edge: a band lights up there and the tree scrolls straight away, stopping as soon as you drop.

  • Drop on a sibling — reorders within that level.
  • Drop on a different category — re-parents it underneath.
  • Drop on All Articles — moves it back to the top level. This is the only way to un-nest something by dragging, so it is worth remembering.

A category you re-parent lands at the end of its new sibling set rather than keeping its old position number, which would otherwise collide arbitrarily with the existing order there.

You can also re-parent from the dialog by changing Parent category — useful for precise moves, and the only way to nest one existing sibling under another (a same-parent drag always reorders instead).

Filing articles into categories

Three ways, all equivalent:

  1. From the editor — the Category control in the rail's Organization panel.
  2. Drag the article row from the table onto a category in the tree.
  3. Drag it onto Uncategorized to un-file it.

Filing requires edit rights on that article. A published article in a category whose changes need approval cannot be moved out of it; unpublish it first (see Approval for published changes).

Uncategorized

Uncategorized is not a real category — it is the bucket of articles with no category at all. You cannot rename it, delete it, nest anything under it, or give it an audience.

It appears at the bottom of the tree, and on the Library it only appears when the current list actually contains uncategorized articles.

Because it is not a category, it carries no audience clamp. An uncategorized article's own visibility setting is the only thing deciding whether customers see it. That is worth remembering when you un-file something out of an Internal category. The same setting decides whether it is listed under Internal Articles or External Articles; an uncategorized article is never under Specifications.

In the customer Help center, uncategorized articles are grouped under General.

Ordering articles inside a category

Articles have a curated order that readers see, both in your team's Library and on the customer Help center. Drag article rows in the Manage table to set it; in a long list, hold the row on the band at the top or bottom edge and the table scrolls.

Reordering is only available when the list you are looking at is unambiguously one ordered bucket. If it is not, a hint tells you exactly what to change:

HintFix
Select a single category to reorder articles.You are on All Articles — pick one category.
Clear the state filter to reorder articles.Set the state chip back to All.
Clear the search to reorder articles.Empty the search box.
Clear the stage filter to reorder articles.Set the stage filter back to Any stage.
Only articles filed directly in this category can be reordered.The list includes articles from subcategories; those belong to their own buckets.

Archived articles are hidden from the All list and do not get in the way: a drag reorders the active articles you can see, and any archived articles in that category keep their relative order behind them.

Reordering works one tab at a time. In a category that mixes internal and external articles, a drag reorders only the articles on the current tab, and the other tab's articles keep their places.

Dragging downward drops the article after the row you land on; dragging upward drops it before. This is what makes a downward drag actually pass the target rather than swapping with it.

Watching a category

Open a category's ⋯ menu and choose Watch category to be told in the app when any article in it, or in its subcategories, changes stage, gets a new published version, or has a change proposed or decided. A bell on the category shows you are watching it. Anyone who can read the category can watch it, so the menu appears for members who cannot otherwise change the tree. See Watching articles and categories.

Deleting a category

Open the category's ⋯ menu and choose Delete. The confirmation states exactly what will happen:

Delete the category Runbooks? This cannot be undone. Child categories move up one level; its articles become Uncategorized.

That is the whole behaviour, and the important part is what it does not do:

  • No article is ever deleted. Articles filed directly on the category become Uncategorized.
  • No article is ever unpublished. A published article stays published.
  • Child categories survive — they move up to take the deleted category's place in the tree, keeping their own children and articles.
  • Articles in subcategories are untouched. Only articles filed directly on the deleted category move.
  • Its watches go with it. People watching the deleted category stop being notified about its articles; watches on the articles themselves stay.

A delete is never blocked. If re-homing creates two siblings with the same name, DevStride allows it rather than refusing to delete or silently renaming something.

A worked example

Say you are building help content for two products.

Getting started            Portal
Product A                  Portal
  ├─ Setup                 Portal
  ├─ Troubleshooting       Portal
  └─ Internal runbooks     Internal   ← hides everything below it
Product B                  Portal
  ├─ Setup                 Portal
  └─ Troubleshooting       Portal
Company policies           Internal   ← whole section is team-only

What this gives you:

  • Customers browsing the Help center see Getting started, Product A (Setup, Troubleshooting), and Product B. They never see Internal runbooks or Company policies — not in the tree, not in search results.
  • Your team sees the entire tree in the Library, with Internal badges on the two hidden branches — unless you have also shared a branch with only some members.
  • Articles inside Internal runbooks can be left set to Portal (customers) without risk — the category holds them back. If you later move one out into Troubleshooting, it becomes customer-visible with its own setting intact.
  • Marking Product B Internal for a week while you rewrite it hides it completely, and unmarking it restores every article exactly as it was.

Reference

ActionWherePermission
Create top-level category+ beside CategoriesPublish knowledge-base articles
Create subcategoryCategory ⋯ → New subcategoryPublish knowledge-base articles
Rename / re-parent / set audienceCategory ⋯ → EditPublish knowledge-base articles
Open or close a category to client draftsCategory ⋯ → Edit → Clients may submit drafts herePublish knowledge-base articles
Require approval for changes to its published articlesCategory ⋯ → Edit → Changes to published articles need approvalPublish knowledge-base articles
Watch it, or stop watchingCategory ⋯ → Watch category / Stop watchingNone beyond reading the category
Reorder or moveDrag the gripPublish knowledge-base articles
DeleteCategory ⋯ → DeletePublish knowledge-base articles
Choose which members can read, comment on, or edit its articlesCategory ⋯ → Share…Publish knowledge-base articles, or Edit any member's knowledge-base articles
File an articleEditor rail → Organization → Category, or drag the rowEdit rights on the article
Reorder articlesDrag rows in the tablePublish knowledge-base articles