Skip to content

mkdocs

mkdocs documentation

toolroom._stubs.mkdocs.Mkdocs

Bases: Tool[_R]

Build

Bases: Tool[_R2]

__call__ 

__call__(
    *,
    clean: Flag = ...,
    config_file: Value = ...,
    quiet: Flag = ...,
    site_dir: Value = ...,
    strict: Flag = ...,
    theme: Theme | Sequence[Theme] | None = ...,
    use_directory_urls: Flag = ...,
    verbose: Flag = ...,
    **flags: Any,
) -> _R2

Build the MkDocs documentation.

Parameters:

Name Type Description Default
clean Flag

Remove old files from the site_dir before building (the default). Defaults on — clean=off emits --dirty.

 ...
config_file Value

Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin.

 ...
quiet Flag

Silence warnings.

 ...
site_dir Value

The directory to output the result of the documentation build.

 ...
strict Flag

Enable strict mode. This will cause MkDocs to abort the build on any warnings. strict=off emits --no-strict.

 ...
theme Theme | Sequence[Theme] | None

The theme to use when building your documentation.

 ...
use_directory_urls Flag

Use directory URLs when building pages (the default). use_directory_urls=off emits --no-directory-urls.

 ...
verbose Flag

Enable verbose output.

 ...

GhDeploy

Bases: Tool[_R2]

__call__ 

__call__(
    *,
    clean: Flag = ...,
    config_file: Value = ...,
    force: Flag = ...,
    ignore_version: Flag = ...,
    message: Value = ...,
    no_history: Flag = ...,
    quiet: Flag = ...,
    remote_branch: Value = ...,
    remote_name: Value = ...,
    shell: Flag = ...,
    site_dir: Value = ...,
    strict: Flag = ...,
    theme: Theme | Sequence[Theme] | None = ...,
    use_directory_urls: Flag = ...,
    verbose: Flag = ...,
    **flags: Any,
) -> _R2

Deploy your documentation to GitHub Pages.

Parameters:

Name Type Description Default
clean Flag

Remove old files from the site_dir before building (the default). Defaults on — clean=off emits --dirty.

 ...
config_file Value

Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin.

 ...
force Flag

Force the push to the repository.

 ...
ignore_version Flag

Ignore check that build is not being deployed with an older version of MkDocs.

 ...
message Value

A commit message to use when committing to the GitHub Pages remote branch. Commit {sha} and MkDocs {version} are available as expansions.

 ...
no_history Flag

Replace the whole Git history with one new commit.

 ...
quiet Flag

Silence warnings.

 ...
remote_branch Value

The remote branch to commit to for GitHub Pages. This overrides the value specified in config.

 ...
remote_name Value

The remote name to commit to for GitHub Pages. This overrides the value specified in config.

 ...
shell Flag

Use the shell when invoking Git.

 ...
site_dir Value

The directory to output the result of the documentation build.

 ...
strict Flag

Enable strict mode. This will cause MkDocs to abort the build on any warnings. strict=off emits --no-strict.

 ...
theme Theme | Sequence[Theme] | None

The theme to use when building your documentation.

 ...
use_directory_urls Flag

Use directory URLs when building pages (the default). use_directory_urls=off emits --no-directory-urls.

 ...
verbose Flag

Enable verbose output.

 ...

New

Bases: Tool[_R2]

__call__ 

__call__(
    project_directory: str | PathLike[str],
    /,
    *args: str | PathLike[str],
    quiet: Flag = ...,
    verbose: Flag = ...,
    **flags: Any,
) -> _R2

Create a new MkDocs project.

Parameters:

Name Type Description Default
quiet Flag

Silence warnings.

 ...
verbose Flag

Enable verbose output.

 ...

Serve

Bases: Tool[_R2]

__call__ 

__call__(
    *,
    clean: Flag = ...,
    config_file: Value = ...,
    dev_addr: Value = ...,
    dirty: Flag = ...,
    dirtyreload: Flag = ...,
    livereload: Flag = ...,
    no_livereload: Flag = ...,
    open: Flag = ...,
    quiet: Flag = ...,
    strict: Flag = ...,
    theme: Theme | Sequence[Theme] | None = ...,
    use_directory_urls: Flag = ...,
    verbose: Flag = ...,
    watch: Value = ...,
    watch_theme: Flag = ...,
    **flags: Any,
) -> _R2

Run the builtin development server.

Parameters:

Name Type Description Default
clean Flag

Build the site without any effects of mkdocs serve - pure mkdocs build, then serve. Added in 1.5.0.

 ...
config_file Value

Provide a specific MkDocs config. This can be a file name, or '-' to read from stdin.

 ...
dev_addr Value

IP address and port to serve documentation locally (default: localhost:8000).

 ...
dirty Flag

Only re-build files that have changed. Added in 1.5.0.

 ...
no_livereload Flag

Disable the live reloading in the development server. Added in 1.5.0.

 ...
open Flag

Open the website in a Web browser after the initial build finishes. Added in 1.6.0.

 ...
quiet Flag

Silence warnings.

 ...
strict Flag

Enable strict mode. This will cause MkDocs to abort the build on any warnings. strict=off emits --no-strict.

 ...
theme Theme | Sequence[Theme] | None

The theme to use when building your documentation.

 ...
use_directory_urls Flag

Use directory URLs when building pages (the default). use_directory_urls=off emits --no-directory-urls.

 ...
verbose Flag

Enable verbose output.

 ...
watch Value

A directory or file to watch for live reloading. Can be supplied multiple times. May be repeated: a list emits the flag once per item.

 ...
watch_theme Flag

Include the theme in list of files to watch for live reloading. Ignored when live reload is not used.

 ...

__call__ 

__call__(
    *args: str | PathLike[str],
    color: Flag = ...,
    quiet: Flag = ...,
    verbose: Flag = ...,
    **flags: Any,
) -> _R

MkDocs - Project documentation with Markdown.

Parameters:

Name Type Description Default
color Flag

Force enable or disable color and wrapping for the output. Gone since 1.6.1.

 ...
quiet Flag

Silence warnings. Gone since 1.6.1.

 ...
verbose Flag

Enable verbose output. Gone since 1.6.1.

 ...

flags 

flags(
    *,
    color: Flag = ...,
    quiet: Flag = ...,
    verbose: Flag = ...,
    **flags: Any,
) -> Self

Bind tool-level global options before the subcommand.

tools.docker.flags(host=...) puts a tool's own options ahead of the verb, where they belong.