Python API

MkDocs can be used as a Python library in addition to a command-line tool. This is useful for CI scripts, build system integrations (for example Hatch or uv plugins), or any other programmatic use such as generating multiple sites or building documentation from an application.

Building a site

The mkdocs.build() function is the programmatic equivalent of the mkdocs build command:

import mkdocs

config = mkdocs.build(config_file="mkdocs.yml")
print(f"Built site to {config.site_dir}")

The loaded configuration is returned, so you can inspect or reuse it (for example config.site_dir or config.site_url).

Overriding configuration in code

Any configuration option can be overridden directly from Python, without editing the config file — or even without a config file at all. Options passed as keyword arguments behave like the corresponding command line options:

import mkdocs

config = mkdocs.build(
    config_file="mkdocs.yml",
    site_name="My project",
    site_url="https://example.com",
    use_directory_urls=False,
    strict=True,
)

When config_file is omitted, mkdocs.yml in the current directory is used. If you want to define the whole configuration in code, pass the values as keyword arguments and point config_file at a minimal (or empty) file.

Building without a config file

A config file is always loaded, but you can build with only programmatic options by providing an empty config file:

import pathlib
import tempfile

import mkdocs

with tempfile.TemporaryDirectory() as tmp:
    config_file = pathlib.Path(tmp) / "mkdocs.yml"
    config_file.write_text("site_name: Generated docs\n", encoding="utf-8")

    config = mkdocs.build(
        config_file=config_file,
        site_dir=pathlib.Path(tmp) / "site",
        nav=[{"Home": "index.md"}],
    )

Running the development server

The mkdocs.serve() function is the programmatic equivalent of the mkdocs serve command. It blocks until the server is shut down (Ctrl+C or SIGTERM):

import mkdocs

mkdocs.serve(
    config_file="mkdocs.yml",
    dev_addr="127.0.0.1:8000",
    livereload=True,
    watch=["../shared-assets"],
)

Behavior notes

• Errors and warnings are reported through the standard Python logging module using the mkdocs logger, exactly as with the command line tool. In strict mode, warnings abort the build.
• Plugin startup and shutdown events are fired automatically around the build, so plugin behavior matches mkdocs build / mkdocs serve.
• For anything not covered here, the mkdocs build and mkdocs serve command line options map directly to the keyword arguments of mkdocs.build() and mkdocs.serve(). See the API reference for the complete signatures.