Skip to content

Latest commit

 

History

History
125 lines (86 loc) · 4.88 KB

agents.md

File metadata and controls

125 lines (86 loc) · 4.88 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.

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.

Repository Structure

Top-level Directories and Files

The external repository is organized as follows:

  • ru/: Contains Russian language documentation
  • en/: Contains English language 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

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.