Name: docs-content
Author: scaleway

Imported from scaleway/docs-content (AGENTS.md). Install upstream with npx skills add scaleway/docs-content. Copyright stays with the author.

AGENTS.md - Scaleway Documentation Content

Purpose

This file helps AI/LLM agents understand the structure, tooling, and conventions of the Scaleway documentation repository so they can make consistent, high-quality contributions.

Project overview

This repository hosts the Scaleway Documentation content. The goal of Scaleway documentation is to provide information about all resources in the Scaleway ecosystem and the procedures users should follow to get the best experience from products and services.

Repository: scaleway/docs-content
Website: scaleway.com/en/docs

Scaleway documentation content is authored in MDX and includes React components to add dynamic, interactive elements.

Content types

PAGE TYPE	DESCRIPTION
How to	Shows how to do a core action (e.g. create, configure, delete, use features) for a Scaleway product via the console, e.g. How to create a Load Balancer
Quickstart	Shows how to do the main series of actions necessary to start using a Scaleway product via the console, e.g. Instances Quickstart
Concepts	Defines and briefly explains the main terminology associated with a Scaleway product, e.g. Kubernetes Concepts
Troubleshooting	Gives solutions to help resolve a common issue with a Scaleway product, e.g. VPC auto-config is not working. Refer to the troubleshooting template for more information
API/CLI	Presents information and tips for creating and configuring a Scaleway product via both official and third-party APIs, CLIs, SDKs and other developer tools, e.g. Terraform/OpenTofu, e.g. Using Object Storage with the AWS-CLI. These pages complement the main developer reference documentation.
Additional Content	Provides detailed information on specific subjects and features associated with a Scaleway product, e.g. Optimize your Object Storage performance
Tutorial	Explains how to use a Scaleway product with a third-party tool, or how to use multiple Scaleway products together for a specific use-case, e.g. Deploying Strapi on an Instance
FAQ	Gives answers to the most frequently asked questions about Scaleway products, e.g. Cockpit FAQ

Directory structure

docs-content/
├── pages/                          # Main documentation content organized by product
│   ├── instances/                  # Example: Instances product documentation
│   │   ├── index.mdx               # Product landing page
│   │   ├── menu.ts                 # Navigation menu structure
│   │   ├── concepts/               # Concept pages
│   │   ├── quickstart/             # Quickstart guides
│   │   ├── how-to/                 # How-to guides
│   │   ├── reference-content/      # Additional content
│   │   ├── api-cli/                # API/CLI documentation
│   │   └── troubleshooting/        # Troubleshooting guides
│   ├── billing/                    # Billing documentation
│   ├── kubernetes/                 # Kubernetes documentation
│   └── ...                         # 50+ product directories
├── macros/                         # Reusable content components organized by product
│   ├── compute/                    # Compute-related macros
│   ├── storage/                    # Storage-related macros
│   ├── network/                    # Network-related macros
│   └── ...                         # Product-specific macros
├── changelog/                      # Product changelog entries
│   ├── instances/                  # Instances changelogs by date
│   ├── kubernetes/                 # Kubernetes changelogs by date
│   └── ...                         # Product-specific changelogs
├── blocks/                         # Reusable UI blocks (callToAction, feedback, etc.)
├── menu/                           # Global navigation configuration
│   ├── navigation.ts               # Main navigation structure
│   ├── mainLinks.json              # Main navigation links
│   ├── footer.json                 # Footer links
│   └── filters.json                # Content filters
├── assets/                         # Global assets (images, PDFs)
├── docs/                           # Project documentation
│   ├── CONTRIBUTING.md             # Contribution guidelines
│   ├── CODE_OF_CONDUCT.md          # Code of conduct
│   ├── DOC_PAGE_TEMPLATE.mdx       # Page template
│   └── PULL_REQUEST_TEMPLATE.md    # PR template
└── tutorials/                      # Standalone tutorial content

Content authoring conventions

Frontmatter structure

All .mdx pages use YAML frontmatter:

---
title: Page Title
description: One-sentence description for SEO
tags: tag1 tag2 tag3
dates:
  validation: 2024-01-01
  posted: 2024-01-01
categories:
  - product-category
---

Navigation structure

Each product directory contains a menu.ts file defining its navigation. The following example uses the Instances product to illustrate how menu.ts works.

export const instancesMenu = {
  label: 'CPU Instances',
  slug: 'instances',
  items: [
    { label: 'Overview', slug: '../instances' },
    { label: 'Concepts', slug: 'concepts' },
    { label: 'Quickstart', slug: 'quickstart' },
    { label: 'How to', slug: 'how-to', items: [...] },
    { label: 'API/CLI', slug: 'api-cli', items: [...] },
    { label: 'Additional Content', slug: 'reference-content', items: [...] },
    { label: 'Troubleshooting', slug: 'troubleshooting' },
  ],
}

Macros

Macros are reusable content components with their own frontmatter:

---
macro: compute-instances
---

Macros embed consistent, reusable content snippets across multiple pages from a single source.

MDX components

