Description
The documentation could be reorganized to better separate the info for users from the info for developers (themes and plugins). I'm thinking the Nav might look something like this (actual page titles and order subject to change):
- Home
- User Guide:
- Getting Started
- Installation
- File Layout
- Writing Markdown
- Configuration
- Themes
- Developer Guide:
- Themes
- Plugins
- API
- About:
- Release Notes
- Contributing
- License
Getting Started
and Installation
have been broken out into their own pages. The Home
page should be a simple introduction with prominate links to the new pages (and perhaps a few others).
Note that the Developer Guide
and the User Guide
each contain a Themes
page. Each would contain theme related documentation specific to the needs of theme develpers and users respectively. Currently the two are mixed with pieces of each intermingled, which makes it hard for devs to find what they need and can be overwhelming for users.
In the Developer Guide
, the Themes
and Plugins
pages would contain mostly prose regarding their respective topics, while the API
page would document the various classes, methods, and functions in the MkDocs' code base which plugin devs might need to use. For example, plugins can define their own config, but we currently have no documentation about the config classes and how to use them. We also define page and nav objects for theme devs (attributes which might be called from a template), but not for plugin devs (all public attributes and methods of the class). Many of the utils
functions could be useful to plugin devs as well.
Much of the work consists simply of rearranging the existing documentation with minor edits to make the text fit in it's new context. However, the API
is currently non-existent. I see two possible paths:
- Author the documentation from stratch in Markdown.
- Build a plugin which extracts documentation from the source code.
Option two would certainly be more userful long term (and it provides a new feature for other users), but it would be more work as much of the source code has very limited documentation in the comments.
Whichever way we go, the rest of the work could be started now. The API
can always be added later.