diff --git a/.cursor/prompts/documentation-review.md b/.cursor/prompts/documentation-review.md new file mode 100644 index 0000000..01a25c1 --- /dev/null +++ b/.cursor/prompts/documentation-review.md @@ -0,0 +1,80 @@ +Review documentation changes for compliance with this repository's rules. + +Context: +- This repository contains Hugo-based product documentation. +- Review the changed documentation files, and inspect nearby related files when needed. +- If the reviewed page describes product or module behavior, verify the statements against the relevant source code, configuration, schemas, examples, or adjacent documentation. Do not guess functionality. +- If a rule is not applicable to the changed files, explicitly skip it instead of forcing a finding. + +Primary rule sources: +- `.cursor/rules/docs/global-style.mdc` +- `.cursor/rules/docs/terminology.mdc` +- `.cursor/rules/docs/refs-editorial-policy-full.mdc` +- `.cursor/rules/docs/refs-glossary-full.mdc` +- `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc` + +Apply additional rules when relevant: +- `.cursor/rules/docs/ru-en-parity.mdc` for EN/RU pairs, `.ru.md` naming, and localized media. +- `.cursor/rules/docs/hugo-shortcodes.mdc` for `alert`, `tabs`, `details`, and shortcode usage. +- `.cursor/rules/docs/frontmatter-links-media.mdc` for front matter, related links, and media placement. +- `.cursor/rules/docs/crd-translation-files.mdc` for `crds/doc-ru-*.yaml` translation files. +- `.cursor/rules/docs/openapi-x-doc.mdc` for `openapi/**/*.yaml` and `x-doc-*` fields. + +Review checklist: + +1. Accuracy and consistency +- Check that the documentation matches the actual behavior described by the code, configuration, schema, or examples. +- Flag claims that are unsupported, outdated, misleading, or contradicted by the implementation. +- Flag missing prerequisites, caveats, limits, or version-sensitive behavior when they are necessary for safe use. + +2. Editorial and style compliance +- Check compliance with `.cursor/rules/docs/refs-editorial-policy-full.mdc` and `.cursor/rules/docs/global-style.mdc`. +- Check for concise technical wording, meaningful link anchors, correct emphasis, and actionable instructions. +- For Russian instructional text, require imperative "вы"-form. +- For docs pages, do not allow first-level headings (`#`). Minimum heading level is `##`. + +3. Terminology compliance +- Check compliance with `.cursor/rules/docs/terminology.mdc` and `.cursor/rules/docs/refs-glossary-full.mdc`. +- Flag forbidden or inconsistent terms. +- Require exact approved product naming. +- Require `d8 k` instead of `kubectl` in command examples unless the repository rule clearly does not apply to that case. + +4. Markdown, Hugo, and code examples +- Every fenced code block must have an explicit language tag. +- The language tag must be present in `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`. +- Markdown ordered lists must use `1.` for every item, not `1.`, `2.`, `3.`. +- Check Hugo shortcode usage when present. +- Check that YAML, JSON, shell, and other examples are syntactically plausible and internally consistent. +- Check that commands, flags, paths, field names, and HTTP codes are formatted as inline code where appropriate. + +5. Localization and parity +- RU files must use the `.ru.md` suffix only. +- If a change is relevant to both EN and RU pages, check whether both sides were updated consistently. +- Flag semantic divergence between paired EN/RU pages when it appears unintentional. +- Check localized media naming when media is language-specific. + +6. Front matter, links, and structure +- Check required front matter fields when present and applicable. +- Check that links are concise, meaningful, and not broken by obvious path mistakes. +- Flag manual "related links" sections when front matter rules require structured related links instead. + +7. Schema-specific rules +- For CRD translation files, check path naming, translation scope, and YAML structure. +- For OpenAPI docs, check `x-doc-*` usage, example structure, and description conventions. + +Severity model: +- `critical`: incorrect or dangerous guidance, a behavioral contradiction, or a change that can cause user harm or a broken workflow. +- `major`: a strong rules violation, missing important context, broken parity, or a likely user-facing documentation defect. +- `minor`: wording, formatting, consistency, or low-risk style issues. + +Output requirements: +- Report findings first, ordered by severity: `critical`, `major`, `minor`. +- Only report real issues. Do not pad the review. +- For each finding, provide: + - severity; + - file path; + - exact issue; + - why it matters; + - specific proposed fix. +- If there are no findings, say: `No issues found.` +- After findings, add a short section named `Residual risk` with any unverified assumptions or areas you could not validate from the available sources. diff --git a/.cursor/rules/docs/frontmatter-links-media.mdc b/.cursor/rules/docs/frontmatter-links-media.mdc new file mode 100644 index 0000000..864eca3 --- /dev/null +++ b/.cursor/rules/docs/frontmatter-links-media.mdc @@ -0,0 +1,45 @@ +--- +description: Front matter, links, and media rules +globs: content/**/*.md +alwaysApply: false +--- + +# Front Matter + +- Use YAML front matter in page header. +- `title`: required. +- If `title` is missing, generate it from page purpose and module context. +- For `README` title use template: + - RU file (`README.ru.md`): `Модуль ` + - EN file (`README.md`): `Module ` +- `` must be the exact value from `module.yaml.name` (lowercase Kebab Case), without case/style changes. +- `linkTitle`: optional, and applicable only to Hugo pages. +- Do not use `linkTitle` in Jekyll page metadata. +- `description`: required, concise, unique, and not a copy of `title`. +- If `description` is missing, generate it automatically from page purpose and key context. +- Do not set top-level front matter `url`; it is generated automatically. +- `moduleStatus` in README front matter is deprecated and must not be used. +- If `moduleStatus` is present: + - remove it from README front matter; + - validate that lifecycle status is set in `module.yaml` via `stage`; + - if README `moduleStatus` conflicts with `module.yaml.stage`, ask user before changing lifecycle value. + +# Related Links + +- For Hugo pages, use related links as `params.relatedLinks` in front matter. +- For Jekyll pages, use related links as top-level `relatedLinks` in front matter (without `params`). +- Do not add manual "Related links" or "Related pages" sections in Markdown body. +- The related links block is rendered automatically from front matter. +- If a `relatedLinks` item has no `url`, the link must not be rendered. +- If `title` is missing, render only module links like `/modules//`. + +# Link Rules + +- Same module docs links must be relative (`cr.html`, `usage.html`). +- Other module links must be absolute without domain (`/modules//...`). +- Deckhouse Kubernetes Platform docs links must be absolute without domain (`/products/kubernetes-platform/documentation/v1/...`). + +# Media Rules + +- Store images, PDFs, and media only in `docs/` or its subdirectories. +- Use relative links for files within the same module repository. diff --git a/.cursor/rules/docs/global-style.mdc b/.cursor/rules/docs/global-style.mdc new file mode 100644 index 0000000..8fa37de --- /dev/null +++ b/.cursor/rules/docs/global-style.mdc @@ -0,0 +1,53 @@ +--- +description: Global style rules for module docs +alwaysApply: true +--- + +# Documentation Style + +- Write concise technical text with clear user value. +- The full editorial policy and glossary are published at https://pp.flant.ru/llms.txt and are normative. + Fetch and apply them before writing or reviewing documentation text. +- Apply editorial policy directly in text: + - use inline code for parameters, module names, commands, file paths, and HTTP codes; + - do not overuse inline code for resource type names in narrative text; + - use meaningful link anchors (avoid generic "here" or "тут"); + - keep links concise and readable; + - prefer bold for emphasis; use italics rarely. +- Use inline code for parameters, commands, file paths, and HTTP codes. +- Use fenced code blocks with a mandatory language tag. +- The language tag must be from `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`. +- If a needed language is absent in that list, use `text` or `plain`. +- Prefer short paragraphs and structured lists. +- For emphasis, prefer bold text; avoid unnecessary italic text. +- Use Hugo alert shortcode levels: `info`, `warning`, `danger`. +- For lists, keep punctuation and casing consistent within one list. +- In Markdown ordered lists, use `1.` for every item instead of `1.`, `2.`, `3.`. +- Keep instructions actionable and testable. +- In command examples use `d8 k` instead of `kubectl` (syntax is the same). +- YAML snippets and YAML files must be syntactically valid. + +# Russian Text Style + +- In Russian instructional text, always use the imperative (вы-форма), not the first-person plural (мы-форма). + - Use «создайте», not «создаем»; + - Use «нажмите», not «нажимаем»; + - Use «перейдите», not «переходим»; + - Use «подключитесь», not «подключаемся»; + - Use «введите», not «вводим». +- This applies to all step-by-step instructions, quickstart guides, and procedural text. + +# Markdown And Hugo + +- Documentation is rendered by Hugo. +- Keep Markdown valid and deterministic for static rendering. +- Use only supported shortcodes and avoid custom undocumented markup. +- Do not use first-level heading (`# ...`) in documentation files. +- Minimum allowed heading level is second-level (`## ...`). +- If a local checklist conflicts with full policy text, follow https://pp.flant.ru/llms.txt. + +# Release notes (`content/documentation/release-notes/`) + +- Under a heading (`##`, `###`, or `####`), if the only body content is a single top-level bullet (`-` or `*`), do not use a list: write one or more plain paragraphs instead (merge the bullet text with any lead-in sentence on the same topic). +- If there is a lead-in paragraph and exactly one bullet, merge them into continuous prose and drop the list marker. +- When there are two or more top-level bullets under the same heading, keep a Markdown list. diff --git a/.cursor/rules/docs/hugo-shortcodes.mdc b/.cursor/rules/docs/hugo-shortcodes.mdc new file mode 100644 index 0000000..1dbde4d --- /dev/null +++ b/.cursor/rules/docs/hugo-shortcodes.mdc @@ -0,0 +1,44 @@ +--- +description: Allowed Hugo shortcodes and partials +globs: content/**/*.md +alwaysApply: false +--- + +# Hugo Shortcodes + +- Use `alert` shortcode with levels `info`, `warning`, `danger`. +- Use `tabs` for multi-option instructions. +- Use `details` for collapsible sections with long examples. +- In fenced code blocks, language identifier is mandatory and must be listed in `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`. + +Example `alert`: + +```go-html-template +{{< alert level="warning" >}} +The warning message... +{{< /alert >}} +``` + +Example `tabs`: + +```go-html-template +{{< tabs name="tabs_uniq_name" >}} +{{% tab name="Tab caption 1" %}}Tab 1 Content {{% /tab %}} +{{% tab name="Tab caption 2" %}}Tab 2 Content {{% /tab %}} +{{< /tabs >}} +``` + +Example `details`: + +```go-html-template +{{% details "Summary..."%}} +## Markdown content + +Markdown content... +{{% /details %}} +``` + +# Templates And Partials + +- In templates, `alert` and `details` partials are allowed. +- Keep shortcode syntax exact to avoid broken page rendering. diff --git a/.cursor/rules/docs/hugo-supported-codeblock-languages.mdc b/.cursor/rules/docs/hugo-supported-codeblock-languages.mdc new file mode 100644 index 0000000..f5b1d12 --- /dev/null +++ b/.cursor/rules/docs/hugo-supported-codeblock-languages.mdc @@ -0,0 +1,301 @@ +--- +description: Hugo supported code block language identifiers +alwaysApply: true +--- + +# Hugo and Jekyll Supported Code Block Languages + +The full language identifier list below is part of Cursor rules. + +# Supported code block languages + +This is the full list of language identifiers (aliases included) for Hugo syntax highlighting (Chroma), based on Hugo docs. It can be use for Jekyll also. + +Source: https://gohugo.io/content-management/syntax-highlighting/#languages + +Use one of these identifiers as `LANG` in fenced code blocks. + +- `abap` +- `abnf` +- `as`, `actionscript` +- `as3`, `actionscript3` +- `ada`, `ada95`, `ada2005` +- `agda` +- `al` +- `alloy` +- `ng2` +- `antlr` +- `apacheconf`, `aconf`, `apache` +- `apl` +- `applescript` +- `aql` +- `arduino` +- `armasm` +- `atl` +- `autohotkey`, `ahk` +- `autoit` +- `awk`, `gawk`, `mawk`, `nawk` +- `ballerina` +- `bash`, `sh`, `ksh`, `zsh`, `shell` +- `bash-session`, `console`, `shell-session` +- `bat`, `batch`, `dosbatch`, `winbatch` +- `beef` +- `bib`, `bibtex` +- `bicep` +- `blitzbasic`, `b3d`, `bplus` +- `bnf` +- `bqn` +- `brainfuck`, `bf` +- `c` +- `csharp`, `c#` +- `cpp`, `c++` +- `c3` +- `caddyfile`, `caddy` +- `caddyfile-directives`, `caddyfile-d`, `caddy-d` +- `capnp` +- `cassandra`, `cql` +- `ceylon` +- `cfengine3`, `cf3` +- `cfs` +- `chai`, `chaiscript` +- `chapel`, `chpl` +- `cheetah`, `spitfire` +- `clojure`, `clj`, `edn` +- `cmake` +- `cobol` +- `coffee-script`, `coffeescript`, `coffee` +- `common-lisp`, `cl`, `lisp` +- `coq` +- `core` +- `cr`, `crystal` +- `css` +- `csv` +- `cue` +- `cython`, `pyx`, `pyrex` +- `d` +- `dart` +- `dax` +- `desktop`, `desktop_entry` +- `devicetree`, `dts` +- `diff`, `udiff` +- `django`, `jinja` +- `zone`, `bind` +- `docker`, `dockerfile`, `containerfile` +- `dtd` +- `dylan` +- `ebnf` +- `elixir`, `ex`, `exs` +- `elm` +- `emacs`, `elisp`, `emacs-lisp` +- `erlang` +- `factor` +- `fennel`, `fnl` +- `fish`, `fishshell` +- `forth` +- `fortran`, `f90` +- `fortranfixed` +- `fsharp` +- `gas`, `asm` +- `gdscript`, `gd` +- `gdscript3`, `gd3` +- `gemtext`, `gmi`, `gmni`, `gemini` +- `genshi`, `kid`, `xml+genshi`, `xml+kid` +- `html+genshi`, `html+kid` +- `genshitext` +- `cucumber`, `Cucumber`, `gherkin`, `Gherkin` +- `gleam` +- `glsl` +- `gnuplot` +- `go`, `golang` +- `go-html-template` +- `go-template` +- `go-text-template` +- `graphql`, `graphqls`, `gql` +- `groff`, `nroff`, `man` +- `groovy` +- `handlebars`, `hbs` +- `hare` +- `haskell`, `hs` +- `hx`, `haxe`, `hxsl` +- `hcl` +- `hexdump` +- `hlb` +- `hlsl` +- `holyc` +- `html` +- `http` +- `hylang` +- `idris`, `idr` +- `igor`, `igorpro` +- `ini`, `cfg`, `dosini` +- `io` +- `iscdhcpd` +- `j` +- `janet` +- `java` +- `js`, `javascript` +- `json` +- `jsonata` +- `jsonnet` +- `julia`, `jl` +- `jungle` +- `kak`, `kakoune`, `kakrc`, `kakscript` +- `kdl` +- `kotlin` +- `lean4`, `lean` +- `lighty`, `lighttpd` +- `llvm` +- `lox` +- `lua`, `luau` +- `make`, `makefile`, `mf`, `bsdmake` +- `mako` +- `md`, `mkd` +- `mess` +- `mason` +- `materialize`, `mzsql` +- `mathematica`, `mma`, `nb` +- `matlab` +- `mcfunction`, `mcf` +- `meson`, `meson.build` +- `metal` +- `minizinc`, `MZN`, `mzn` +- `mlir` +- `modelica` +- `modula2`, `m2` +- `mojo` +- `monkeyc` +- `moonbit`, `mbt` +- `moonscript`, `moon` +- `morrowind`, `mwscript` +- `myghty` +- `mysql`, `mariadb` +- `nasm` +- `natural` +- `ndisasm` +- `newspeak` +- `nginx` +- `nim`, `nimrod` +- `nixos`, `nix` +- `nsis`, `nsi`, `nsh` +- `nu` +- `objective-c`, `objectivec`, `obj-c`, `objc` +- `objectpascal` +- `ocaml` +- `octave` +- `odin` +- `ones`, `onesenterprise`, `1S`, `1S:Enterprise` +- `openedge`, `abl`, `progress`, `openedgeabl` +- `openscad` +- `org`, `orgmode` +- `pacmanconf` +- `perl`, `pl` +- `php`, `php3`, `php4`, `php5` +- `phtml` +- `pig` +- `pkgconfig` +- `plpgsql` +- `text`, `plain`, `no-highlight` +- `plutus-core`, `plc` +- `pony` +- `postgresql`, `postgres` +- `postscript`, `postscr` +- `pov` +- `powerquery`, `pq` +- `powershell`, `posh`, `ps1`, `psm1`, `psd1`, `pwsh` +- `prolog` +- `promela` +- `promql` +- `java-properties` +- `protobuf`, `proto` +- `txtpb` +- `prql` +- `psl` +- `puppet` +- `python`, `py`, `sage`, `python3`, `py3`, `starlark` +- `python2`, `py2` +- `qbasic`, `basic` +- `qml`, `qbs` +- `splus`, `s`, `r` +- `racket`, `rkt` +- `ragel` +- `perl6`, `pl6`, `raku` +- `jsx`, `react` +- `reason`, `reasonml` +- `registry` +- `rego` +- `rst`, `rest`, `restructuredtext` +- `rexx`, `arexx` +- `rgbasm` +- `ring` +- `SQLRPGLE`, `RPG IV` +- `spec` +- `rb`, `ruby`, `duby` +- `rust`, `rs` +- `sas` +- `sass` +- `scala` +- `scheme`, `scm` +- `scilab` +- `scss` +- `sed`, `gsed`, `ssed` +- `sieve` +- `smali` +- `smalltalk`, `squeak`, `st` +- `smarty` +- `snbt` +- `snobol` +- `sol`, `solidity` +- `sp` +- `sparql` +- `sql` +- `squidconf`, `squid.conf`, `squid` +- `sml` +- `stas` +- `stylus` +- `svelte` +- `swift` +- `systemd` +- `systemverilog`, `sv` +- `tablegen` +- `tal`, `uxntal` +- `tasm` +- `tcl` +- `tcsh`, `csh` +- `termcap` +- `terminfo` +- `terraform`, `tf`, `hcl` +- `tex`, `latex` +- `thrift` +- `toml` +- `tradingview`, `tv` +- `tsql`, `t-sql` +- `turing` +- `turtle` +- `twig` +- `ts`, `tsx`, `typescript` +- `typoscript` +- `typoscriptcssdata` +- `typoscripthtmldata` +- `typst` +- `ucode` +- `v`, `vlang` +- `vsh`, `vshell` +- `vala`, `vapi` +- `vb.net`, `vbnet` +- `verilog`, `v` +- `vhdl` +- `vhs`, `tape`, `cassette` +- `vim` +- `vue`, `vuejs` +- `wdte` +- `wast`, `wat` +- `wgsl` +- `vtt` +- `whiley` +- `xml` +- `xorg.conf` +- `yaml` +- `yang` +- `z80` +- `zed` +- `zig` diff --git a/.cursor/rules/docs/openapi-x-doc.mdc b/.cursor/rules/docs/openapi-x-doc.mdc new file mode 100644 index 0000000..f0e1678 --- /dev/null +++ b/.cursor/rules/docs/openapi-x-doc.mdc @@ -0,0 +1,95 @@ +--- +description: OpenAPI x-doc rules for configuration docs +globs: openapi/**/*.yaml +alwaysApply: false +--- + +# OpenAPI Documentation Fields + +- Use reserved `x-doc-` fields only for documentation rendering. +- Supported keys: + - `x-doc-deprecated` + - `x-doc-required` + - `x-doc-default` + - `x-doc-examples` + - `x-doc-search` + - `x-doc-skip` + - `x-doc-map-key-name` + - `x-doc-pattern-name` + +# Value Constraints + +- `x-doc-default` must match target field type. +- `x-doc-example` may contain markdown and has priority over `example` and `x-examples`. +- `x-doc-examples` must be an array of YAML examples. +- `examples`, `x-examples`, and `x-doc-examples` must always be arrays of examples. + - If target parameter type is `array`, example value must be an array of arrays. + - If target parameter type is `object`, example value must be an array of objects (maps). + - If target parameter type is string/integer/boolean, example value must be an array of string/integer/boolean. +- `x-doc-skip: true` means field is not rendered in docs. + +Example (`type: array` -> array of arrays in `x-examples`): + +```yaml +type: array +description: | + List of plugins. +x-examples: + - - name: "plugin1" + ignoreFailure: false +items: + type: object +``` + +# Description Quality For OpenAPI Parameters + +- If a parameter has `default`, do not duplicate that value in `description`. + - Avoid phrases like "Default is ...", "По умолчанию ...", "It is ... by default". +- If a parameter has `enum`, do not duplicate enum values as a plain "Possible values" list in `description`. + - Enum values are rendered automatically. + - It is allowed (and recommended) to explain semantic differences between each enum value. +- Description structure rule: + - first 1-2 sentences define parameter purpose; + - usage details must be placed in separate paragraph(s), separated by blank lines (Markdown). + +Preferred enum description style (if it is necessary to describe possible values): + +```yaml +mode: + type: string + description: | + The HTTPS usage mode. + + Modes: + - `CertManager` — Stronghold will use HTTPS and get a certificate from the clusterissuer defined in the `certManager.clusterIssuerName` parameter. + - `CustomCertificate` — Stronghold will use HTTPS using the certificate from the `d8-system` namespace. + enum: + - "CertManager" + - "CustomCertificate" +``` + +Avoid style: + +```yaml +mode: + type: string + description: | + The HTTPS usage mode: + + Possible values: `CertManager`, `CustomCertificate` + enum: + - "CertManager" + - "CustomCertificate" +``` + +# OpenAPI RU Translation File + +- For `openapi/config-values.yaml`, create and maintain `openapi/doc-ru-config-values.yaml`. +- Translation file should follow source structure and include RU `description` values. +- Keep only translation-relevant structure for descriptions; avoid copying operational schema fields into translation file. + +# OpenAPI Translation Validation + +- `openapi/config-values.yaml` and `openapi/doc-ru-config-values.yaml` must be valid YAML. +- Each translated `description` path in `doc-ru-config-values.yaml` must exist in `config-values.yaml`. +- Do not leave orphan translation paths that have no source counterpart. diff --git a/.cursor/rules/docs/ru-en-parity.mdc b/.cursor/rules/docs/ru-en-parity.mdc new file mode 100644 index 0000000..f364dcf --- /dev/null +++ b/.cursor/rules/docs/ru-en-parity.mdc @@ -0,0 +1,25 @@ +--- +description: RU and EN parity and naming rules +globs: content/**/*.md +alwaysApply: false +--- + +# RU EN Parity + +- For each EN page, create RU counterpart when RU docs are maintained. +- Keep section structure aligned between EN and RU versions. +- Allow wording differences, but preserve technical meaning and constraints. +- For any update in one language, check paired file in second language and apply equivalent changes when they are relevant to both. +- Do not leave EN/RU pair semantically diverged after an edit unless change is intentionally language-specific. + +# File Naming + +- Russian files must use suffix `.ru.md` only. +- Forbidden variants: `.RU.md`, `_RU.md`, or any custom RU suffix. +- Naming must stay Hugo-compatible. + +# Media Localization + +- Use localized file pairs for media when needed, for example: + - EN: `image1.jpg` + - RU: `image1.ru.jpg` diff --git a/.cursor/rules/docs/terminology.mdc b/.cursor/rules/docs/terminology.mdc new file mode 100644 index 0000000..4c4b134 --- /dev/null +++ b/.cursor/rules/docs/terminology.mdc @@ -0,0 +1,44 @@ +--- +description: Deckhouse terminology and wording rules +alwaysApply: true +--- + +# Terminology + +- The full glossary is normative and published at https://pp.flant.ru/llms.txt (see "Glossary" section). + Fetch and apply it before writing or reviewing documentation text. +- Apply glossary constraints directly: + - `K8s` with uppercase `K`; + - `cloud provider` -> "облачный провайдер"; + - `module parameter` -> "параметр модуля"; + - `RBAC` is not translated; + - use "узел", not "нода"; + - use "веб-интерфейс", not `web-интерфейс` or `Web-интерфейс`; + - use `IP-адрес`; + - use "файлы cookie", not "cookie-файлы"; + - avoid "платформа Deckhouse"; use product names explicitly (for example, Deckhouse Kubernetes Platform). +- For mixed EN/RU or abbreviation+RU compound terms, use a hyphen: + - `S3-бакета` (not `S3 бакета`); + - `managed-сервис` (not `managed сервис`); + - `master-узел` (not `master узел`); + - `HTTP-протокол` or `протокол HTTP` (not `HTTP протокол`). +- Do not replace approved terms with synonyms if glossary defines exact form. +- Keep product naming consistent with glossary and product wording rules. +- Module name must be used exactly as defined in `module.yaml.name` (canonical lowercase Kebab Case). +- Do not humanize or reformat module name in prose: + - use `stronghold`, not `Stronghold`; + - use `volume-data-manager`, not `Volume Data Manager`. +- For RU text, avoid jargon variants forbidden by glossary. +- If a local checklist conflicts with full glossary text, follow https://pp.flant.ru/llms.txt. + +# Inline Code Scope + +- Do not wrap values inside YAML files in backticks — YAML values are already code context. + For example, the `name` field in `module.yaml` must contain the plain module name, not `` `module-name` ``. +- The same applies to other YAML fields: `enum` values, `default` values, etc. + +# Language Consistency + +- Use one term form throughout a page. +- Keep EN technical terms where glossary explicitly requires no translation. +- Validate key terms in headings, alerts, and examples, not only body text. diff --git a/.cursor/skills/run-docs-website/SKILL.md b/.cursor/skills/run-docs-website/SKILL.md new file mode 100644 index 0000000..a2c812e --- /dev/null +++ b/.cursor/skills/run-docs-website/SKILL.md @@ -0,0 +1,30 @@ +--- +name: run-website +description: Runs the documentation website locally via `Makefile` and werf. Use when the user wants to run the docs, preview the documentation site, start the docs server, or open the documentation website locally. +--- + +# Run Documentation Website + +## Quick start + +1. **Run in the repository root**: + ```bash + make up + ``` + +3. **Open** in a browser: + - for the English version — http://localhost/products/kubernetes-platform/documentation/v1/ + - for the Russian version — http://ru.localhost/products/kubernetes-platform/documentation/v1/ + +4. **Stop** when done: + ```bash + make down + ``` + +## Other targets (from docs/site/) + +| Target | Use case | +|--------|-----------------------------------------------------------------------------| +| `make up` | Start docs in watch mode that rebuilds on commit | +| `make lint-markdown-fix` | Run markdown linter and fix some problems automatically | +| `make down` | Stop containers, remove networks, and stop the local registry |