Better public API

[pawamoy]

MkDocs could gain at better exposing and documenting its API.

Some of it could help plugin/extension authors (reusing Markdown treeprocessors), but is not exposed. Some of it must be imported for integration within other Python tools, but is not exposed (entrypoints in __main__). Some of it is documented under API reference, some of it under Plugins, some of it is not documented.

Side note: One reason I started using MkDocs and writing mkdocstrings was to have all auto-documented objects (API autodoc) appear in the table of contents. But the default mkdocs theme does not allow that 😢

Relevant issues:

• https://github.com/mkdocs/mkdocs/issues/1240
• https://github.com/mkdocs/mkdocs/issues/2743
• https://github.com/mkdocs/mkdocs/issues/2876 (careful with logging configuration in API vs CLI)
• https://github.com/mkdocs/mkdocs/issues/3055
• ? (please comment and I'll add links)

[squidfunk]

+1! Also, if we could add subcommand support, that'd be really powerful! As a theme and plugin author, I'd really love if MkDocs could offer all of the following extension capabilities:

• [x] Themes (incl. overrides)
• [x] Plugins
• [x] Hooks (lightweight option to plugins)
• [x] Markdown extensions
• [ ] Subcommands
• [ ] Custom YAML tags in mkdocs.yml

For instance, subcommands would allow the blog plugin of Material for MkDocs to make it easy to scaffold a new post. Custom YAML tags would allow to solve things like #3331. I've thought about creating a CLI for Material for MkDocs, but hooking into the mkdocs CLI would feel more natural.

[mkusz]

As for log levels (#2876 ) and overall better debugging while developing, I have created a plugin for that, called pub-debugger. This is core functionality for development, but not sure if we want to invest much time in it since default console logging is usefull for normal user. More in depth view is only needed during development phase.