migrate all docs to the new directives

add a summary option for tools and commands so we can output them with
their tags and keybindings at the top of the file.

docs/builtins/alias.rst

@@ -1,13 +1,13 @@
 alias
 =====
-**Tags:** `tag/system`
-:dfhack-keybind:`alias`
-
-:index:`Configure helper aliases for other DFHack commands.
-<alias; Configure helper aliases for other DFHack commands.>` Aliases are
-resolved immediately after built-in commands, which means that an alias cannot
-override a built-in command, but can override a command implemented by a plugin
-or script.
+
+.. dfhack-tool::
+    :summary: Configure helper aliases for other DFHack commands.
+    :tags: system
+
+Aliases are resolved immediately after built-in commands, which means that an
+alias cannot override a built-in command, but can override a command implemented
+by a plugin or script.
 
 Usage:
 

docs/builtins/cls.rst

@@ -1,8 +1,13 @@
 cls
 ===
-**Tags:** `tag/system`
-:dfhack-keybind:`cls`
 
-:index:`Clear the terminal screen. <cls; Clear the terminal screen.>` Can also
-be invoked as ``clear``. Note that this command does not delete command history.
-It just clears the text on the screen.
+.. dfhack-tool::
+    :summary: Clear the terminal screen.
+    :tags: system
+
+Can also be invoked as ``clear``. Note that this command does not delete command
+history. It just clears the text on the screen.
+
+Usage::
+
+    cls

docs/builtins/devel/dump-rpc.rst

@@ -1,10 +1,11 @@
 devel/dump-rpc
 ==============
-Tags: `tag/system`
-:dfhack-keybind:`devel/dump-rpc`
 
-:index:`Write RPC endpoint information to the specified file.
-<devel/dump-rpc; Writes RPC endpoint information to the specified file.>`
+.. dfhack-tool::
+    :summary: Dump RPC endpoint info.
+    :tags: dev
+
+Write RPC endpoint information to the specified file.
 
 Usage::
 

docs/builtins/die.rst

@@ -1,7 +1,12 @@
 die
 ===
-**Tags:** `tag/system`
-:dfhack-keybind:`die`
 
-:index:`Instantly exit DF without saving.
-<die; Instantly exit DF without saving.>`
+.. dfhack-tool::
+    :summary: Instantly exit DF without saving.
+    :tags: system
+
+Use to exit DF quickly and safely.
+
+Usage::
+
+    die

docs/builtins/disable.rst

@@ -1,11 +1,11 @@
 disable
 =======
-**Tags:** `tag/system`
-:dfhack-keybind:`disable`
 
-:index:`Deactivate a DFHack tool that has some persistent effect.
-<disable; Deactivate a DFHack tool that has some persistent effect.>` See the
-`enable` command for more info.
+.. dfhack-tool::
+    :summary: Deactivate a DFHack tool that has some persistent effect.
+    :tags: system
+
+See the `enable` command for more info.
 
 Usage::
 

docs/builtins/enable.rst

@@ -1,14 +1,14 @@
 enable
 ======
-**Tags:** `tag/system`
-:dfhack-keybind:`enable`
 
-:index:`Activate a DFHack tool that has some persistent effect.
-<enable; Activate a DFHack tool that has some persistent effect.>` Many plugins
-and scripts can be in a distinct enabled or disabled state. Some of them
-activate and deactivate automatically depending on the contents of the world
-raws. Others store their state in world data. However a number of them have to
-be enabled globally, and the init file is the right place to do it.
+.. dfhack-tool::
+    :summary: Activate a DFHack tool that has some persistent effect.
+    :tags: system
+
+Many plugins and scripts can be in a distinct enabled or disabled state. Some
+of them activate and deactivate automatically depending on the contents of the
+world raws. Others store their state in world data. However a number of them
+have to be enabled globally, and the init file is the right place to do it.
 
 Most such plugins or scripts support the built-in ``enable`` and `disable`
 commands. Calling them at any time without arguments prints a list of enabled

docs/builtins/fpause.rst

@@ -1,10 +1,11 @@
 fpause
 ======
-**Tags:** `tag/system`
-:dfhack-keybind:`fpause`
 
-:index:`Forces DF to pause. <fpause; Forces DF to pause.>` This is useful when
-your FPS drops below 1 and you lose control of the game.
+.. dfhack-tool::
+    :summary: Forces DF to pause.
+    :tags: system
+
+This is useful when your FPS drops below 1 and you lose control of the game.
 
 Usage::
 

docs/builtins/help.rst

@@ -1,11 +1,11 @@
 help
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`help`
 
-:index:`Display help about a command or plugin.
-<help; Display help about a command or plugin.>` Can also be invoked as ``?``
-or ``man`` (short for "manual").
+.. dfhack-tool::
+    :summary: Display help about a command or plugin.
+    :tags: system
+
+Can also be invoked as ``?`` or ``man`` (short for "manual").
 
 Usage::
 

docs/builtins/hide.rst

@@ -1,12 +1,12 @@
 hide
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`hide`
 
-:index:`Hide the DFHack terminal window.
-<hide; Hide the DFHack terminal window.>` You can show it again with the `show`
-command, though you'll need to use it from a `keybinding` set beforehand or the
-in-game `command-prompt`.
+.. dfhack-tool::
+    :summary: Hide the DFHack terminal window.
+    :tags: system
+
+You can show it again with the `show` command, though you'll need to use it from
+a `keybinding` set beforehand or the in-game `command-prompt`.
 
 Only available on Windows.
 

docs/builtins/keybinding.rst

@@ -1,12 +1,13 @@
 keybinding
 ==========
-**Tags:** `tag/system`
-:dfhack-keybind:`keybinding`
 
