Organizing with Categories
Build the category tree your readers navigate — creating, nesting, reordering, filing articles, and what happens when you delete a category.
On this page
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:
- Groups articles so readers can browse instead of searching.
- Controls customer visibility for everything inside it — see Who can see an article.
- Holds a curated order, so you decide what readers see first rather than the alphabet deciding for you.
Write first, organize second
Resist designing the perfect tree before you have written anything. Write a dozen articles into Uncategorized, then look at what you actually produced and build categories around it. The structure you guess at up front is rarely the structure your content wants.
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:
| Rule | What you will see |
|---|---|
| Maximum 5 levels of nesting | KB categories cannot be nested more than 5 levels deep |
| Sibling names must be unique, ignoring case | A sibling KB category named "Billing" already exists |
| A category cannot move inside its own subtree | Moving 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).
Moving a category can change who can read it
Dragging a category out from under an Internal parent makes its whole subtree customer-visible immediately. Dragging it under an Internal parent hides it. Both are reversible, and neither rewrites anything — but the change takes effect at once, without a confirmation prompt. The move can also shift its articles to a different tab.
Filing articles into categories#
Three ways, all equivalent:
- From the editor — the Category control in the rail's Organization panel.
- Drag the article row from the table onto a category in the tree.
- 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:
| Hint | Fix |
|---|---|
| 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.
Deleting an Internal category never exposes its contents
This is the one case where the audience is not purely derived. If the category you delete was hiding its contents from customers, that restriction would vanish with it — so where it is needed, DevStride writes Internal down on what survives: the articles that become Uncategorized, and the child categories that move up.
Where the restriction is not at risk — a surviving parent is still Internal and still hides them — nothing is written, so those categories keep their own setting and re-opening that parent later brings them back properly.
Either way, nothing that was hidden becomes visible. Anything written down shows in the UI and can be widened again. Deleting a Portal category writes nothing at all.
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#
| Action | Where | Permission |
|---|---|---|
| Create top-level category | + beside Categories | Publish knowledge-base articles |
| Create subcategory | Category ⋯ → New subcategory | Publish knowledge-base articles |
| Rename / re-parent / set audience | Category ⋯ → Edit | Publish knowledge-base articles |
| Open or close a category to client drafts | Category ⋯ → Edit → Clients may submit drafts here | Publish knowledge-base articles |
| Require approval for changes to its published articles | Category ⋯ → Edit → Changes to published articles need approval | Publish knowledge-base articles |
| Watch it, or stop watching | Category ⋯ → Watch category / Stop watching | None beyond reading the category |
| Reorder or move | Drag the grip | Publish knowledge-base articles |
| Delete | Category ⋯ → Delete | Publish knowledge-base articles |
| Choose which members can read, comment on, or edit its articles | Category ⋯ → Share… | Publish knowledge-base articles, or Edit any member's knowledge-base articles |
| File an article | Editor rail → Organization → Category, or drag the row | Edit rights on the article |
| Reorder articles | Drag rows in the table | Publish knowledge-base articles |