Improve the structure of the mdBook documentation #10619
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
(This is a follow up to #5534)
The current documentation does not have a consistent structure making it hard to see an overview of the content and navigate to the desired section. Currently:
1. Installation
is totally self-contained with no mdBook subsections. All navigation is in the TOC.2. Usage
has some usage guides in the markdown file TOC, and also some in mdBook subsections.3. Migrating from Vim
is not complete and basically just a link to the WIKI < deal with that another day4. Config
has the Editor subsection in the markdown file (no TOC), and then the rest in mdBook subsections.5. Guides
is the only consistent one. A brief description of the section, and then all neatly divided into mdBook subsections.I have refactored it to be consistent and follow the following format, the same as the current
Guides
section:I have not changed any of the actual content, apart from in
keymap
, the heading should be an h2 for consistency, and- [Comment mode](#comment-mode)
was a bug/broken link, the content never was created.