-:index:`Create hotkeys that will run DFHack commands.
-<keybinding; Create hotkeys that will run DFHack commands.>` Like any other
-command, it can be used at any time from the console, but bindings are not
-remembered between runs of the game unless re-created in `dfhack.init`.
+.. dfhack-tool::
+    :summary: Create hotkeys that will run DFHack commands.
+    :tags: system
+
+Like any other command, it can be used at any time from the console, but
+bindings are not remembered between runs of the game unless re-created in
+`dfhack.init`.
 
 Hotkeys can be any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12, or
 ``\``` (the key below the ``Esc`` key.

docs/builtins/kill-lua.rst

@@ -1,11 +1,11 @@
 kill-lua
 ========
-**Tags:** `tag/system`
-:dfhack-keybind:`kill-lua`
 
-:index:`Gracefully stops any currently-running Lua scripts.
-<kill-lua; Gracefully stops any currently-running Lua scripts.>` Use this
-command to stop a misbehaving script that appears to be stuck.
+.. dfhack-tool::
+    :summary: Gracefully stop any currently-running Lua scripts.
+    :tags: system
+
+Use this command to stop a misbehaving script that appears to be stuck.
 
 Usage::
 

docs/builtins/load.rst

@@ -1,11 +1,11 @@
 load
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`load`
 
-:index:`Load and register a plugin library.
-<load; Load and register a plugin library.>` Also see `unload` and `reload` for
-related actions.
+.. dfhack-tool::
+    :summary: Load and register a plugin library.
+    :tags: system
+
+Also see `unload` and `reload` for related actions.
 
 Usage::
 

docs/builtins/ls.rst

@@ -1,9 +1,10 @@
 ls
 ==
-**Tags:** `tag/system`
-:dfhack-keybind:`ls`
 
-:index:`List available DFHack commands. <ls; List available DFHack commands.>`
+.. dfhack-tool::
+    :summary: List available DFHack commands.
+    :tags: system
+
 In order to group related commands, each command is associated with a list of
 tags. You can filter the listed commands by a tag or a substring of the
 command name. Can also be invoked as ``dir``.

docs/builtins/plug.rst

@@ -1,14 +1,13 @@
 plug
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`plug`
 
-:index:`List available plugins and whether they are enabled.
-<plug; List available plugins and whether they are enabled.>`
+.. dfhack-tool::
+    :summary: List available plugins and whether they are enabled.
+    :tags: system
 
-Usage:
+Usage::
 
-``plug``
-    Lists available plugins and whether they are enabled.
-``plug <plugin> [<plugin> ...]``
-    Lists only the named plugins.
+    plug [<plugin> [<plugin> ...]]
+
+If run with parameters, it lists only the named plugins. Otherwise it will list
+all available plugins.

docs/builtins/reload.rst

@@ -1,11 +1,12 @@
 reload
 ======
-**Tags:** `tag/system`
-:dfhack-keybind:`reload`
 
-:index:`Reload a loaded plugin. <reload; Reload a loaded plugin.>` Developers
-use this command to reload a plugin that they are actively modifying. Also see
-`load` and `unload` for related actions.
+.. dfhack-tool::
+    :summary: Reload a loaded plugin.
+    :tags: system
+
+Developers use this command to reload a plugin that they are actively modifying.
+Also see `load` and `unload` for related actions.
 
 Usage::
 

docs/builtins/sc-script.rst

@@ -1,12 +1,12 @@
 sc-script
 =========
-**Tags:** `tag/system`
-:dfhack-keybind:`sc-script`
 
-:index:`Run commands when game state changes occur.
-<sc-script; Run commands when game state changes occur.>` This is similar to
-the static `init-files` but is slightly more flexible since it can be set
-dynamically.
+.. dfhack-tool::
+    :summary: Run commands when game state changes occur.
+    :tags: system
+
+This is similar to the static `init-files` but is slightly more flexible since
+it can be set dynamically.
 
 Usage:
 

docs/builtins/script.rst

@@ -1,12 +1,12 @@
 script
 ======
-**Tags:** `tag/system`
-:dfhack-keybind:`script`
 
-:index:`Execute a batch file of DFHack commands.
-<script; Execute a batch file of DFHack commands.>` It reads a text file and
-runs each line as a DFHack command as if it had been typed in by the user --
-treating the input like `an init file <init-files>`.
+.. dfhack-tool::
+    :summary: Execute a batch file of DFHack commands.
+    :tags: system
+
+It reads a text file and runs each line as a DFHack command as if it had been
+typed in by the user -- treating the input like `an init file <init-files>`.
 
 Some other tools, such as `autobutcher` and `workflow`, export their settings as
 the commands to create them - which can later be reloaded with ``script``.

docs/builtins/show.rst

@@ -1,13 +1,13 @@
 show
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`show`
 
-:index:`Unhides the DFHack terminal window.
-<show; Unhides the DFHack terminal window.>` Useful if you have hidden the
-terminal with `hide` and you want it back. Since the terminal window won't be
-available to run this command, you'll need to use it from a `keybinding` set
-beforehand or the in-game `command-prompt`.
+.. dfhack-tool::
+    :summary: Unhides the DFHack terminal window.
+    :tags: system
+
+Useful if you have hidden the terminal with `hide` and you want it back. Since
+the terminal window won't be available to run this command, you'll need to use
+it from a `keybinding` set beforehand or the in-game `command-prompt`.
 
 Only available on Windows.
 

docs/builtins/tags.rst

@@ -1,11 +1,12 @@
 tags
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`tags`
 
-:index:`List the strings that DFHack tools can be tagged with.
-<tags; List the strings that DFHack tools can be tagged with.>` You can find
-groups of related tools by passing the tag name to the `ls` command.
+.. dfhack-tool::
+    :summary: List the strings that DFHack tools can be tagged with.
+    :tags: system
+
+You can find groups of related tools by passing the tag name to the `ls`
+command.
 
 Usage::
 

docs/builtins/type.rst

@@ -1,12 +1,13 @@
 type
 ====
-**Tags:** `tag/system`
-:dfhack-keybind:`type`
 
-:index:`Describe how a command is implemented.
-<type; Describe how a command is implemented.>` DFHack commands can be provided
-by plugins, scripts, or by the core library itself. The ``type`` command can
-tell you which is the source of a particular command.
+.. dfhack-tool::
+    :summary: Describe how a command is implemented.
+    :tags: system
+
+DFHack commands can be provided by plugins, scripts, or by the core library
+itself. The ``type`` command can tell you which is the source of a particular
+command.
 
 Usage::
 

docs/builtins/unload.rst

@@ -1,9 +1,10 @@
 unload
 ======
-**Tags:** `tag/system`
-:dfhack-keybind:`unload`
 
-:index:`Unload a plugin from memory. <unload; Unload a plugin from memory.>`
+.. dfhack-tool::
+    :summary: Unload a plugin from memory.
+    :tags: system
+
 Also see `load` and `reload` for related actions.
 
 Usage::

docs/plugins/3dveins.rst

@@ -2,13 +2,12 @@
 =======
 
 .. dfhack-tool::
+    :summary: Rewrite layer veins to expand in 3D space.
     :tags: fort mod map
 
-:index:`Rewrite layer veins to expand in 3D space.
-<3dveins; Rewrite layer veins to expand in 3D space.>` Existing, flat veins
-are removed and new 3D veins that naturally span z-levels are generated in
-their place. The transformation preserves the mineral counts reported by
-`prospect`.
+Existing, flat veins are removed and new 3D veins that naturally span z-levels
+are generated in their place. The transformation preserves the mineral counts
+reported by `prospect`.
 
 Usage::
 

docs/plugins/RemoteFortressReader.rst

@@ -1,12 +1,19 @@
 RemoteFortressReader
 ====================
-**Tags:** `tag/dev`
-:dfhack-keybind:`RemoteFortressReader_version`
-:dfhack-keybind:`load-art-image-chunk`
 
-:index:`Backend for Armok Vision.
-<RemoteFortressReader; Backend for Armok Vision.>` Provides an API for realtime
-remote fortress visualization. See :forums:`Armok Vision <146473>`.
+.. dfhack-tool::
+    :summary: Backend for Armok Vision.
+    :tags: dev
+    :no-command:
+
+.. dfhack-command:: RemoteFortressReader_version
+    :summary: Print the loaded RemoteFortressReader version.
+
+.. dfhack-command:: load-art-image-chunk
+    :summary: Gets an art image chunk by index.
+
+This plugin provides an API for realtime remote fortress visualization. See
+:forums:`Armok Vision <146473>`.
 
 Usage:
 

docs/plugins/add-spatter.rst

@@ -1,11 +1,14 @@
 add-spatter
 ===========
-**Tags:** `tag/adventure`, `tag/fort`, `tag/mod`, `tag/items`
 
-:index:`Make tagged reactions produce contaminants.
-<add-spatter; Make tagged reactions produce contaminants.>` Give some use to all
-those poisons that can be bought from caravans! The plugin automatically enables
-itself when you load a world with reactions that include names starting with
-``SPATTER_ADD_``. These reactions will then produce contaminants on items
-instead of improvements. The contaminants are immune to being washed away by
-water or destroyed by `clean`.
+.. dfhack-tool::
+    :summary: Make tagged reactions produce contaminants.
+    :tags: adventure fort mod items
+    :no-command:
+
+Give some use to all those poisons that can be bought from caravans! The plugin
+automatically enables itself when you load a world with reactions that include
+names starting with ``SPATTER_ADD_``, so there are no commands to run to use it.
+These reactions will then produce contaminants on items instead of improvements.
+The contaminants are immune to being washed away by water or destroyed by
+`clean`.

docs/plugins/autobutcher.rst

@@ -1,12 +1,13 @@
 autobutcher
 ===========
-**Tags:** `tag/fort`, `tag/auto`, `tag/fps`, `tag/animals`
-:dfhack-keybind:`autobutcher`
 
-Automatically butcher excess livestock. This plugin monitors how many pets you
-have of each gender and age and assigns excess lifestock for slaughter. Requires
-that you add the target race(s) to a watch list. Units will be ignored if they
-are:
+.. dfhack-tool::
+    :summary: Automatically butcher excess livestock.
+    :tags: fort auto fps animals
+
+This plugin monitors how many pets you have of each gender and age and assigns
+excess lifestock for slaughter. It requires that you add the target race(s) to a
+watch list. Units will be ignored if they are:
 
 * Untamed
 * Nicknamed (for custom protection; you can use the `rename` ``unit`` tool

docs/plugins/autochop.rst

@@ -1,10 +1,12 @@
 autochop
 ========
-**Tags:** `tag/fort`, `tag/auto`
 
-:index:`Auto-harvest trees when low on stockpiled logs.
-<autochop; Auto-harvest trees when low on stockpiled logs.>` This plugin can
-designate trees for chopping when your stocks are low on logs.
+.. dfhack-tool::
+    :summary: Auto-harvest trees when low on stockpiled logs.
+    :tags: fort auto
+    :no-command:
+
+This plugin can designate trees for chopping when your stocks are low on logs.
 
 Usage::
 

docs/plugins/autoclothing.rst

@@ -1,11 +1,12 @@
 autoclothing
 ============
-**Tags:** `tag/fort`, `tag/auto`, `tag/jobs`
-:dfhack-keybind:`autoclothing`
 
-:index:`Automatically manage clothing work orders.
-<autoclothing; Automatically manage clothing work orders.>` It allows you to
-set how many of each clothing type every citizen should have.
+.. dfhack-tool::
+    :summary: Automatically manage clothing work orders.
+    :tags: fort auto jobs
+
+This command allows you to set how many of each clothing type every citizen
+should have.
 
 Usage::
 

docs/plugins/autodump.rst

@@ -2,15 +2,20 @@ autodump
 ========
 
 .. dfhack-tool::
+    :summary: Automatically set items in a stockpile to be dumped.
     :tags: fort auto fps items stockpiles
+    :no-command:
+
+.. dfhack-command:: autodump
+    :summary: Teleports items marked for dumping to the cursor position.
 
 .. dfhack-command:: autodump-destroy-here
+    :summary: Destroy items marked for dumping under the cursor.
 
 .. dfhack-command:: autodump-destroy-item
+    :summary: Destroys the selected item.
 
-:index:`Automatically set items in a stockpile to be dumped.
-<autodump (plugin); Automatically set items in a stockpile to be dumped.>` When
-`enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
 stockpiles. When the ``autodump`` option is selected for the stockpile, any
 items placed in the stockpile will automatically be designated to be dumped.
 
@@ -44,8 +49,7 @@ Options
     called again with this option before the game is resumed, it cancels
     pending destroy actions.
 ``destroy-here``
-    :index:`Destroy items marked for dumping under the cursor.
-    <autodump-destroy-here; Destroy items marked for dumping under the cursor.>`
+    Destroy items marked for dumping under the cursor.
 ``visible``
     Only process items that are not hidden.
 ``hidden``
@@ -57,10 +61,8 @@ Examples
 --------
 
 ``autodump``
-    :index:`Teleports items marked for dumping to the cursor position.
-    <autodump; Teleports items marked for dumping to the cursor position.>`
+    Teleports items marked for dumping to the cursor position.
 ``autodump destroy``
     Destroys all unforbidden items marked for dumping
 ``autodump-destroy-item``
-    :index:`Destroys the selected item.
-    <autodump-destroy-item; Destroys the selected item.>`
+    Destroys the selected item.