This project uses MDX (Markdown + React components). Key components include:

<Message> - Note, tip, warning, important messages
<Grid> - Grid layout container
<SummaryCard> - Card components for navigation
<ProductHeader> - Product landing page headers
<Tabs> - Tabbed content
<CodeBlock> - Syntax-highlighted code blocks
<Table> - Data tables

For full component reference, see: storybook-docs.scaleway.com

Writing guidelines

See Writing Guidelines for the full documentation style guide.

Language: Use American English (US English) spelling exclusively (e.g., "center" not "centre", "recognize" not "recognise").
Tone: Use present tense, active voice. Maintain a formal tone. Do not use passive voice, "please", "thank you", future tense, or contractions.
Pronouns: Address the user as "you". Refer to Scaleway as "Scaleway".
File format: All pages must be .mdx files. All images must be .webp format.
Page structure: Include metadata in the frontmatter YAML, Introduction, Requirements (when applicable), and Page body in that order.
Headings: Treat the title in the frontmatter YAML as the H1 heading, it must be the only H1 heading, and use H2/H3 for subsections. All headings must be in sentence case.
Numbered steps: Use numbered steps for instructions. Each step = one action, starting with an imperative verb.
Code blocks: Use triple backticks with language specification (e.g., ```python).
Inline code: Use backticks for environment variables, placeholders, and short code snippets.
Links: Use descriptive link text (not "here" or "this page"). Use relative links with leading and trailing slashes for internal pages.
Admonitions: Use one of the following message boxes: Tip, Note, Important. Do not use tables or code blocks in message boxes.
Bold text: Use bold for console navigation elements and button names (e.g., Click Create Instance).
Capitalization: Capitalize product names (Instance, Load Balancer). Do not capitalize feature names unless they are Scaleway-specific terms (InstantApp, Easy Deploy). Use sentence-case capitalization in titles and headings.
Numbers: Write all numbers as numerals. Use commas to separate thousands.
Dates/Times: Use 24-hour format for times. Use Month Day, Year format for dates (e.g., January 14, 2026). Avoid ordinals (e.g., "January 14" not "January 14th").

Product categories

The navigation of the documentation website scaleway.com/en/docs is organized into the following main categories (to match the navigation of the Scaleway console).

Management & Governance

Account, Billing, Environmental Footprint
Security & Identity (IAM, Key Manager, Organizations, Secret Manager)

Products

AI: Generative APIs
Bare Metal: Apple Silicon, Elastic Metal, Dedibox
Compute: Instances, GPU
Containers: Container Registry, Kubernetes
Databases: PostgreSQL/MySQL, Redis, MongoDB, OpenSearch, Serverless SQL
Data & Analytics: Data Orchestrator, Data Warehouse, Apache Spark, Kafka, NATS
Developer Tools: CLI, SDK, Terraform
Domains & Web Hosting: Domains/DNS, Mailbox, TEM, Webhosting
Integration Services: IoT Hub, Topics/Events, Queues, RabbitMQ
Monitoring: Audit Trail, Cockpit
Network: Edge Services, Interlink, IPAM, Load Balancer, Public Gateways, VPN, VPC
Serverless: Containers, Functions, Jobs
Storage: Block Storage, File Storage, Local Storage, Object Storage

Dedibox (separate console)

Dedibox Console, Servers, Network

Contributing

See CONTRIBUTING.md for the full guide.

Branch naming convention

[source]-[action]-[product]

source: int (internal) or ext (external)
action: add, rm, fix
product: product name (e.g., instances, kubernetes)

Example: int-add-instances, ext-fix-kubernetes

Commit convention

Based on Conventional Commits:

type(module): description PROJECT-XXX

Types:

docs - Project documentation (README, CONTRIBUTING, etc.)
feat - New content (pages, sections)
fix - Bug fixes (typos, images, etc.)
refactor - Structural changes
revert - Reverting changes
style - Formatting changes

Examples:

feat(console): add vpc how-to page MTA-2342
fix(iot): wrong image in quickstart
style: add bold at scaleway name occurrences MTA-1337

Pull Request naming

docs(product_name): description with some words

Agent attributions

All agent-drafted content must add draftedBy metadata as the last line of the YAML frontmatter, using the following format:

---
title: Page Title
description: One-sentence description for SEO
tags: tag1 tag2 tag3
dates:
  validation: 2024-01-01
  posted: 2024-01-01
categories:
  - product-category
draftedBy: agent-name agent-version
---

Strict boundaries

You MAY edit files in the macros, pages, and tutorials directories.
You MUST NEVER modify files in the .github, assets, bin, blocks, changelog, docs, menu, and the root directories.

Building and serving locally

This repository only hosts the documentation site content, and does not include any of the frontend or backend components required to build or render the site.

Important notes

This repository contains content only - no frontend/backend for building the site
Internal Scaleway users have access to internal preview tools
All PRs are reviewed and approved by the Scaleway Product Documentation team
Files use .mdx extension for extended Markdown with React components
Slugs must be kebab-case

docs-content

About