# 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

```yaml
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
# 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.

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

```yaml
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`:

````markdown
# 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:

1. identify the selected runtime and dependency file;
2. verify whether the package is already available there;
3. confirm version compatibility in primary documentation;
4. describe the exact declaration change;
5. 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.

## Official references

- [Creating your site](https://squidfunk.github.io/mkdocs-material/creating-your-site/)
- [Setting up navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/)
- [Content tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/)
- [Python Markdown extensions](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/)
- [Built-in plugins](https://squidfunk.github.io/mkdocs-material/plugins/)
- [Customization](https://squidfunk.github.io/mkdocs-material/customization/)
- [Publishing](https://squidfunk.github.io/mkdocs-material/publishing-your-site/)
- [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/)