docs/plugins/autofarm.rst

@@ -1,13 +1,13 @@
 autofarm
 ========
-**Tags:** `tag/fort`, `tag/auto`, `tag/buildings`
-:dfhack-keybind:`autofarm`
-
-:index:`Automatically manage farm crop selection.
-<autofarm; Automatically manage farm crop selection.>` This plugin periodically
-scans your plant stocks and assigns crops to your farm plots based on which
-plant stocks are low (as long as you have the appropriate seeds). The target
-threshold for each crop type is configurable.
+
+.. dfhack-tool::
+    :summary: Automatically manage farm crop selection.
+    :tags: fort auto buildings
+
+Periodically scan your plant stocks and assign crops to your farm plots based on
+which plant stocks are low (as long as you have the appropriate seeds). The
+target threshold for each crop type is configurable.
 
 Usage:
 

docs/plugins/autogems.rst

@@ -1,15 +1,16 @@
 autogems
 ========
 
-.. dfhack-tool:: autogems
+.. dfhack-tool::
+    :summary: Automatically cut rough gems.
     :tags: fort auto jobs
     :no-command:
 
 .. dfhack-command:: autogems-reload
+    :summary: Reloads the autogems configuration file.
 
-:index:`Automatically cut rough gems. <autogems; Automatically cut rough gems.>`
-This plugin periodically scans your stocks of rough gems and creates manager
-orders for cutting them at a Jeweler's Workshop.
+Automatically cut rough gems. This plugin periodically scans your stocks of
+rough gems and creates manager orders for cutting them at a Jeweler's Workshop.
 
 Usage:
 
@@ -17,10 +18,8 @@ Usage:
     Enables the plugin and starts autocutting gems according to its
     configuration.
 ``autogems-reload``
-    :index:`Reloads the autogems configuration file.
-    <autogems-reload; Reloads the autogems configuration file.>` You might need
-    to do this if you have manually modified the contents while the game is
-    running.
+    Reloads the autogems configuration file. You might need to do this if you
+    have manually modified the contents while the game is running.
 
 Run `gui/autogems` for a configuration UI, or access the ``Auto Cut Gems``
 option from the Current Workshop Orders screen (:kbd:`o`-:kbd:`W`).

docs/plugins/autohauler.rst

@@ -1,13 +1,14 @@
 autohauler
 ==========
-**Tags:** `tag/fort`, `tag/auto`, `tag/labors`
-:dfhack-keybind:`autohauler`
-
-:index:`Automatically manage hauling labors.
-<autohauler; Automatically manage hauling labors.>` Similar to `autolabor`, but
-instead of managing all labors, ``autohauler`` only addresses hauling labors,
-leaving the assignment of skilled labors entirely up to you. You can use the
-in-game `manipulator` UI or an external tool like Dwarf Therapist to do so.
+
+.. dfhack-tool::
+    :summary: Automatically manage hauling labors.
+    :tags: fort auto labors
+
+Similar to `autolabor`, but instead of managing all labors, ``autohauler`` only
+addresses hauling labors, leaving the assignment of skilled labors entirely up
+to you. You can use the in-game `manipulator` UI or an external tool like Dwarf
+Therapist to do so.
 
 Idle dwarves who are not on active military duty will be assigned the hauling
 labors; everyone else (including those currently hauling) will have the hauling

docs/plugins/autolabor.rst

@@ -1,12 +1,12 @@
 autolabor
 =========
-**Tags:** `tag/fort`, `tag/auto`, `tag/labors`
-:dfhack-keybind:`autolabor`
 
-:index:`Automatically manage dwarf labors.
-<autolabor; Automatically manage dwarf labors.>` Autolabor attempts to keep as
-many dwarves as possible busy while allowing dwarves to specialize in specific
-skills.
+.. dfhack-tool::
+    :summary: Automatically manage dwarf labors.
+    :tags: fort auto labors
+
+Autolabor attempts to keep as many dwarves as possible busy while allowing
+dwarves to specialize in specific skills.
 
 Autolabor frequently checks how many jobs of each type are available and sets
 labors proportionally in order to get them all done quickly. Labors with

docs/plugins/automaterial.rst

@@ -1,11 +1,14 @@
 automaterial
 ============
-**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/buildings`, `tag/map`
 
-:index:`Sorts building materials by recent usage.
-<automaterial; Sorts building materials by recent usage.>` This makes building
-constructions (walls, floors, fortifications, etc) much easier by saving you
-from having to trawl through long lists of materials each time you place one.
+.. dfhack-tool::
+    :summary: Sorts building materials by recent usage.
+    :tags: fort productivity design buildings map
+    :no-command:
+
+This plugin makes building constructions (walls, floors, fortifications, etc)
+much easier by saving you from having to trawl through long lists of materials
+each time you place one.
 
 It moves the last used material for a given construction type to the top of the
 list, if there are any left. So if you build a wall with chalk blocks, the next

docs/plugins/automelt.rst

@@ -2,14 +2,13 @@ automelt
 ========
 
 .. dfhack-tool::
+    :summary: Quickly designate items to be melted.
     :tags: fort auto items stockpiles
     :no-command:
 
-:index:`Quickly designate items to be melted.
-<automelt; Quickly designate items to be melted.>` When `enabled <enable>`, this
-plugin adds an option to the :kbd:`q` menu for stockpiles. When the ``automelt``
-option is selected for the stockpile, any items placed in the stockpile will
-automatically be designated to be melted.
+When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+stockpiles. When the ``automelt`` option is selected for the stockpile, any
+items placed in the stockpile will automatically be designated to be melted.
 
 Usage::
 

docs/plugins/autonestbox.rst

@@ -1,16 +1,21 @@
 autonestbox
 ===========
-**Tags:** `tag/fort`, `tag/auto`, `tag/animals`
-:dfhack-keybind:`autonestbox`
 
-Auto-assign egg-laying female pets to nestbox zones. Requires that you create
-pen/pasture zones above nestboxes. If the pen is bigger than 1x1, the nestbox
-must be in the top left corner. Only 1 unit will be assigned per pen, regardless
-of the size. The age of the units is currently not checked since most birds grow
-up quite fast. Egg layers who are also grazers will be ignored, since confining
-them to a 1x1 pasture is not a good idea. Only tame and domesticated own units
-are processed since pasturing half-trained wild egg layers could destroy your
-neat nestbox zones when they revert to wild.
+.. dfhack-tool::
+    :summary: Auto-assign egg-laying female pets to nestbox zones.
+    :tags: fort auto animals
+
+To use this feature, you must create pen/pasture zones above nestboxes. If the
+pen is bigger than 1x1, the nestbox must be in the top left corner. Only 1 unit
+will be assigned per pen, regardless of the size. Egg layers who are also
+grazers will be ignored, since confining them to a 1x1 pasture is not a good
+idea. Only tame and domesticated own units are processed since pasturing
+half-trained wild egg layers could destroy your neat nestbox zones when they
+revert to wild.
+
+Note that the age of the units is not checked, so you might get some egg-laying
+kids assigned to the nestbox zones. Most birds grow up quite fast, though, so
+they should be adults and laying eggs soon enough.
 
 Usage:
 

docs/plugins/autotrade.rst

@@ -1,12 +1,14 @@
 autotrade
 =========
-**Tags:** `tag/fort`, `tag/auto`, `tag/items`, `tag/stockpiles`
 
-:index:`Quickly designate items to be traded.
-<autotrade; Quickly designate items to be traded.>` When `enabled <enable>`,
-this plugin adds an option to the :kbd:`q` menu for stockpiles. When the
-``autotrade`` option is selected for the stockpile, any items placed in the
-stockpile will automatically be designated to be traded.
+.. dfhack-tool::
+    :summary: Quickly designate items to be traded.
+    :tags: fort auto items stockpiles
+    :no-command:
+
+When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+stockpiles. When the ``autotrade`` option is selected for the stockpile, any
+items placed in the stockpile will automatically be designated to be traded.
 
 Usage::
 

docs/plugins/blueprint.rst

@@ -1,12 +1,13 @@
 blueprint
 =========
-**Tags:** `tag/fort`, `tag/design`, `tag/quickfort`, `tag/map`
-:dfhack-keybind:`blueprint`
 
-:index:`Record a live game map in a quickfort blueprint.
-<blueprint; Record a live game map in a quickfort blueprint.>` With
-``blueprint``, you can export the structure of a portion of your fortress in a
-blueprint file that you (or anyone else) can later play back with `quickfort`.
+.. dfhack-tool::
+    :summary: Record a live game map in a quickfort blueprint.
+    :tags: fort design quickfort map
+
+With ``blueprint``, you can export the structure of a portion of your fortress
+in a blueprint file that you (or anyone else) can later play back with
+`quickfort`.
 
 Blueprints are ``.csv`` or ``.xlsx`` files created in the ``blueprints``
 subdirectory of your DF folder. The map area to turn into a blueprint is either

docs/plugins/building-hacks.rst

@@ -1,7 +1,9 @@
 building-hacks
 ==============
-**Tags:** `tag/fort`, `tag/mod`, `tag/buildings`
 
-Provides a Lua API for creating powered workshops.
+.. dfhack-tool::
+    :summary: Provides a Lua API for creating powered workshops.
+    :tags: fort mod buildings
+    :no-command:
 
 See `building-hacks-api` for more details.

docs/plugins/buildingplan.rst

@@ -1,11 +1,11 @@
 buildingplan
 ============
-**Tags:** `tag/fort`, `tag/design`, `tag/quickfort`, `tag/buildings`, `tag/map`
-:dfhack-keybind:`buildingplan`
 
-:index:`Plan building construction before you have materials.
-<buildingplan; Plan building construction before you have materials.>` This
-plugin adds a planning mode for building placement. You can then place
+.. dfhack-tool::
+    :summary: Plan building construction before you have materials.
+    :tags: fort design quickfort buildings map
+
+This plugin adds a planning mode for building placement. You can then place
 furniture, constructions, and other buildings before the required materials are
 available, and they will be created in a suspended state. Buildingplan will
 periodically scan for appropriate items, and the jobs will be unsuspended when

docs/plugins/burrows.rst

@@ -1,24 +1,23 @@
 burrows
 =======
-**Tags:** `tag/fort`, `tag/auto`, `tag/productivity`, `tag/units`
-:dfhack-keybind:`burrow`
 
-:index:`Auto-expand burrows as you dig.
-<burrows (plugin); Auto-expand burrows as you dig.>` When a wall inside a burrow
-with a name ending in ``+`` is dug out, the burrow will be extended to
-newly-revealed adjacent walls. Note that digging 1-wide corridors with the miner
-inside the burrow is **SLOW**.
+.. dfhack-tool::
+    :summary: Auto-expand burrows as you dig.
+    :tags: fort auto productivity units
+    :no-command:
 
-You can also use the ``burrow`` command to
-:index:`quickly add units/tiles to burrows.
-<burrow; Quickly add units/tiles to burrows.>`
+.. dfhack-command:: burrow
+    :summary: Quickly add units/tiles to burrows.
+
+When a wall inside a burrow with a name ending in ``+`` is dug out, the burrow
+will be extended to newly-revealed adjacent walls.
 
 Usage:
 
 ``burrow enable auto-grow``
     When a wall inside a burrow with a name ending in '+' is dug out, the burrow
     will be extended to newly-revealed adjacent walls. This final '+' may be
-    omitted in burrow name args of other ``burrows`` commands. Note that digging
+    omitted in burrow name args of other ``burrow`` commands. Note that digging
     1-wide corridors with the miner inside the burrow is SLOW.
 ``burrow disable auto-grow``
     Disables auto-grow processing.

docs/plugins/changeitem.rst

@@ -1,15 +1,15 @@
 changeitem
 ==========
-**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/items`
-:dfhack-keybind:`changeitem`
-
-:index:`Change item material and base quality.
-<changeitem; Change item material and base quality.>` By default, a change is
-only allowed if the existing and desired item materials are of the same subtype
-(for example wood -> wood, stone -> stone, etc). But since some transformations
-work pretty well and may be desired you can override this with ``force``. Note
-that forced changes can possibly result in items that crafters and haulers
-refuse to touch.
+
+.. dfhack-tool::
+    :summary: Change item material or base quality.
+    :tags: adventure fort armok items
+
+By default, a change is only allowed if the existing and desired item materials
+are of the same subtype (for example wood -> wood, stone -> stone, etc). But
+since some transformations work pretty well and may be desired you can override
+this with ``force``. Note that forced changes can possibly result in items that
+crafters and haulers refuse to touch.
 
 Usage:
 

