grabardm/MTUCI-RAG-Example
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Даниил
2026-09-19 17:25:14 +10:00
parent 34535ac579
commit 7e756c01c2
5 changed files with 336 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
support_files/codex_files/skills/mkdocs-material/SKILL.md
+92
View File
@@ -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/)
support_files/codex_files/skills/mkdocs-material/agents/openai.yaml
+4
View File
@@ -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."
support_files/codex_files/skills/mkdocs-material/references/configuration.md
+150
View File
@@ -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/)
support_files/codex_files/skills/mkdocs-material/references/troubleshooting.md
+88
View File
@@ -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/)