Добавлен навык по 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,150 @@
+# 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/)