docs/plugins/changelayer.rst

@@ -1,13 +1,14 @@
 changelayer
 ===========
-**Tags:** `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`changelayer`
 
-:index:`Change the material of an entire geology layer.
-<changelayer; Change the material of an entire geology layer.>` Note that one
-layer can stretch across many z-levels, and changes to the geology layer will
-affect all surrounding regions, not just your embark! Mineral veins and gem
-clusters will not be affected. Use `changevein` if you want to modify those.
+.. dfhack-tool::
+    :summary: Change the material of an entire geology layer.
+    :tags: fort armok map
+
+Note that one layer can stretch across many z-levels, and changes to the geology
+layer will affect all surrounding regions, not just your embark! Mineral veins
+and gem clusters will not be affected. Use `changevein` if you want to modify
+those.
 
 tl;dr: You will end up with changing large areas in one go, especially if you
 use it in lower z levels. Use this command with care!

docs/plugins/changevein.rst

@@ -1,13 +1,13 @@
 changevein
 ==========
-**Tags:** `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`changevein`
 
-:index:`Change the material of a mineral inclusion.
-<changevein; Change the material of a mineral inclusion.>` You can change it to
-any incorganic material RAW id. Note that this command only affects tiles within
-the current 16x16 block - for large veins and clusters, you will need to use
-this command multiple times.
+.. dfhack-tool::
+    :summary: Change the material of a mineral inclusion.
+    :tags: fort armok map
+
+You can change a vein to any incorganic material RAW id. Note that this command
+only affects tiles within the current 16x16 block - for large veins and
+clusters, you will need to use this command multiple times.
 
 You can use the `probe` command to discover the material RAW ids for existing
 veins that you want to duplicate.

docs/plugins/cleanconst.rst

@@ -1,13 +1,14 @@
 cleanconst
 ==========
-**Tags:** `tag/fort`, `tag/fps`, `tag/map`
-:dfhack-keybind:`cleanconst`
-
-:index:`Cleans up construction materials.
-<cleanconst; Cleans up construction materials.>` This tool alters all
-constructions on the map so that they spawn their building component when they
-are disassembled, allowing their actual build items to be safely deleted. This
-can improve FPS when you have many constructions on the map.
+
+.. dfhack-tool::
+    :summary: Cleans up construction materials.
+    :tags: fort fps map
+
+This tool alters all constructions on the map so that they spawn their building
+component when they are disassembled, allowing their actual build items to be
+safely deleted. This can improve FPS when you have many constructions on the
+map.
 
 Usage::
 

docs/plugins/cleaners.rst

@@ -3,15 +3,22 @@
 
 cleaners
 ========
-**Tags:** `tag/adventure`, `tag/fort`, `tag/fps`, `tag/items`, `tag/map`, `tag/units`
-:dfhack-keybind:`clean`
-:dfhack-keybind:`spotclean`
 
-:index:`Removes contaminants.  <clean; Removes contaminants.>` More
-specifically, it cleans all the splatter that get scattered all over the map and
-that clings to your items and units. In an old fortress, cleaning with this tool
-can significantly reduce FPS lag. It can also spoil your !!FUN!!, so think
-before you use it.
+.. dfhack-tool::
+    :summary: Provides commands for cleaning spatter from the map.
+    :tags: adventure fort fps items map units
+    :no-command:
+
+.. dfhack-command:: clean
+    :summary: Removes contaminants.
+
+.. dfhack-command:: spotclean
+    :summary: Remove all contaminants from the tile under the cursor.
+
+This plugin provides commands that clean the splatter that get scattered all
+over the map and that clings to your items and units. In an old fortress,
+cleaning with this tool can significantly reduce FPS lag! It can also spoil your
+!!FUN!!, so think before you use it.
 
 Usage::
 
@@ -21,11 +28,10 @@ Usage::
 By default, cleaning the map leaves mud and snow alone. Note that cleaning units
 includes hostiles, and that cleaning items removes poisons from weapons.
 
-``spotclean`` works like ``clean map snow mud``,
-:index:`removing all contaminants from the tile under the cursor.
-<clean; Remove all contaminants from the tile under the cursor.>` This is ideal
-if you just want to clean a specific tile but don't want the `clean` command to
-remove all the glorious blood from your entranceway.
+``spotclean`` works like ``clean map snow mud``, removing all contaminants from
+the tile under the cursor. This is ideal if you just want to clean a specific
+tile but don't want the `clean` command to remove all the glorious blood from
+your entranceway.
 
 Examples
 --------

docs/plugins/cleanowned.rst

@@ -1,13 +1,14 @@
 cleanowned
 ==========
-**Tags:** `tag/fort`, `tag/productivity`, `tag/items`
-:dfhack-keybind:`cleanowned`
-
-:index:`Confiscates and dumps garbage owned by dwarves.
-<cleanowned; Confiscates and dumps garbage owned by dwarves.>` This tool gets
-dwarves to give up ownership of scattered items and items with heavy wear and
-then marks those items for dumping. Now you can finally get your dwarves to give
-up their rotten food and tattered loincloths and go get new ones!
+
+.. dfhack-tool::
+    :summary: Confiscates and dumps garbage owned by dwarves.
+    :tags: fort productivity items
+
+This tool gets dwarves to give up ownership of scattered items and items with
+heavy wear and then marks those items for dumping. Now you can finally get your
+dwarves to give up their rotten food and tattered loincloths and go get new
+ones!
 
 Usage::
 

docs/plugins/command-prompt.rst

@@ -1,10 +1,9 @@
 command-prompt
 ==============
-**Tags:** `tag/system`
-:dfhack-keybind:`command-prompt`
 
-:index:`An in-game DFHack terminal where you can enter other commands.
-<command-prompt; An in-game DFHack terminal where you can enter other commands.>`
+.. dfhack-tool::
+    :summary: An in-game DFHack terminal where you can run other commands.
+    :tags: system
 
 Usage::
 

docs/plugins/confirm.rst

@@ -1,12 +1,12 @@
 confirm
 =======
-**Tags:** `tag/fort`, `tag/interface`
-:dfhack-keybind:`confirm`
 
-:index:`Adds confirmation dialogs for destructive actions.
-<confirm; Adds confirmation dialogs for destructive actions.>` Now you can get
-the chance to avoid seizing goods from traders or deleting a hauling route in
-case you hit the key accidentally.
+.. dfhack-tool::
+    :summary: Adds confirmation dialogs for destructive actions.
+    :tags: fort interface
+
+Now you can get the chance to avoid seizing goods from traders or deleting a
+hauling route in case you hit the key accidentally.
 
 Usage:
 

