API参考
注意：API的主要入口是通过插件接收的事件。这些事件的描述链接回此页面。
mkdocs.structure.files.Files
A collection of File objects.
src_paths: dict[str, File]
property
Soft-deprecated, prefer src_uris.
src_uris: Mapping[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
Soft-deprecated, prefer get_file_from_path(path) is not None.
get_file_from_path(path: str) -> File | None
Return a File instance with File.src_uri equal to path.
append(file: File) -> None
Add file to the 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.
It represents how the contents of one file should be populated in the destination site.
A file always has its abs_dest_path (obtained by joining dest_dir and dest_path),
where the dest_dir is understood to be the site directory.
content_bytes/content_string (new in MkDocs 1.6) can always be used to obtain the file's
content. But it may be backed by one of the two sources:
-
A physical source file at
abs_src_path(by default obtained by joiningsrc_dirandsrc_uri).src_diris understood to be the docs directory.Then
content_bytes/content_stringwill read the file atabs_src_path.src_dirshould be populated for real files and should beNonefor generated files. -
Since MkDocs 1.6 a file may alternatively be stored in memory -
content_string/content_bytes.Then
src_dirandabs_src_pathwill remainNone.content_bytes/content_stringneed to be written to, or populated through thecontentargument in the constructor.But
src_uriis still populated for such files as well! The virtual file pretends as if it originated from that path in thedocsdirectory, and other values are derived.
For static files the file is just copied to the destination, and dest_uri equals src_uri.
For Markdown files (determined by the file extension in src_uri) the destination content
will be the rendered content, and dest_uri will have the .html extension and some
additional transformations to the path, based on use_directory_urls.
src_uri: str
instance-attribute
The pure path (always '/'-separated) of the source file relative to the source directory.
generated_by: str | None = None
class-attribute
instance-attribute
If not None, indicates that a plugin generated this file on the fly.
The value is the plugin's entrypoint name and can be used to find the plugin by key in the PluginCollection.
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.
src_dir: str | None = src_dir
instance-attribute
The OS path of the top-level directory that the source file originates from.
Assumed to be the docs_dir; not populated for generated files.
dest_dir: str = dest_dir
instance-attribute
The OS path of the destination directory (top-level site_dir) that the file should be copied to.
use_directory_urls: bool = use_directory_urls
instance-attribute
Whether directory URLs ('foo/') should be used or not ('foo.html').
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. Non-Markdown files retain their
original path.
inclusion: InclusionLevel = inclusion
class-attribute
instance-attribute
Whether the file will be excluded from the built site.
name = cached_property(_get_stem)
class-attribute
instance-attribute
Return the name of the file without its extension.
dest_uri = cached_property(_get_dest_path)
class-attribute
instance-attribute
The pure path (always '/'-separated) of the destination file relative to the destination directory.
url = cached_property(_get_url)
class-attribute
instance-attribute
The URI of the destination file relative to the destination directory as a string.
abs_src_path: str | None
cached
property
The absolute concrete path of the source file. Will use backslashes on Windows.
Note: do not use this path to read the file, prefer content_bytes/content_string.
abs_dest_path: str
cached
property
The absolute concrete path of the destination file. Will use backslashes on Windows.
content_bytes: bytes
property
writable
Get the content of this file as a bytestring.
May raise if backed by a real file (abs_src_path) if it cannot be read.
If used as a setter, it defines the content of the file, and abs_src_path becomes unset.
content_string: str
property
writable
Get the content of this file as a string. Assumes UTF-8 encoding, may raise.
May also raise if backed by a real file (abs_src_path) if it cannot be read.
If used as a setter, it defines the content of the file, and abs_src_path becomes unset.
generated(config: MkDocsConfig, src_uri: str, *, content: str | bytes | None = None, abs_src_path: str | None = None, inclusion: InclusionLevel = InclusionLevel.UNDEFINED) -> File
classmethod
Create a virtual file, backed either by in-memory content or by a file at abs_src_path.
It will pretend to be a file in the docs dir at src_uri.
edit_uri() -> str | None
A path relative to the source repository to use for the "edit" button.
Defaults to src_uri and can be overwritten.
For generated files this should be set to None.
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