I've been thinking of this a bit more - if we're going to have a clear separation between sections and chapters in our documentation, would it be easier to maintain (and more well-structured) to format the directory structure as well? I believe mdBook allows directories for its SUMMARY.md file, so we could have something like...

.
├── velocity
│   └── velocity_intro.md
└── spigot
    └── (everything else)

We could also continue this with something like...

.
├── velocity
│   └── velocity_intro.md
└── spigot
    ├── arguments
    │   ├── argument_whatever1.md
    │   ├── argument_whatever2.md
    │   └── ...
    └── annotations
        └── ...

Just a thought. Not sure how relevant this is at this stage, but if we continue branching out to different platforms (fabric, forge, sponge, etc.), it's probably worth considering.

Yeah, it probably makes sense adding something like that.
However, I do think it's not necessary now but should be something to add for 10.0.0 when we actually do release Velocity.
For now it's probably sufficient to be able to link people to that page if they ask about Velocity support before we release 10.0.0.

Maybe we could also bring the documentation-code structure together with the docssrc files. Something like this maybe?

commandapi-documentation/
├─ pom.xml
├─ docssrc/
│  └─ intro.md
├─ bukkit/
│  ├─ docssrc/
│  │  ├─ bukkit_intro.md
│  │  ├─ arguments/
│  │  │  ├─ argument_whatever1.md
│  │  │  ├─ argument_whatever2.md
│  │  │  └─ ...
│  │  └─ annotations/
│  │     └─ ...
│  └─ commandapi-documentation-bukkit-code/
│     ├─ src/main/.../
│     └─ pom.xml
└─ velocity/
   ├─ docssrc/
   │  └─ velocity_intro.md
   └─ commandapi-documenatation-velocity-code/
      ├─ src/main/.../
      └─ pom.xml

That way, for example, when you're working with the bukkit documentation pages bukkit/docssrc, you're simply one directory away from documentation examples bukkit/commandapi-documentation-bukkit-code.

Or maybe we could completely merge the documentation-code and docssrc files like so:

commandapi-documenation/
├─ pom.xml
├─ src/
│  └─ main/
│     └─ intro.md
├─ commandapi-documenation-bukkit/
│  ├─ pom.xml
│  └─ src/
│     └─ main/
│        ├─ bukkit_intro.md
│        ├─ arguments/
│        │  ├─ argument1.md
│        │  ├─ argument1.java
│        │  ├─ argument1.kt
│        │  ├─ argument2.md
│        │  ├─ argument2.java
│        │  ├─ argument2.kt
│        │  └─ ...
│        └─ annotations/
│           └─ ...
└─ commandapi-documentation-velocity/
   ├─ pom.xml
   └─ src/
      └─ main/
         ├─ velocity_intro.md
         ├─ randomNumberCommand.java
         ├─ randomNumberCommand.kt
         └─ randomNumberCommandDSL.kt

I'm not sure if mdBook, Java, or Kotlin like all those files in the same place, but it would make it very easy to find the files that hold the code that documentation pages reference. Individual code files for each documentation page might be easier to understand than monolithic Example classes that hold everything.

But yeah, that's probably not something we need to set up now for a single page about Velocity.

For this PR, I intentionally paid attention to not change any existing documentation code locations because that would need to be updated in the pages as well which to be honest I deemed to not be within the scope of this PR.
During 9.0.0 development, I sorted the examples alphabetically and with the method they are in you also find the page rather quickly. The class, however, is quite big so splitting that up to a per-page class might also help.
With #517 I am also already trying to introduce platform specific documentation so something like this maybe should wait.

Maybe once we do some more Velocity docs it would make sense to restructure

No argument here. Restructuring definitely makes sense but also definitely doesn't fit into this PR.

Also thanks for the few notes. I'll do them all locally but will add you as a co-author for the suggested changes as GitHub would do the same.