docs/plugins/createitem.rst

@@ -1,12 +1,13 @@
 createitem
 ==========
-**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/items`
-:dfhack-keybind:`createitem`
 
-:index:`Create arbitrary items. <createitem; Create arbitrary items.>` You can
-create new items of any type and made of any material. A unit must be selected
-in-game to use this command. By default, items created are spawned at the feet
-of the selected unit.
+.. dfhack-tool::
+    :summary: Create arbitrary items.
+    :tags: adventure fort armok items
+
+You can create new items of any type and made of any material. A unit must be
+selected in-game to use this command. By default, items created are spawned at
+the feet of the selected unit.
 
 Specify the item and material information as you would indicate them in custom
 reaction raws, with the following differences:

docs/plugins/cursecheck.rst

@@ -1,9 +1,10 @@
 cursecheck
 ==========
-**Tags:** `tag/system`, `tag/interface`
-:dfhack-keybind:`cursecheck`
 
-:index:`Check for cursed creatures. <cursecheck; Check for cursed creatures.>`
+.. dfhack-tool::
+    :summary: Check for cursed creatures.
+    :tags: system interface
+
 This command checks a single map tile (or the whole map/world) for cursed
 creatures (ghosts, vampires, necromancers, werebeasts, zombies, etc.).
 

docs/plugins/cxxrandom.rst

@@ -1,7 +1,9 @@
 cxxrandom
 =========
-**Tags:** `tag/dev`
 
-Provides a Lua API for random distributions.
+.. dfhack-tool::
+    :summary: Provides a Lua API for random distributions.
+    :tags: dev
+    :no-command:
 
 See `cxxrandom-api` for details.

docs/plugins/debug.rst

@@ -1,11 +1,15 @@
 debug
 =====
-**Tags:** `tag/dev`
-:dfhack-keybind:`debugfilter`
 
-:index:`Configure verbosity of DFHack debug output.
-<debugfilter; Configure verbosity of DFHack debug output.>` Debug output is
-grouped by plugin name, category name, and verbosity level.
+.. dfhack-tool::
+    :summary: Provides commands for controlling debug log verbosity.
+    :tags: dev
+    :no-command:
+
+.. dfhack-command:: debugfilter
+    :summary: Configure verbosity of DFHack debug output.
+
+Debug output is grouped by plugin name, category name, and verbosity level.
 
 The verbosity levels are:
 

docs/plugins/deramp.rst

@@ -1,11 +1,11 @@
 deramp
 ======
-**Tags:** `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`deramp`
 
-:index:`Removes all ramps designated for removal from the map.
-<deramp; Removes all ramps designated for removal from the map.>` It also
-removes any "floating" down ramps that can remain after a cave-in.
+.. dfhack-tool::
+    :summary: Removes all ramps designated for removal from the map.
+    :tags: fort armok map
+
+It also removes any "floating" down ramps that can remain after a cave-in.
 
 Usage::
 

docs/plugins/dig-now.rst

@@ -1,14 +1,14 @@
 dig-now
 =======
-**Tags:** `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`dig-now`
 
-:index:`Instantly complete dig designations.
-<dig-now; Instantly complete dig designations.>` This tool will magically
-complete non-marker dig designations, modifying tile shapes and creating
-boulders, ores, and gems as if a miner were doing the mining or engraving. By
-default, the entire map is processed and boulder generation follows standard
-game rules, but the behavior is configurable.
+.. dfhack-tool::
+    :summary: Instantly complete dig designations.
+    :tags: fort armok map
+
+This tool will magically complete non-marker dig designations, modifying tile
+shapes and creating boulders, ores, and gems as if a miner were doing the mining
+or engraving. By default, the entire map is processed and boulder generation
+follows standard game rules, but the behavior is configurable.
 
 Note that no units will get mining or engraving experience for the dug/engraved
 tiles.

docs/plugins/dig.rst

@@ -3,47 +3,58 @@
 
 dig
 ===
-**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/map`
-:dfhack-keybind:`digv`
-:dfhack-keybind:`digvx`
-:dfhack-keybind:`digl`
-:dfhack-keybind:`diglx`
-:dfhack-keybind:`digcircle`
-:dfhack-keybind:`digtype`
-:dfhack-keybind:`digexp`
 
-Make complicated dig patterns easy.
+.. dfhack-tool::
+    :summary: Provides commands for designating tiles for digging.
+    :tags: fort productivity design map
+    :no-command:
+
+.. dfhack-command:: digv
+    :summary: Designate all of the selected vein for digging.
+
+.. dfhack-command:: digvx
+    :summary: Dig a vein across z-levels, digging stairs as needed.
+
+.. dfhack-command:: digl
+    :summary: Dig all of the selected layer stone.
+
+.. dfhack-command:: diglx
+    :summary: Dig layer stone across z-levels, digging stairs as needed.
+
+.. dfhack-command:: digcircle
+    :summary: Designate circles.
+
+.. dfhack-command:: digtype
+    :summary: Designate all vein tiles of the selected type.
+
+.. dfhack-command:: digexp
+    :summary: Designate dig patterns for exploratory mining.
+
+This plugin provides commands to make complicated dig patterns easy.
 
 Usage:
 
 ``digv [x] [-p<number>]``
-    :index:`Designate all of the selected vein for digging.
-    <digv; Designate all of the selected vein for digging.>`
+    Designate all of the selected vein for digging.
 ``digvx [-p<number>]``
-    :index:`Dig a vein across z-levels, digging stairs as needed.
-    <digvx; Dig a vein across z-levels, digging stairs as needed.>`
-    This is an alias for ``digv x``.
+    Dig a vein across z-levels, digging stairs as needed. This is an alias for
+    ``digv x``.
 ``digl [x] [undo] [-p<number>]``
-    :index:`Dig all of the selected layer stone.
-    <digl; Dig all of the selected layer stone.>` If ``undo`` is specified,
-    removes the designation instead (for if you accidentally set 50 levels at
-    once).
+    Dig all of the selected layer stone. If ``undo`` is specified, removes the
+    designation instead (for if you accidentally set 50 levels at once).
 ``diglx [-p<number>]``
-    :index:`Dig layer stone across z-levels, digging stairs as needed.
-    <diglx; Dig layer stone across z-levels, digging stairs as needed.>` This
-    is an alias for ``digl x``.
+    Dig layer stone across z-levels, digging stairs as needed. This is an alias
+    for ``digl x``.
 ``digcircle [<diameter>] [<solidity>] [<action>] [<designation>] [-p<number>]``
-    :index:`Designate circles. <digcircles; Designate circles.>` The diameter
-    is the number of tiles across the center of the circle that you want to dig.
-    See the `digcircle`_ section below for options.
+    Designate circles. The diameter is the number of tiles across the center of
+    the circle that you want to dig. See the `digcircle`_ section below for
+    options.
 ``digtype [<designation>] [-p<number>]``
-    :index:`Designate all vein tiles of the selected type.
-    <digtype; Designate all vein tiles of the selected type.>` See the `digtype`_
-    section below for options.
+    Designate all vein tiles of the selected type. See the `digtype`_ section
+    below for options.
 ``digexp [<pattern>] [<filter>] [-p<number>]``
-    :index:`Designate dig patterns for exploratory mining.
-    <digexp; Designate dig patterns for exploratory mining.>` See the `digexp`_
-    section below for options
+    Designate dig patterns for exploratory mining. See the `digexp`_ section
+    below for options.
 
 All commands support specifying the priority of the dig designations with
 ``-p<number>``, where the number is from 1 to 7. If a priority is not specified,

docs/plugins/digFlood.rst

@@ -1,13 +1,16 @@
 digFlood
 ========
-**Tags:** `tag/fort`, `tag/auto`, `tag/map`
-:dfhack-keybind:`digFlood`
-
-:index:`Digs out veins as they are discovered.
-<digFlood; Digs out veins as they are discovered.>` It will only dig out
-appropriate tiles that are adjacent to a just-finished dig job, so if you want
-to autodig a vein that has already been discovered, you may need to manually
-designate one tile of the tile for digging to get started.
+
+.. dfhack-tool::
+    :summary: Digs out veins as they are discovered.
+    :tags: fort auto map
+
+Once you register specific vein types, this tool will automatically designate
+tiles of those types of veins for digging as your miners complete adjacent
+mining jobs. Note that it will *only* dig out tiles that are adjacent to a
+just-finished dig job, so if you want to autodig a vein that has already been
+discovered, you may need to manually designate one tile of the tile for digging
+to get started.
 
 Usage:
 

docs/plugins/diggingInvaders.rst

@@ -1,10 +1,9 @@
 diggingInvaders
 ===============
-**Tags:** `tag/fort`, `tag/mod`, `tag/map`
-:dfhack-keybind:`diggingInvaders`
 
-:index:`Invaders dig and destroy to get to your dwarves.
-<diggingInvaders; Invaders dig and destroy to get to your dwarves.>`
+.. dfhack-tool::
+    :summary: Invaders dig and destroy to get to your dwarves.
+    :tags: fort mod map
 
 Usage:
 

docs/plugins/dwarfmonitor.rst

@@ -1,11 +1,11 @@
 dwarfmonitor
 ============
-**Tags:** `tag/fort`, `tag/inspection`, `tag/units`
-:dfhack-keybind:`dwarfmonitor`
 
