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 ConfigOption
s 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