Loaders Based Plugin API

Proposal

This is a proposal for a Plugin API based on loaders. Loader is used for convert raw files into html content.

Create loader

# my_loader.py
class MyLoader:

    def __init__(options):
        """Configure your loader with options"""

    def accept(self, filename):
        """Decide load the file or not"""

    def load(self, page):
        """Load page"""
        # the page object contains all info of which should be load
        # the return value contains all info of which should be write
        return MkdocsResponse()

Register loaders

# setup.py
entry_points = {
    'mkdocs.loaders': [
        'my_loader = path.to.my_loader:MyLoader',
    ]
}

Activating Loaders

# mkdocs.yml
loaders:
    - name: "my_loader"
      options: "options"

Implementation

# changes in mkdocs.config.load_config
def load_config(config_file=None, **kwargs):
    # ...do somethings
    loaders = []
    # instance loaders
    cfg["loaders"] = loaders

# changes in mkdocs.commands.build.py
def _build_page(page, config):
    for loader in config["loaders"]:
        if loader.accept(page.input_path):
            return loader.load(page)
    raise ValueError("Can't find loader for {}".format(page.input_path))

# also, create a markdown loader and register it as builtin loader
class MarkdownLoader:
    def accept(self, filename):
        # accept markdown file
        pass

    def load(page):
        # some code of origin _build_page
        pass

Example

A autodoc loader.
Live Demo: http://restaction.readthedocs.io/zh_CN/latest/api/

Usage

docs/api.autodoc

mkdocs_autodoc
mkdocs_autodoc::Demo

mkdocs.yml

site_name: Demo
pages:
  - Home: index.md
  - API: api.autodoc

Loader

class AutodocLoader:
    def accept(self, filename):
        # accept *.autodoc file
        pass

    def load(page):
        # parse *.autodoc file, generate html content
        pass

See also

https://groups.google.com/forum/#!topic/mkdocs/7x2u9iN7gdk