Introducing the visual index editor for Discourse Doc Categories

AI-generated summary

saquetim introduces the new visual index editor for the Doc Categories plugin, designed to streamline how document sidebars are managed. This update removes the dependency on maintaining a separate index topic, allowing admins to build and manage their sidebar index directly within the admin UI. The feature is currently available as an experimental upcoming change, which can be enabled at /admin/config/upcoming-changes.

The editor offers three modes for sourcing the index: Editor (building the index in place with sections and links), Index topic (the legacy behavior using a topic’s headings), and Disabled. Existing categories using index topics remain unaffected. When using the new editor, admins can create sections containing links to topics or external URLs, each customizable with icons. The UI provides validation warnings for duplicate links or section titles and highlights topics in the category that are not yet included in the index, allowing for bulk addition.

Key features include:

  • Auto-index: A section that automatically populates with unlinked topics, which can resync on save.
  • Drag-and-drop reordering: Sections and links can be moved via drag handles or keyboard navigation (via tab stops).
  • Batch mode: Supports multi-selection for efficient deletion or moving of multiple rows.

martin confirmed that the initial PR has been merged behind the experimental flag and noted that further refinements are expected before the Alpha release. He later mentioned additional improvements, such as support for three levels of nesting and establishing this as a proper Documentation category type.

Community feedback has been positive. hugh praised the smooth migration process, noting that existing index topics correctly populated the new UI. jainmike highlighted the utility of the in-place editor, stating it resolves issues where headings and sidebars previously drifted apart. They appreciated the visibility of unlinked topics and the balance provided by the auto-index feature, expressing interest in testing it once it exits the experimental stage.

Doc categories can now build their sidebar index directly in the admin UI. The index editor is an upcoming change for the Doc Categories plugin, and it removes the need to maintain a separate index topic.

Two ways to source an index

Editing a category now has a Doc index tab with a mode selector:

  • Editor builds the index in place, as sections holding links.
  • Index topic is the existing behaviour, where a topic’s headings and lists become the index.
  • Disabled turns the sidebar index off for that category.

Categories already pointing at an index topic keep working exactly as they do today.

Building an index

A section holds links, and a link points either at a topic or at any URL you type. Each link can carry its own icon, and the editor warns you when two links resolve to the same place or two sections share a title.

You are also shown when topics in the category do not appear in the index, and you can add these topics in bulk:

An Auto-index section fills itself from the category’s topics, so you can list the pages you care about by hand and let everything else collect in one place. It can resync on each save.

Sections and links reorder by dragging. Every drag handle is also an ordinary tab stop that opens a move menu, so the whole index can be rearranged from the keyboard. A batch mode handles multi-select, for deleting several rows at once or dragging a whole selection together.

Enable it on your site

The index editor is an experimental upcoming change. Enable Doc categories index editor at /admin/config/upcoming-changes. It affects doc categories only, and only what admins see while editing one.

We’d love your feedback

Tell us how it holds up against a real index: whether building one here beats maintaining a topic, what is missing before you would move a category over, and anything that feels rough.

23 likes

The initial PR FEATURE: Add visual doc category index editor - Pull Request #87 - discourse/discourse-doc-categories - GitHub has just been merged behind an experimental upcoming change, the functionality will likely go through further refinements over the next week or two before we move it to Alpha.

3 likes

This is great! Migration is simple - the existing index topic populates the new UI and it all works smoothly. Love this update and very happy with the new UI here :slightly_smiling_face:

5 likes

Thanks Hugh! More improvements are coming, I’ve already merged a change to allow 3 levels deep of nesting and to make this into a proper Documentation category type, so stay tuned.

2 likes

This looks like a useful step forward. Keeping an index in a separate topic always felt fragile, because the headings and the sidebar could drift apart after edits. Being able to build the index in place, and to see which topics are not in the index yet, should make it much easier to keep a doc category tidy. The auto-index section is a good balance too — hand-picked pages at the top, with the rest filled in automatically. I would be interested to try it once it moves past the experimental stage.

1 like