API reference

Note

The main entry point to the API is through Events that are received by plugins. These events' descriptions link back to this page.

mkdocs.structure.files.Files

A collection of File objects.

src_paths: dict[str, File] property

Soft-deprecated, prefer src_uris.

src_uris: dict[str, File] property

A mapping containing every file, with the keys being their src_uri.

__iter__() -> Iterator[File]

Iterate over the files within.

__len__() -> int

The number of files within.

__contains__(path: str) -> bool

Whether the file with this src_uri is in the collection.

get_file_from_path(path: str) -> File | None

Return a File instance with File.src_uri equal to path.

append(file: File) -> None

Append file to Files collection.

remove(file: File) -> None

Remove file from Files collection.

copy_static_files(dirty: bool = False, *, inclusion: Callable[[InclusionLevel], bool] = InclusionLevel.is_included) -> None

Copy static files from source to destination.

documentation_pages(*, inclusion: Callable[[InclusionLevel], bool] = InclusionLevel.is_included) -> Sequence[File]

Return iterable of all Markdown page file objects.

static_pages() -> Sequence[File]

Return iterable of all static page file objects.

media_files() -> Sequence[File]

Return iterable of all file objects which are not documentation or static pages.

javascript_files() -> Sequence[File]

Return iterable of all javascript file objects.

css_files() -> Sequence[File]

Return iterable of all CSS file objects.

add_files_from_theme(env: jinja2.Environment, config: MkDocsConfig) -> None

Retrieve static files from Jinja environment and add to collection.

mkdocs.structure.files.File

A MkDocs File object.

Points to the source and destination locations of a file.

The path argument must be a path that exists relative to src_dir.

The src_dir and dest_dir must be absolute paths on the local file system.

The use_directory_urls argument controls how destination paths are generated. If False, a Markdown file is mapped to an HTML file of the same name (the file extension is changed to .html). If True, a Markdown file is mapped to an HTML index file (index.html) nested in a directory using the "name" of the file in path. The use_directory_urls argument has no effect on non-Markdown files.

File objects have the following properties, which are Unicode strings:

src_uri: str instance-attribute

The pure path (always '/'-separated) of the source file relative to the source directory.

dest_path: str property writable

Same as dest_uri (and synchronized with it) but will use backslashes on Windows. Discouraged.

src_path: str = path instance-attribute property writable

Same as src_uri (and synchronized with it) but will use backslashes on Windows. Discouraged.

dest_uri: str = dest_uri instance-attribute

The pure path (always '/'-separated) of the destination file relative to the destination directory.

url: str = self._get_url(use_directory_urls) instance-attribute

The URI of the destination file relative to the destination directory as a string.

abs_src_path: str = os.path.normpath(os.path.join(src_dir, self.src_uri)) instance-attribute

The absolute concrete path of the source file. Will use backslashes on Windows.

abs_dest_path: str = os.path.normpath(os.path.join(dest_dir, self.dest_uri)) instance-attribute

The absolute concrete path of the destination file. Will use backslashes on Windows.

inclusion: InclusionLevel = inclusion class-attribute instance-attribute

Whether the file will be excluded from the built site.

url_relative_to(other: File | str) -> str

Return url for file relative to other file.

copy_file(dirty: bool = False) -> None

Copy source file to destination, ensuring parent directories exist.

is_documentation_page() -> bool

Return True if file is a Markdown page.

is_static_page() -> bool

Return True if file is a static page (HTML, XML, JSON).

is_media_file() -> bool

Return True if file is not a documentation or static page.

is_javascript() -> bool

Return True if file is a JavaScript file.

is_css() -> bool

Return True if file is a CSS file.

mkdocs.config.base.Config

Bases: UserDict

Base class for MkDocs configuration, plugin configuration (and sub-configuration) objects.

It should be subclassed and have ConfigOptions defined as attributes. For examples, see mkdocs/contrib/search/init.py and mkdocs/config/defaults.py.

Behavior as it was prior to MkDocs 1.4 is now handled by LegacyConfig.

__new__(*args, **kwargs) -> Config

Compatibility: allow referring to LegacyConfig(...) constructor as Config(...).

set_defaults() -> None

Set the base config by going through each validator and getting the default if it has one.

load_dict(patch: dict) -> None

Load config options from a dictionary.

load_file(config_file: IO) -> None

Load config options from the open file descriptor of a YAML file.

mkdocs.utils.templates.TemplateContext

Bases: TypedDict

nav: Navigation instance-attribute

pages: Sequence[File] instance-attribute

base_url: str instance-attribute

extra_css: Sequence[str] instance-attribute

extra_javascript: Sequence[str] instance-attribute

mkdocs_version: str instance-attribute

build_date_utc: datetime.datetime instance-attribute

config: MkDocsConfig instance-attribute

page: Page | None instance-attribute

mkdocs.livereload.LiveReloadServer

Bases: ThreadingMixIn, WSGIServer

watch(path: str, func: Callable[[], None] | None = None, recursive: bool = True) -> None

Add the 'path' to watched paths, call the function and reload when any file changes under it.

unwatch(path: str) -> None

Stop watching file changes for path. Raises if there was no corresponding watch call.