-:index:`Measure fort happiness and efficiency.
-<dwarfmonitor; Measure fort happiness and efficiency.>` Also show heads-up
-display widgets with live fort statistics.
+.. dfhack-tool::
+    :summary: Measure fort happiness and efficiency.
+    :tags: fort inspection units
+
+It can also show heads-up display widgets with live fort statistics.
 
 Usage:
 

docs/plugins/dwarfvet.rst

@@ -1,10 +1,9 @@
 dwarfvet
 ========
-**Tags:** `tag/fort`, `tag/mod`, `tag/animals`
-:dfhack-keybind:`dwarfvet`
 
-:index:`Allows animals to be treated at animal hospitals.
-<dwarfvet; Allows animals to be treated at animal hospitals.>`
+.. dfhack-tool::
+    :summary: Allows animals to be treated at animal hospitals.
+    :tags: fort mod animals
 
 Annoyed your dragons become useless after a minor injury? Well, with dwarfvet,
 injured animals will be treated at an animal hospital, which is simply a hospital

docs/plugins/embark-assistant.rst

@@ -1,14 +1,15 @@
 embark-assistant
 ================
-**Tags:** `tag/fort`, `tag/embark`, `tag/interface`
-:dfhack-keybind:`embark-assistant`
 
-:index:`Embark site selection support.
-<embark-assistant; Embark site selection support.>` Run this command while the
-pre-embark screen is displayed to show extended (and correct(?)) resource
-information for the embark rectangle as well as normally undisplayed sites in
-the current embark region. You will also have access to a site selection tool
-with far more options than DF's vanilla search tool.
+.. dfhack-tool::
+    :summary: Embark site selection support.
+    :tags: fort embark interface
+
+Run this command while the pre-embark screen is displayed to show extended (and
+reasonably correct) resource information for the embark rectangle as well as
+normally undisplayed sites in the current embark region. You will also have
+access to a site selection tool with far more options than DF's vanilla search
+tool.
 
 If you enable the plugin, you'll also be able to invoke ``embark-assistant``
 with the :kbd:`A` key on the pre-embark screen.

docs/plugins/embark-tools.rst

@@ -1,10 +1,9 @@
 embark-tools
 ============
-**Tags:** `tag/fort`, `tag/embark`, `tag/interface`
-:dfhack-keybind:`embark-tools`
 
-:index:`Extend the embark screen functionality.
-<embark-tools; Extend the embark screen functionality.>`
+.. dfhack-tool::
+    :summary: Extend the embark screen functionality.
+    :tags: fort embark interface
 
 Usage::
 

docs/plugins/eventful.rst

@@ -1,7 +1,9 @@
 eventful
 ========
-**Tags:** `tag/dev`, `tag/mod`
 
-Provides a Lua API for reacting to in-game events.
+.. dfhack-tool::
+    :summary: Provides a Lua API for reacting to in-game events.
+    :tags: dev mod
+    :no-command:
 
 See `eventful-api` for details.

docs/plugins/fastdwarf.rst

@@ -1,9 +1,9 @@
 fastdwarf
 =========
-**Tags:** `tag/fort`, `tag/armok`, `tag/units`
-:dfhack-keybind:`fastdwarf`
 
-Dwarves teleport and/or finish jobs instantly.
+.. dfhack-tool::
+    :summary: Dwarves teleport and/or finish jobs instantly.
+    :tags: fort armok units
 
 Usage::
 

docs/plugins/filltraffic.rst

@@ -3,24 +3,28 @@
 
 filltraffic
 ===========
-**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/map`
-:dfhack-keybind:`filltraffic`
-:dfhack-keybind:`alltraffic`
-:dfhack-keybind:`restrictice`
-:dfhack-keybind:`restrictliquids`
-
-Usage:
-
-``filltraffic <designation> [<options>]``
-    Set traffic designations using flood-fill starting at the cursor. Flood
-    filling stops at walls and doors.
-``alltraffic <designation>``
-    Set traffic designations for every single tile of the map - useful for
-    resetting traffic designations.
-``restrictice``
-    Restrict traffic on all tiles on top of visible ice.
-``restrictliquids``
-    Restrict traffic on all visible tiles with liquid.
+
+.. dfhack-tool::
+    :summary: Set traffic designations using flood-fill starting at the cursor.
+    :tags: fort productivity design map
+
+.. dfhack-command:: alltraffic
+    :summary: Set traffic designations for every single tile of the map.
+
+.. dfhack-command:: restrictice
+    :summary: Restrict traffic on all tiles on top of visible ice.
+
+.. dfhack-command:: restrictliquids
+    :summary: Restrict traffic on all visible tiles with liquid.
+
+Usage::
+
+    filltraffic <designation> [<options>]
+    alltraffic <designation>
+    restrictice
+    restrictliquids
+
+For ``filltraffic``, flood filling stops at walls and doors.
 
 Examples
 --------

docs/plugins/fix-unit-occupancy.rst

@@ -1,10 +1,12 @@
 fix-unit-occupancy
 ==================
-**Tags:** `tag/fort`, `tag/fix`, `tag/map`
-:dfhack-keybind:``
 
-Fix phantom unit occupancy issues. For example, if you see "unit blocking tile"
-messages that you can't account for (:bug:`3499`), this tool can help.
+.. dfhack-tool::
+    :summary: Fix phantom unit occupancy issues.
+    :tags: fort fix map
+
+If you see "unit blocking tile" messages that you can't account for
+(:bug:`3499`), this tool can help.
 
 Usage::
 

docs/plugins/fixveins.rst

@@ -1,10 +1,12 @@
 fixveins
 ========
-**Tags:** `tag/fort`, `tag/fix`, `tag/map`
-:dfhack-keybind:`fixveins`
 
-Restore missing mineral inclusions. This tool can also remove invalid references
-to mineral inclusions if you broke your embark with tools like `tiletypes`.
+.. dfhack-tool::
+    :summary: Restore missing mineral inclusions.
+    :tags: fort fix map
+
+This tool can also remove invalid references to mineral inclusions if you broke
+your embark with tools like `tiletypes`.
 
 Usage::
 

docs/plugins/flows.rst

@@ -1,10 +1,12 @@
 flows
 =====
-**Tags:** `tag/fort`, `tag/inspection`, `tag/map`
-:dfhack-keybind:`flows`
 
-Counts map blocks with flowing liquids.. If you suspect that your magma sea
-leaks into HFS, you can use this tool to be sure without revealing the map.
+.. dfhack-tool::
+    :summary: Counts map blocks with flowing liquids.
+    :tags: fort inspection map
+
+If you suspect that your magma sea leaks into HFS, you can use this tool to be
+sure without revealing the map.
 
 Usage::
 

docs/plugins/follow.rst

@@ -1,11 +1,13 @@
 follow
 ======
-**Tags:** `tag/fort`, `tag/interface`, `tag/units`
-:dfhack-keybind:`follow`
 
-Make the screen follow the selected unit. Once you exit from the current menu or
-cursor mode, the screen will stay centered on the unit. Handy for watching
-dwarves running around. Deactivated by moving the cursor manually.
+.. dfhack-tool::
+    :summary: Make the screen follow the selected unit.
+    :tags: fort interface units
+
+Once you exit from the current menu or cursor mode, the screen will stay
+centered on the unit. Handy for watching dwarves running around. Deactivated by
+moving the cursor manually.
 
 Usage::
 

docs/plugins/forceequip.rst

@@ -1,14 +1,15 @@
 forceequip
 ==========
-**Tags:** `tag/adventure`, `tag/fort`, `tag/items`, `tag/units`
-:dfhack-keybind:`forceequip`
 
-Move items into a unit's inventory. This tool is typically used to equip
-specific clothing/armor items onto a dwarf, but can also be used to put armor
-onto a war animal or to add unusual items (such as crowns) to any unit. Make
-sure the unit you want to equip is standing on the target items, which must be
-on the ground and be unforbidden. If multiple units are standing on the same
-tile, the first one will be equipped.
+.. dfhack-tool::
+    :summary: Move items into a unit's inventory.
+    :tags: adventure fort items units
+
+This tool is typically used to equip specific clothing/armor items onto a dwarf,
+but can also be used to put armor onto a war animal or to add unusual items
+(such as crowns) to any unit. Make sure the unit you want to equip is standing
+on the target items, which must be on the ground and be unforbidden. If multiple
+units are standing on the same tile, the first one will be equipped.
 
 The most reliable way to set up the environment for this command is to pile
 target items on a tile of floor with a garbage dump activity zone or the

docs/plugins/generated-creature-renamer.rst

@@ -1,12 +1,20 @@
 generated-creature-renamer
 ==========================
-**Tags:** `tag/adventure`, `tag/fort`, `tag/legends`, `tag/units`
-:dfhack-keybind:`list-generated`
-:dfhack-keybind:`save-generated-raws`
 
-Automatically renames generated creatures. Now, forgotten beasts, titans,
-necromancer experiments, etc. will have raw token names that match the
-description given in-game instead of unreadable generated strings.
+.. dfhack-tool::
+    :summary: Automatically renames generated creatures.
+    :tags: adventure fort legends units
+    :no-command:
+
+.. dfhack-command:: list-generated
+    :summary: List the token names of all generated creatures.
+
+.. dfhack-command:: save-generated-raws
+    :summary: Export a creature graphics file for modding.
+
+Now, forgotten beasts, titans, necromancer experiments, etc. will have raw token
+names that match the description given in-game instead of unreadable generated
+strings.
 
 Usage:
 

docs/plugins/getplants.rst

@@ -1,10 +1,12 @@
 getplants
 =========
-**Tags:** `tag/fort`, `tag/productivity`
-:dfhack-keybind:`getplants`
 
-Designate trees for chopping and shrubs for gathering. Specify the types of
-trees to cut down and/or shrubs to gather by their plant names.
+.. dfhack-tool::
+    :summary: Designate trees for chopping and shrubs for gathering.
+    :tags: fort productivity
+
+Specify the types of trees to cut down and/or shrubs to gather by their plant
+names.
 
 Usage:
 

docs/plugins/hotkeys.rst

@@ -1,11 +1,12 @@
 hotkeys
 =======
-**Tags:** `tag/system`, `tag/productivity`, `tag/interface`
-:dfhack-keybind:`hotkeys`
 
-Show all dfhack keybindings in current context. The command opens an in-game
-screen showing which DFHack keybindings are active in the current context.
-See also `hotkey-notes`.
+.. dfhack-tool::
+    :summary: Show all dfhack keybindings for the current context.
+    :tags: system productivity interface
+
+The command opens an in-game screen showing which DFHack keybindings are active
+in the current context. See also `hotkey-notes`.
 
 Usage::
 

docs/plugins/infiniteSky.rst

@@ -1,10 +1,13 @@
 infiniteSky
 ===========
-**Tags:** `tag/fort`, `tag/map`
-:dfhack-keybind:`infiniteSky`
 
-Automatically allocates new z-levels of sky at the top of the map as you build
-up, or on request allocates many levels all at once.
+.. dfhack-tool::
+    :summary: Automatically allocates new z-levels of sky
+    :tags: fort map
+
+If enabled, this plugin will automatically allocate new z-levels of sky at the
+top of the map as you build up. Or it can allocate one or many additional levels
+at your command.
 
 Usage:
 

docs/plugins/isoworldremote.rst

@@ -1,5 +1,9 @@
 isoworldremote
 ==============
-**Tags:** `tag/dev`, `tag/mod`
 
-Provides a `remote API <remote>` used by Isoworld.
+.. dfhack-tool::
+    :summary: Provides a remote API used by Isoworld.
+    :tags: dev mod
+    :no-command:
+
+See `remote` for related remote APIs.

docs/plugins/jobutils.rst

@@ -2,12 +2,20 @@
 
 jobutils
 ========
-**Tags:** `tag/fort`, `tag/inspection`, `tag/jobs`
-:dfhack-keybind:`job`
-:dfhack-keybind:`job-duplicate`
-:dfhack-keybind:`job-material`
 
-Inspect or modify details of workshop jobs.
+.. dfhack-tool::
+    :summary: Provides commands for interacting with jobs.
+    :tags: fort inspection jobs
+    :no-command:
+
+.. dfhack-command:: job
+    :summary: Inspect or modify details of workshop jobs.
+
+.. dfhack-command:: job-duplicate
+    :summary: Duplicates the highlighted job.
+
+.. dfhack-command:: job-material
+    :summary: Alters the material of the selected job.
 
 Usage:
 

docs/plugins/labormanager.rst

@@ -1,12 +1,14 @@
 labormanager
 ============
-**Tags:** `tag/fort`, `tag/auto`, `tag/labors`
-:dfhack-keybind:`labormanager`
 
-Automatically manage dwarf labors. Labormanager is derived from `autolabor`
-but uses a completely different approach to assigning jobs to dwarves. While
-autolabor tries to keep as many dwarves busy as possible, labormanager instead
-strives to get jobs done as quickly as possible.
+.. dfhack-tool::
+    :summary: Automatically manage dwarf labors.
+    :tags: fort auto labors
+
+Labormanager is derived from `autolabor` but uses a completely different
+approach to assigning jobs to dwarves. While autolabor tries to keep as many
+dwarves busy as possible, labormanager instead strives to get jobs done as
+quickly as possible.
 
 Labormanager frequently scans the current job list, current list of dwarves, and
 the map to determine how many dwarves need to be assigned to what labors in

docs/plugins/lair.rst

@@ -1,10 +1,11 @@
 lair
 ====
-**Tags:** `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`lair`
 
