Like everyone great tool that I use to document my python code. I've been playing around with a custom handler based off your template handler to document some internal file formats/code that are not python and have a few questions.

I am using another tool to generate some image diagrams. Doing that in the render() method makes mkdocs serve go into an infinite loop after you click a page since it sees a file change in the docs_dir, regenerates, sees lots of image files change again then loops. I can do a few things but are looking to your suggestion on the best or if I have missed an easier path.

Use mkdocs serve --dirtyreload [Current Solution]

Not great since an update to that file doesn't necessarily trigger updating these diagrams since they are different files. So while I'm not infinitely looping, I'm not rendering the latest and greatest when serving. Build works as expected.

Use a similar recipe to automatic code pages with mkdocs-gen-files. [Rejected]

Since this doesn't know what identifiers will be collected, I have to generate a lot of images that may never be used. I also have no guarantees when rendering that the file actually exists since I don't know the site_dir at the handler scope.

mkdocstrings change to expose mkdocs config to handler

Currently, it looks like the configuration is stripped down before passing to the handler. A potential solution to give me access to the mkdocs configuration object and ultimate configurability by passing that to the handler? This could allow collect(), render(), and teardown() have some knowledge about the current mkdocs configuration including where the site_dir is to copy these files directly into it. Looking at the python and crystal handlers, neither use site_name.

plugin.py:168

        extension_config = {
            "site_name": config["site_name"],  # Change this to "mkdocs_config": config,
            "config_file_path": config["config_file_path"],
            "theme_name": theme_name,
            "mdx": config["markdown_extensions"],
            "mdx_configs": config["mdx_configs"],
            "mkdocstrings": self.config,
            # "mkdocs_config": config, #  Or add as a new item to not break existing code.
        }
        self._handlers = Handlers(extension_config)

mkdocstrings change to add a extra_files method during the on_env event. [Rejected]

Just like the handler.extra_css, add an attribute to BaseHandler that is a iterable of paths to copy to where ever the site_dir may be. I can populate extra_files during rendering or collecting and if one errors out for any reason, react to it in the rendering.

if self._handlers:
    css_content = "\n".join(handler.extra_css for handler in self.handlers.seen_handlers)
    write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))

    for handler in self.handlers.seen_handlers:
        for filepath in handler.extra_files:
            copy_file(filepath, os.path.join(config["site_dir"])

If either of these two changes are favorable, happy to open a PR as such. My preference would be exposing the mkdocs configuration but the second option has better "guard rails" for users.

  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          import:
            - https://docs.python.org/3/objects.inv
            - https://mkdocstrings.github.io/objects.inv
        my_custom_handler:
          paths:
            - where to look for these files.

• mkdocstrings version: 0.19.1