Skip to content

agents.md

Latest commit

 

History

History
156 lines (105 loc) · 7.08 KB

agents.md

File metadata and controls

156 lines (105 loc) · 7.08 KB

Documentation Guide for Yandex Cloud

Repository Overview

This repository contains the source files for Yandex Cloud documentation and is open for community contributions through the Content Program.

The repository has two distinct kinds of content. Choose the right location based on your task — do not treat all folders as interchangeable.

For AI Agents: Reading vs Editing

Search and answer questions about Yandex Cloud

When you need factual information from the documentation — how a service works, CLI commands, limits, pricing, step-by-step procedures, troubleshooting — work in md-docs/.

  • md-docs/ is a pre-built documentation bundle: plain Markdown with YFM variables and includes already resolved, ready to read and search.
  • Prefer md-docs/ for grep, codebase search, and reading pages end-to-end.
  • Do not edit files in md-docs/. It is generated output, not source.

Modify documentation (contributions, technical writers)

When you change documentation — fix typos, add sections, update operations guides, help technical writers — work in the source directories, not in md-docs/.

Task Where to work
Edit Russian documentation ru/ (primary source)
Contribution guides, topic lists guides/
English documentation en/ — do not edit; English is translated from Russian

Source files use Yandex Flavored Markdown (YFM): frontmatter, {{ variables }} from ru/presets.yaml / en/presets.yaml, {% include %} blocks, and service-specific syntax. After source changes, documentation is rebuilt; the result lands in a bundle like md-docs/ (or a local docs-gen/ output when building locally).

Summary: read and search in md-docs/; write and edit in ru/ (and related source paths). Never edit md-docs/ or en/ unless explicitly instructed otherwise.

How the Documentation is Created

The documentation is built using Diplodoc and Yandex Flavored Markdown (YFM).

  • Diplodoc: A documentation generation tool that processes YFM files and converts them into a publishable format.
  • YFM (Yandex Flavored Markdown): An extended version of Markdown that includes additional features for technical documentation, such as variables, includes, and special formatting options.

How to Build Documentation Locally

To build the documentation locally, follow these steps:

  1. Install diplodoc:

    npm i @diplodoc/cli -g

    To update the version of diplodoc, use the same command.

  2. Build the documentation:

    yfm -i docs -o docs-gen

    Where docs is the directory with source texts, and docs-gen is the directory where the generated documentation will be placed.

    In this repository, Russian source lives under ru/. The md-docs/ directory is the checked-in built bundle (same role as docs-gen after a local build): use it for search without running a build.

Repository Structure

Top-level Directories and Files

The external repository is organized as follows:

  • md-docs/: Pre-built documentation bundle for reading and search (resolved variables and includes). Do not edit.
  • ru/: Russian language source documentation — edit here when changing docs
  • en/: English language source documentation (DO NOT edit, documentation is translated from Russian)
  • guides/: Contains contribution guides and important topics list
  • redirects.yaml: URL redirect configuration (DO NOT edit)
  • README.md: Repository introduction and contribution guidelines

ru/ and en/ hold YFM source; md-docs/ holds the built Markdown equivalent (same structure as services on the site, without templating syntax).

Documentation Content Structure

The ru/ and en/ directories contain toc.yaml files that define the top-level documentation structure.

Directories with Underscores

Directories that begin with an underscore (e.g., _includes, _tutorials, _assets) store non-publishable source files. These are typically shared components, templates, or resources that are included in other documentation files but are not published as standalone pages.

Media files are stored in ru/_assets/ and en/_assets/ directories.

Service documentation is located in directories without underscores (e.g., compute, iam, storage).

Frontmatter Metadata

All documentation files in service directories must include Frontmatter metadata at the beginning of the file. Frontmatter is written in YAML format and enclosed between triple dashes (---).

Common Frontmatter fields include:

  • title: The page title (required)
  • description: Page description for SEO and previews (required)
  • editable: Controls whether the file can be edited (optional)
    • If editable: false is present, DO NOT edit this file
    • If this field is absent, the file can be edited

Example Frontmatter:

---
title: "Managing access in {{ service-name }}"
description: "Access management in the service for creating and managing databases."
---

Typical Service Documentation Structure

A typical service documentation directory follows this structure:

ru/<service-name>/
├── api-ref/             # API authentication and references (auto-generated, DO NOT edit)
├── cli-ref/             # CLI reference (auto-generated, DO NOT edit)
├── concepts/            # Conceptual information about the service
├── operations/          # Step-by-step instructions and how-to guides
├── qa/                  # Questions and answers
├── security/            # Security and access management
├── tutorials/           # Practical tutorials and examples
├── index.yaml           # Service index page
├── quickstart.md        # Getting started guide
├── release-notes.md     # Release notes and updates
├── tf-ref.md            # Terraform reference (partially generated, typically do not edit)
└── toc.yaml             # Service table of contents configuration

Contributing to the Repository

Auto-generated Content (DO NOT Edit)

The following content is automatically generated and should not be manually edited:

  • CLI references in service directories (e.g., ru/audit-trails/cli-ref/)
  • Terraform references (e.g., en/terraform/tf-ref/yandex-cloud/overview.md)
  • API references in service directories
  • Variables in ru/presets.yaml and en/presets.yaml
  • URL redirects in redirects.yaml

What Can Be Edited

  • All other documentation files in service directories
  • Concept pages, operations guides, tutorials, quickstarts
  • Security documentation (except role descriptions)
  • Questions and answers

Writing Guidelines

  • Use clear, concise language
  • Follow the existing structure of similar pages
  • Include practical examples where appropriate
  • Ensure technical accuracy
  • Use proper YFM syntax for formatting

License

The documentation is licensed under Creative Commons Attribution 4.0 International Public License. See the LICENSE file for details.