diff --git a/pages/guidelines.mdx b/pages/guidelines.mdx index d73dc3e6cd..6f24ca9595 100644 --- a/pages/guidelines.mdx +++ b/pages/guidelines.mdx @@ -80,6 +80,20 @@ When creating an entirely new documentation page from scratch, we generally expe All Scaleway documentation pages should be `.mdx` files (MDX is an extension to Markdown that lets you include JSX). Any images included within the page must be `.webp` files. +### Page URL + +All Scaleway product documentation pages have URLs that should conform to the following format: + +`https://www.scaleway.com/en/docs////` + +| URL element | Description | Guidance | +|-------------|-------------|----------| +| Product name | Scaleway documentation and developers sites use the **full product name** in their URLs. | ✅ managed-databases-for-redis, container-registry

❌ redis, registry | +| Page type | All product documentation pages should conform to one of the [page types listed above](#page-type) | E.g. `how-to`, `api-cli`, `concepts`. | +| Page slug | A short, descriptive, slug, usually based on the title of the page. To keep slugs short, you can omit the product name
(already in the URL at a higher level) and stopwords. Note that certain page types (concepts, quickstart etc.) do not have further page slugs and terminate at type.| ✅ manage-flexible-ips, create-pipeline

❌ manage-your-instance-flexible-ips, create-an-edge-services-pipeline | + +Note that for [tutorials](/tutorials/), the URL format is: `https://www.scaleway.com/en/docs/tutorials//`, and it is pertinent to include the relevant product name in the page slug, as it does not appear elsewhere in the URL. + ### Page structure Scaleway Documentation pages should conform to the following structure: