From 7e756c01c289511f2a99e65122c370783e97c1d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=B0=D0=BD=D0=B8=D0=B8=D0=BB?= Date: Sat, 19 Sep 2026 17:25:14 +1000 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=20=D0=BD=D0=B0=D0=B2=D1=8B=D0=BA=20=D0=BF=D0=BE=20MK-Doc?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 5 +- .../skills/mkdocs-material/SKILL.md | 92 +++++++++++ .../skills/mkdocs-material/agents/openai.yaml | 4 + .../references/configuration.md | 150 ++++++++++++++++++ .../references/troubleshooting.md | 88 ++++++++++ 5 files changed, 336 insertions(+), 3 deletions(-) create mode 100644 support_files/codex_files/skills/mkdocs-material/SKILL.md create mode 100644 support_files/codex_files/skills/mkdocs-material/agents/openai.yaml create mode 100644 support_files/codex_files/skills/mkdocs-material/references/configuration.md create mode 100644 support_files/codex_files/skills/mkdocs-material/references/troubleshooting.md diff --git a/.env.example b/.env.example index 0b486cc..b7c0558 100644 --- a/.env.example +++ b/.env.example @@ -1,7 +1,6 @@ # Полные URL опубликованных webhook n8n -N8N_CHAT_WEBHOOK_URL=https://your-n8n-host/webhook/126bdb74-0630-415d-a8f7-6f699eac1a2c -N8N_UPLOAD_WEBHOOK_URL=https://your-n8n-host/webhook/993d3a50-19a7-4c64-9d36-67c0ced130dd - +N8N_CHAT_WEBHOOK_URL=https://your-n8n-host/webhook/126 +N8N_UPLOAD_WEBHOOK_URL=https://your-n8n-host/webhook/993 # Время ожидания ответа в секундах N8N_CHAT_TIMEOUT_SECONDS=60 N8N_UPLOAD_TIMEOUT_SECONDS=120 diff --git a/support_files/codex_files/skills/mkdocs-material/SKILL.md b/support_files/codex_files/skills/mkdocs-material/SKILL.md new file mode 100644 index 0000000..dad0f74 --- /dev/null +++ b/support_files/codex_files/skills/mkdocs-material/SKILL.md @@ -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/) diff --git a/support_files/codex_files/skills/mkdocs-material/agents/openai.yaml b/support_files/codex_files/skills/mkdocs-material/agents/openai.yaml new file mode 100644 index 0000000..8c2f0b6 --- /dev/null +++ b/support_files/codex_files/skills/mkdocs-material/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "MkDocs Material" + short_description: "Build and maintain MkDocs Material sites" + default_prompt: "Use $mkdocs-material to configure and verify this documentation site." diff --git a/support_files/codex_files/skills/mkdocs-material/references/configuration.md b/support_files/codex_files/skills/mkdocs-material/references/configuration.md new file mode 100644 index 0000000..569fea8 --- /dev/null +++ b/support_files/codex_files/skills/mkdocs-material/references/configuration.md @@ -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/) diff --git a/support_files/codex_files/skills/mkdocs-material/references/troubleshooting.md b/support_files/codex_files/skills/mkdocs-material/references/troubleshooting.md new file mode 100644 index 0000000..e9b6c6b --- /dev/null +++ b/support_files/codex_files/skills/mkdocs-material/references/troubleshooting.md @@ -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/)