-Mark the map as a monster lair. This avoids item scatter when the fortress is
-abandoned.
+.. dfhack-tool::
+    :summary: Mark the map as a monster lair.
+    :tags: fort armok map
+
+This avoids item scatter when the fortress is abandoned.
 
 Usage:
 

docs/plugins/liquids.rst

@@ -2,9 +2,13 @@
 
 liquids
 =======
-**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`liquids`
-:dfhack-keybind:`liquids-here`
+
+.. dfhack-tool::
+    :summary: Place magma, water or obsidian.
+    :tags: adventure fort armok map
+
+.. dfhack-command:: liquids-here
+    :summary: Spawn liquids on the selected tile.
 
 Place magma, water or obsidian.  See `gui/liquids` for an in-game interface for
 this functionality.

docs/plugins/luasocket.rst

@@ -1,7 +1,9 @@
 luasocket
 =========
-**Tags:** `tag/dev`, `tag/mod`
 
-Provides a Lua API for accessing network sockets.
+.. dfhack-tool::
+    :summary: Provides a Lua API for accessing network sockets.
+    :tags: dev mod
+    :no-command:
 
 See `luasocket-api` for details.

docs/plugins/manipulator.rst

@@ -1,9 +1,12 @@
 manipulator
 ===========
-**Tags:** `tag/fort`, `tag/productivity`, `tag/interface`, `tag/labors`
 
-An in-game labor management interface. It is equivalent to the popular Dwarf
-Therapist utility.
+.. dfhack-tool::
+    :summary: An in-game labor management interface.
+    :tags: fort productivity interface labors
+    :no-command:
+
+It is equivalent to the popular Dwarf Therapist utility.
 
 To activate, open the unit screen and press :kbd:`l`.
 

docs/plugins/map-render.rst

@@ -1,7 +1,9 @@
 map-render
 ==========
-**Tags:** `tag/dev`
 
-Provides a Lua API for rerendering portions of the map.
+.. dfhack-tool::
+    :summary: Provides a Lua API for rerendering portions of the map.
+    :tags: dev
+    :no-command:
 
 See `map-render-api` for details.

docs/plugins/misery.rst

@@ -1,9 +1,9 @@
 misery
 ======
-**Tags:** `tag/fort`, `tag/armok`, `tag/units`
-:dfhack-keybind:`misery`
 
-Increase the intensity of negative dwarven thoughts.
+.. dfhack-tool::
+    :summary: Increase the intensity of negative dwarven thoughts.
+    :tags: fort armok units
 
 When enabled, negative thoughts that your dwarves have will multiply by the
 specified factor.

docs/plugins/mode.rst

@@ -1,9 +1,9 @@
 mode
 ====
-**Tags:** `tag/dev`
-:dfhack-keybind:`mode`
 
-This command lets you see and change the game mode directly.
+.. dfhack-tool::
+    :summary: See and change the game mode.
+    :tags: dev
 
 .. warning::
 

docs/plugins/mousequery.rst

@@ -1,7 +1,9 @@
 mousequery
 ==========
-**Tags:** `tag/fort`, `tag/productivity`, `tag/interface`
-:dfhack-keybind:`mousequery`
+
+.. dfhack-tool::
+    :summary: Adds mouse controls to the DF interface.
+    :tags: fort productivity interface
 
 Adds mouse controls to the DF interface. For example, with ``mousequery`` you
 can click on buildings to configure them, hold the mouse button to draw dig

docs/plugins/nestboxes.rst

@@ -1,11 +1,14 @@
 nestboxes
 =========
-**Tags:** `tag/fort`, `tag/auto`, `tag/animals`
 
-Protect fertile eggs incubating in a nestbox. This plugin will automatically
-scan for and forbid fertile eggs incubating in a nestbox so that dwarves won't
-come to collect them for eating. The eggs will hatch normally, even when
-forbidden.
+.. dfhack-tool::
+    :summary: Protect fertile eggs incubating in a nestbox.
+    :tags: fort auto animals
+    :no-command:
+
+This plugin will automatically scan for and forbid fertile eggs incubating in a
+nestbox so that dwarves won't come to collect them for eating. The eggs will
+hatch normally, even when forbidden.
 
 Usage::
 

docs/plugins/orders.rst

@@ -1,9 +1,9 @@
 orders
 ======
-**Tags:** `tag/fort`, `tag/productivity`, `tag/jobs`
-:dfhack-keybind:`orders`
 
-Manage manager orders.
+.. dfhack-tool::
+    :summary: Manage manager orders.
+    :tags: fort productivity jobs
 
 Usage:
 

docs/plugins/pathable.rst

@@ -1,8 +1,10 @@
 pathable
 ========
-**Tags:** `tag/dev`, `tag/inspection`, `tag/interface`, `tag/map`
 
-Marks tiles that are reachable from the cursor. This plugin provides a Lua API,
-but no direct commands.
+.. dfhack-tool::
+    :summary: Marks tiles that are reachable from the cursor.
+    :tags: dev inspection interface map
+    :no-command:
 
-See `pathable-api` for details.
+This plugin provides a Lua API, but no direct commands. See `pathable-api` for
+details.

docs/plugins/petcapRemover.rst

@@ -1,16 +1,17 @@
 petcapRemover
 =============
-**Tags:** `tag/fort`, `tag/armok`, `tag/animals`
-:dfhack-keybind:`petcapRemover`
 
