Добавлен навык по 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,88 @@
+# Troubleshooting MkDocs Material
+
+Read this reference when a build, preview, plugin, Markdown extension, theme
+override, asset, link, or deployed site fails or behaves unexpectedly.
+
+## Diagnostic order
+
+1. Capture the exact command, working directory, config path, selected
+   interpreter or image, complete error, and exit code.
+2. Reproduce in the project's established environment. If several configs
+   exist, pass the intended one explicitly with `--config-file`.
+3. Establish a baseline when possible: did the same command fail before the
+   requested change? Keep new failures separate from existing warnings.
+4. Classify the failure as YAML/schema, dependency/plugin, content/navigation,
+   Markdown extension, override/asset, or hosting/base-URL related.
+5. Apply the narrowest correction, rerun the focused command, then rerun the
+   complete project build.
+
+Do not install packages, delete generated output, publish, or rewrite a whole
+configuration merely to probe a failure unless that action is within the
+user-approved scope.
+
+## Symptom guide
+
+| Symptom | First checks | Typical correction |
+|---|---|---|
+| YAML parser error | Reported line plus preceding indentation, tabs, duplicate/misnested keys | Repair the smallest YAML structure and validate again. |
+| `Config value 'plugins'` error | Exact plugin name, active environment, dependency declarations, plugin docs | Correct the key or declare/install a compatible package with authorization. |
+| Page in `nav` is missing | `docs_dir`, spelling/case, suffix, generated-page timing | Make the path relative to `docs_dir` or create the intended page. |
+| Unknown Markdown extension | Active interpreter, extension name, dependency version | Use the documented extension identifier and compatible installed package. |
+| Tabs render as plain text | `pymdownx.tabbed`, indentation, `alternate_style`, companion fences for nested code | Enable/configure the extension and fix page syntax; `content.tabs.link` alone is insufficient. |
+| Override template not found or broken | `theme.custom_dir`, relative path, upstream template name, Material version | Fix the override path or update the minimal block override for the installed version. |
+| CSS/JavaScript missing | Path under `docs_dir`, `extra_css`/`extra_javascript`, browser network errors, instant navigation lifecycle | Correct the asset declaration and reinitialize page-specific JavaScript when required. |
+| Strict build aborts on warnings | First warning, normal-build output, baseline before the change | Fix regressions; report unrelated existing warnings separately instead of hiding them. |
+| Links break only under a hosted subpath | `site_url`, hosting base path, absolute `/...` links, CI artifact layout | Set the real canonical subpath and use generated/internal relative links appropriately. |
+| Preview works but deployed site fails | CI command, dependency versions, config selection, environment variables, case-sensitive paths | Reproduce the production build inputs and correct the differing assumption. |
+
+## Version and environment mismatches
+
+Dependency declarations, installed packages, the command on `PATH`, and a CI
+image can all describe different versions. Capture version evidence from the
+same execution path that fails. With local Python, prefer:
+
+```powershell
+python -m mkdocs --version
+python -m pip show mkdocs-material
+```
+
+Use the project's interpreter in place of generic `python` when one is defined.
+For containers, inspect the Dockerfile/image inputs and run version commands in
+the project image if it already exists. Do not silently fall back to a global
+MkDocs executable.
+
+When current online documentation differs from the installed release, either
+use the installed release's supported form or propose a separately authorized
+upgrade. Label behavior that cannot be verified rather than inventing a key.
+
+## Build warnings and strict mode
+
+`--strict` converts warnings into build failures. It is valuable as a project
+policy or final clean-build gate, but it does not identify which change caused
+an old warning.
+
+1. Run the repository's normal build command and retain its warnings.
+2. Compare with a pre-change run, CI history, or an unchanged revision when
+   available.
+3. Fix warnings introduced by the requested work.
+4. Report unrelated warnings by message and affected path; do not suppress them
+   or expand scope silently.
+5. Run strict mode when the project requires it or after the warning set is
+   understood.
+
+## Preview versus deployment
+
+`mkdocs serve` is a live-reload development server. A successful preview does
+not verify the production base URL, generated artifact, CI dependencies,
+case-sensitive filesystem, caching, redirects, or host configuration. Build the
+site using production-equivalent inputs and inspect the actual publishing
+workflow. Running that workflow still requires authorization because it changes
+external state.
+
+## Official references
+
+- [MkDocs CLI](https://www.mkdocs.org/user-guide/cli/)
+- [MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/)
+- [Material customization](https://squidfunk.github.io/mkdocs-material/customization/)
+- [Material publishing](https://squidfunk.github.io/mkdocs-material/publishing-your-site/)
+- [Material content tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/)