Добавлен навык по MK-Docs

2026-09-19 17:25:14 +10:00
parent 34535ac579
commit 7e756c01c2
5 changed files with 336 additions and 3 deletions
@@ -0,0 +1,92 @@
+---
+name: mkdocs-material
+description: Use when creating, configuring, editing, building, publishing, or troubleshooting MkDocs documentation sites that use the Material theme, including mkdocs.yml, navigation, plugins, Markdown extensions, theme overrides, and build warnings.
+---
+
+# MkDocs Material
+
+## Overview
+
+Preserve the project's documentation conventions, verify version-sensitive
+options against the selected environment, and make the smallest complete
+change. Treat configuration, Markdown content, dependencies, assets, and build
+commands as one system.
+
+## Establish project context
+
+1. Locate `mkdocs.yml` and `mkdocs.yaml` plus repository instructions,
+   dependency files, Dockerfiles, CI workflows, and documentation scripts.
+2. If several configs exist, resolve which site the request targets from the
+   user's wording and repository evidence. Ask before editing when it remains
+   ambiguous.
+3. Read the chosen config for `docs_dir`, `site_dir`, `theme`, `nav`, plugins,
+   Markdown extensions, assets, hooks, and overrides. Inspect the referenced
+   paths rather than assuming the default layout.
+4. Identify the established execution path: project virtual environment,
+   package-manager command, container, or CI task. Query actual installed
+   versions when behavior depends on them; a requirement declaration alone
+   does not prove the active version.
+
+## Make changes
+
+- Use the relevant official Material for MkDocs and MkDocs pages for unfamiliar
+  or version-sensitive keys. Never invent a configuration option.
+- Preserve existing YAML style and entries. Keep `nav` paths, `docs_dir`,
+  Markdown files, plugins, extensions, `extra_css`, `extra_javascript`, and
+  `theme.custom_dir` consistent.
+- Distinguish related features. For example, content tabs require
+  `pymdownx.tabbed`; `content.tabs.link` only synchronizes tabs with equal
+  labels. Read [configuration.md](references/configuration.md) for setup,
+  content, navigation, extensions, plugins, assets, or overrides.
+- Identify missing packages and the file that should declare them. Installing
+  or upgrading dependencies changes the environment: do it only when the user
+  requested or approved it.
+- Publishing and deployment change external state. Preparing or inspecting a
+  publish workflow does not authorize running it.
+
+## Verify
+
+Run the project's established command from the directory and environment it
+expects. Start with a normal build when the baseline is unknown. Use
+`mkdocs build --strict` when the project already requires strict builds or after
+warnings have been classified. Separate failures introduced by the requested
+change from pre-existing warnings and report both.
+
+Use `mkdocs serve` only for local preview; it is not a production server or
+deployment check. When a build fails or output differs between preview and
+hosting, read [troubleshooting.md](references/troubleshooting.md).
+
+## Quick reference
+
+Prefer repository scripts over these generic commands.
+
+| Intent | Local environment | Official image |
+|---|---|---|
+| Create in current directory | `mkdocs new .` | `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .` |
+| Preview | `mkdocs serve` | `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material` |
+| Build | `mkdocs build` | `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build` |
+| Treat warnings as errors | `mkdocs build --strict` | append `build --strict` to the project container command |
+
+Use `--config-file PATH` when running outside the config directory. Adapt
+volume syntax to the active shell and reuse a project Dockerfile when it adds
+plugins not present in the official image.
+
+## Common mistakes
+
+| Mistake | Correction |
+|---|---|
+| Editing the first config found | Resolve the intended site and execution path first. |
+| Replacing whole YAML sections | Merge the requested entry and preserve unrelated settings. |
+| Adding a plugin or extension key only | Confirm its package and compatible version in the project environment. |
+| Using `content.tabs.link` to enable tabs | Enable `pymdownx.tabbed`; add linking only if synchronized labels are wanted. |
+| Treating every strict warning as a regression | Compare with the baseline and attribute warnings. |
+| Treating `serve` as publishing validation | Build the static site and inspect the actual deployment workflow. |
+
+## Official entry points
+
+- [Installation](https://squidfunk.github.io/mkdocs-material/getting-started/)
+- [Creating a site](https://squidfunk.github.io/mkdocs-material/creating-your-site/)
+- [Material setup](https://squidfunk.github.io/mkdocs-material/setup/)
+- [Customization](https://squidfunk.github.io/mkdocs-material/customization/)
+- [MkDocs CLI](https://www.mkdocs.org/user-guide/cli/)
+- [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/)