Configuration and content

Read this reference when creating a site or changing mkdocs.yml, content, navigation, Material features, Markdown extensions, plugins, assets, or theme overrides.

Choose the project path

Situation	Evidence to inspect	Working rule
Existing local-Python site	lock/requirements file, virtual environment, scripts, CI	Use the project interpreter and its declared command.
Existing containerized site	Dockerfile, Compose file, task runner, CI	Reuse the project image; the official image may lack its plugins.
New site with Python	requested package manager and supported Python version	Create a virtual environment; add dependencies only with authorization.
New site with Docker	requested container workflow and target platform	Pin the image major version and document the exact command.

For an existing environment, record versions with its own interpreter, for example python -m mkdocs --version and python -m pip show mkdocs-material. Do not substitute a global interpreter. For a container workflow, obtain the version through the established image or its lock/build inputs; building or pulling an image may require authorization.

Minimal configuration

site_name: Project documentation
site_url: https://example.org/project/

theme:
  name: material

Set site_url to the real canonical deployment URL, including a repository or other subpath. Do not invent it when the hosting target is unknown. It affects canonical URLs, sitemap generation, and features that depend on absolute site context.

Coupled settings

Setting	Check together with
`docs_dir`	All `nav` paths and asset locations; paths are relative to the documentation source directory.
`nav`	Actual Markdown files, desired ordering, translations, generated pages, and plugins that add navigation.
`theme.features`	Material version and feature compatibility; preserve existing feature flags.
`markdown_extensions`	Extension package, required companion extensions, and syntax used in pages.
`plugins`	Installed distributions and existing plugin config. When `plugins` is explicitly set, retain `search` if search is desired.
`extra_css` / `extra_javascript`	Files under the documentation source tree and behavior under instant navigation.
`theme.custom_dir`	Directory relative to the configuration, override paths matching the active theme, and compatibility after upgrades.
`site_url`	Production hostname/subpath, canonical links, sitemap, social cards, and deployment config.

Use the Material YAML schema when editor support is useful:

# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json

Schema validation helps find misspelled keys but does not prove that third-party plugins are installed or that the selected runtime supports an option.

Complete content-tabs example

This example creates docs/guide.md, places it in navigation, and enables the syntax that renders content tabs. content.tabs.link is optional behavior for synchronizing tabs with equal labels; it does not enable the syntax by itself.

.
|-- docs/
|   |-- index.md
|   `-- guide.md
`-- mkdocs.yml

site_name: Example documentation
site_url: https://example.org/docs/

theme:
  name: material
  features:
    - content.tabs.link

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

nav:
  - Home: index.md
  - Guide: guide.md

docs/guide.md:

# Guide

=== "Linux"

    ```bash
    python -m pip install package-name
    ```

=== "Windows"

    ```powershell
    py -m pip install package-name
    ```

If the project sets docs_dir: documentation, create documentation/guide.md; the nav value remains guide.md because navigation paths are relative to docs_dir.

Dependencies and installation authority

Material installs compatible MkDocs, Python-Markdown, Pygments, and PyMdown Extensions dependencies, but third-party plugins still need their own packages. Before proposing a dependency change:

identify the selected runtime and dependency file;
verify whether the package is already available there;
confirm version compatibility in primary documentation;
describe the exact declaration change;
install, lock, pull, or build only when authorized.

Prefer a current-major constraint or the project's existing lock strategy over an unconstrained upgrade. Do not copy an option from current documentation into an older installed version without checking support.

Preview, build, and publishing preparation

Preview content with the project command or mkdocs serve; verify navigation, narrow screens, code blocks, tabs, links, and custom assets when relevant.
Build with the established command before claiming readiness. Run a baseline build before edits when attributing warnings matters.
Inspect CI and hosting configuration to learn the production URL, base path, dependency installation, and publish command.
mkdocs gh-deploy pushes generated content. Do not run it merely because the user asked to prepare or verify a site.

5.8 KiB Raw Blame History