-Modify the pet population cap. In vanilla DF, pets will not reproduce unless the
-population is below 50 and the number of children of that species is below a
-certain percentage. This plugin allows removing these restrictions and setting
-your own thresholds. Pets still require PET or PET_EXOTIC tags in order to
-reproduce. In order to make population more stable and avoid sudden population
-booms as you go below the raised population cap, this plugin counts pregnancies
-toward the new population cap. It can still go over, but only in the case of
-multiple births.
+.. dfhack-tool::
+    :summary: Modify the pet population cap.
+    :tags: fort armok animals
+
+In vanilla DF, pets will not reproduce unless the population is below 50 and the
+number of children of that species is below a certain percentage. This plugin
+allows removing these restrictions and setting your own thresholds. Pets still
+require PET or PET_EXOTIC tags in order to reproduce. In order to make
+population more stable and avoid sudden population booms as you go below the
+raised population cap, this plugin counts pregnancies toward the new population
+cap. It can still go over, but only in the case of multiple births.
 
 Usage:
 

docs/plugins/plants.rst

@@ -2,10 +2,14 @@
 
 plants
 ======
-**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/map`
-:dfhack-keybind:`plant`
 
-Grow shrubs or trees.
+.. dfhack-tool::
+    :summary: Provides commands that interact with plants.
+    :tags: adventure fort armok map
+    :no-command:
+
+.. dfhack-command:: plant
+   :summary: Create a plant or make an existing plant grow up.
 
 Usage:
 

docs/plugins/power-meter.rst

@@ -1,7 +1,11 @@
 power-meter
 ===========
-**Tags:** `tag/fort`, `tag/mod`, `tag/buildings`
 
-Allow presure plates to measure power. If you run `gui/power-meter` while
-building a pressure plate, the pressure plate can be modified to detect power
-being supplied to gear boxes built in the four adjacent N/S/W/E tiles.
+.. dfhack-tool::
+    :summary: Allow presure plates to measure power.
+    :tags: fort mod buildings
+    :no-command:
+
+If you run `gui/power-meter` while building a pressure plate, the pressure
+plate can be modified to detect power being supplied to gear boxes built in the
+four adjacent N/S/W/E tiles.

docs/plugins/probe.rst

@@ -1,11 +1,15 @@
 probe
 =====
-**Tags:** `tag/adventure`, `tag/fort`, `tag/inspection`, `tag/map`
-:dfhack-keybind:`probe`
-:dfhack-keybind:`bprobe`
-:dfhack-keybind:`cprobe`
 
-Display low-level properties of selected objects.
+.. dfhack-tool::
+    :summary: Display low-level properties of the selected tile.
+    :tags: adventure fort inspection map
+
+.. dfhack-command:: bprobe
+    :summary: Display low-level properties of the selected building.
+
+.. dfhack-command:: cprobe
+    :summary: Display low-level properties of the selected unit.
 
 Usage:
 

docs/plugins/prospector.rst

@@ -2,11 +2,17 @@
 
 prospector
 ==========
-**Tags:** `tag/fort`, `tag/embark`, `tag/inspection`, `tag/map`
-:dfhack-keybind:`prospect`
 
-Shows a summary of resources that exist on the map. It can also calculate an
-estimate of resources available in the selected embark area.
+.. dfhack-tool::
+    :summary: Provides commands that help you analyze natural resources.
+    :tags: fort embark inspection map
+    :no-command:
+
+.. dfhack-command:: prospect
+   :summary: Shows a summary of resources that exist on the map.
+
+It can also calculate an estimate of resources available in the selected embark
+area.
 
 Usage::
 

docs/plugins/regrass.rst

@@ -1,14 +1,15 @@
 regrass
 =======
-**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/animals`
-:dfhack-keybind:`regrass`
 
-Regrows all the grass. Use this command if your grazers have eaten everything
-down to the dirt.
+.. dfhack-tool::
+    :summary: Regrows all the grass.
+    :tags: adventure fort armok animals
+
+Use this command if your grazers have eaten everything down to the dirt.
 
 Usage::
 
     regrass [max]
 
-Specify the 'max' option to pack more grass onto a tile than what the game
+Specify the 'max' keyword to pack more grass onto a tile than what the game
 normally allows to give your grazers extra chewing time.

docs/plugins/rename.rst

@@ -1,9 +1,11 @@
 rename
 ======
-**Tags:** `tag/adventure`, `tag/fort`, `tag/productivity`
-:dfhack-keybind:`rename`
 
-Easily rename things.  Use `gui/rename` for an in-game interface.
+.. dfhack-tool::
+    :summary: Easily rename things.
+    :tags: adventure fort productivity
+
+Use `gui/rename` for an in-game interface.
 
 Usage:
 

docs/plugins/rendermax.rst

@@ -1,10 +1,12 @@
 rendermax
 =========
-**Tags:** `tag/adventure`, `tag/fort`, `tag/mod`
-:dfhack-keybind:`rendermax`
 
-Modify the map lighting. This plugin provides a collection of OpenGL lighting
-filters that affect how the map is drawn to the screen.
+.. dfhack-tool::
+    :summary: Modify the map lighting.
+    :tags: adventure fort mod
+
+This plugin provides a collection of OpenGL lighting filters that affect how the
+map is drawn to the screen.
 
 Usage:
 

docs/plugins/resume.rst

@@ -1,13 +1,18 @@
 resume
 ======
-**Tags:** `tag/fort`, `tag/productivity`
-:dfhack-keybind:`resume`
-
-Color planned buildings based on their suspend status. When enabled, this plugin
-will display a colored 'X' over suspended buildings. When run as a command, it
-can resume all suspended building jobs, allowing you to quickly recover if a
-bunch of jobs were suspended due to the workers getting scared off by wildlife
-or items temporarily blocking buildling sites.
+
+.. dfhack-tool::
+    :summary: Color planned buildings based on their suspend status.
+    :tags: fort productivity
+    :no-command:
+
+.. dfhack-command:: resume
+   :summary: Resume all suspended building jobs.
+
+When enabled, this plugin will display a colored 'X' over suspended buildings.
+When run as a command, it can resume all suspended building jobs, allowing you
+to quickly recover if a bunch of jobs were suspended due to the workers getting
+scared off by wildlife or items temporarily blocking buildling sites.
 
 Usage::
 

docs/plugins/reveal.rst

@@ -2,17 +2,29 @@
 
 reveal
 ======
-**Tags:** `tag/adventure`, `tag/fort`, `tag/inspection`, `tag/armok`, `tag/map`
-:dfhack-keybind:`reveal`
-:dfhack-keybind:`unreveal`
-:dfhack-keybind:`revforget`
-:dfhack-keybind:`revtoggle`
-:dfhack-keybind:`revflood`
-:dfhack-keybind:`nopause`
-
-Reveals the map. This reveals all z-layers in fort mode. It also works in
-adventure mode, but any of its effects are negated once you move. When you use
-it this way, you don't need to run ``unreveal`` to hide the map again.
+
+.. dfhack-tool::
+    :summary: Reveals the map.
+    :tags: adventure fort inspection armok map
+
+.. dfhack-tool:: unreveal
+   :summary: Hides previously hidden tiles again.
+
+.. dfhack-tool:: revforget
+   :summary: Discard records about what was visible before revealing the map.
+
+.. dfhack-tool:: revtoggle
+   :summary: Switch between reveal and unreveal.
+
+.. dfhack-tool:: revflood
+   :summary: Hide everything, then reveal tiles with a path to the cursor.
+
+.. dfhack-tool:: nopause
+   :summary: Disable pausing.
+
+This reveals all z-layers in fort mode. It also works in adventure mode, but any
+of its effects are negated once you move. When you use it this way, you don't
+need to run ``unreveal`` to hide the map again.
 
 Usage:
 

docs/plugins/ruby.rst

@@ -2,12 +2,17 @@
 
 ruby
 ====
-**Tags:** `tag/dev`
-:dfhack-keybind:`rb`
-:dfhack-keybind:`rb_eval`
 
-Allow Ruby scripts to be executed. When invoked as a command, you can Eval() a
-ruby string.
+.. dfhack-tool::
+    :summary: Allow Ruby scripts to be executed as DFHack commands.
+    :tags: dev
+    :no-command:
+
+.. dfhack-command:: rb
+   :summary: Eval() a ruby string.
+
+.. dfhack-command:: rb_eval
+   :summary: Eval() a ruby string.
 
 Usage::
 

docs/plugins/search.rst

@@ -2,12 +2,16 @@
 
 search
 ======
-**Tags:** `tag/fort`, `tag/productivity`, `tag/interface`
 
-Adds search capabilities to the UI. The Stocks, Animals, Trading, Stockpile,
-Noble (assignment candidates), Military (position candidates), Burrows (unit
-list), Rooms, Announcements, Job List, and Unit List screens all get hotkeys
-that allow you to dynamically filter the displayed lists.
+.. dfhack-tool::
+    :summary: Adds search capabilities to the UI.
+    :tags: fort productivity interface
+    :no-command:
+
+Search options are added to the Stocks, Animals, Trading, Stockpile, Noble
+aassignment candidates), Military (position candidates), Burrows (unit list),
+Rooms, Announcements, Job List, and Unit List screens all get hotkeys that allow
+you to dynamically filter the displayed lists.
 
 Usage::
 

docs/plugins/seedwatch.rst

@@ -1,9 +1,9 @@
 seedwatch
 =========
-**Tags:** `tag/fort`, `tag/auto`
-:dfhack-keybind:`seedwatch`
 
-Manages seed and plant cooking based on seed stock levels.
+.. dfhack-tool::
+    :summary: Manages seed and plant cooking based on seed stock levels.
+    :tags: fort auto
 
 Each seed type can be assigned a target. If the number of seeds of that type
 falls below that target, then the plants and seeds of that type will be excluded