From 1e2aefbe80cdb51edeac6f42f841e87af8821566 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Wed, 23 Jul 2025 17:51:43 +0200 Subject: [PATCH 1/2] docs(fix): replace broken links and update procedures --- pages/guidelines.mdx | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/pages/guidelines.mdx b/pages/guidelines.mdx index c639535371..5cfa61aeb2 100644 --- a/pages/guidelines.mdx +++ b/pages/guidelines.mdx @@ -3,7 +3,7 @@ title: Scaleway Documentation Guidelines description: Discover comprehensive guidelines on writing and formatting for our documentation site. Ensure consistency and clarity with our style guide, covering grammar, terminology, and best practices. tags: style-guide guidelines wording grammar dates: - validation: 2025-02-11 + validation: 2025-07-23 --- import Requirements from '@macros/iam/requirements.mdx' @@ -241,7 +241,7 @@ Use a console icon when referring in the documentation to the equivalent icon in | ------------------------------------------------------------------- | ---------------------------------------------------------- | | ````Use the toggle to activate the feature```` | Use the toggle to activate the feature | -See the [full list of available icons](/components/docs/#inline-console-icons). +See the [full list of available icons](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-icon--docs). ### Messages @@ -253,7 +253,7 @@ Three types of message boxes are available, to use as follows: | Tip | Information about a different way to accomplish something, or how to go further | ```` ```` | This is a tip | | Important | Critical warnings and information that the user must read to avoid unwanted consequences or mistakes | ```` ```` | This is important | -Read more about [message box components](/components/docs/#messages). +Read more about [message box components](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-message--docs). ### Tabs @@ -299,7 +299,7 @@ Renders as: -Read more about the [tab component](/components/docs/#tabs). +Read more about the [tab component](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-tabs--docs). ## Grammar, syntax and typography @@ -418,10 +418,12 @@ A wording handbook is available internally, with a full list of correct product ### Lightbox component -Use the [Lightbox component](/components/docs/#lightbox) for images, with the following syntax: +Use the [Lightbox component](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-lightbox--docs) for images, with the following syntax: ```` - +import myImage from "./assets/myImage.webp" + + ```` All images must be in `webp` format, and stored in the page's `assets` folder. Image names must always start with `scaleway`, and the words should be hyphen-seperated. @@ -460,8 +462,7 @@ categories: ``` - **title**: The title of the page, used by external search engines and the main title that displays on the documentation page. -- **description**: The description, used by external search engines. It should be between 120 and 160 characters, and SEO-optimized, using clear, engaging language suitable for a wide audience. Also displays on some -documentation pages (e.g. when the page is linked to from a [product card](https://www.scaleway.com/en/docs/components/docs-editor/#productcard)). +- **description**: The description, used by external search engines. It should be between 120 and 160 characters, and SEO-optimized, using clear, engaging language suitable for a wide audience. Also displays on some documentation pages (e.g. when the page is linked to from a [product card](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-card--docs). - **tags**: The tags used by internal and external search engines to help users find the page - **dates: posted**: The date the page was originally created, in the format `yyyy-mm-dd`. This displays on the generated page. - **dates: validation**: The date the page was last validated, in the format `yyyy-mm-dd`. This displays on the generated page, and is used by the Documentation team when identifying documentation pages that need reviewing. @@ -488,6 +489,8 @@ The introduction should be a few sentences, or a few short paragraphs, which exp ### Requirements --- +import Requirements from '@macros/iam/requirements.mdx' + - A Scaleway account logged into the [console](https://console.scaleway.com) @@ -497,7 +500,7 @@ The introduction should be a few sentences, or a few short paragraphs, which exp - Installed `helm` (version 3.2+), the Kubernetes [packet manager](https://helm.sh/), on your local machine --- -Start by using the macro `` or type the macro text manually. For example: +Import the `` macro under the page's [metadata](#metadata) as shown in the example above, then use the macro or type the macro text manually. For example: | Macro id | Text formatting | |-------------------------------|-----------------| @@ -518,4 +521,4 @@ Continue by listing the necessary products, resources or items users must have. |`- An [SSH key](/organizations-and-projects/how-to/create-ssh-key/)` | - An [SSH key](/organizations-and-projects/how-to/create-ssh-key/) | |`- A valid [API key](/iam/how-to/create-api-keys/)` | - A valid [API key](/iam/how-to/create-api-keys/) | |`- Downloaded and installed the [Scaleway CLI](https://github.com/scaleway/scaleway-cli#scaleway-cli-v2) ` | - Downloaded and installed the [Scaleway CLI](https://github.com/scaleway/scaleway-cli#scaleway-cli-v2) | -|`- An [Instance](/instances/how-to/create-an-instance) ` | - An [Instance](/instances/how-to/create-an-instance) | \ No newline at end of file +|`- An [Instance](/instances/how-to/create-an-instance) ` | - An [Instance](/instances/how-to/create-an-instance) | From 6f3beae02ba6021b5cfeacf2308efffdcdaf0d7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=A9da?= <87707325+nerda-codes@users.noreply.github.com> Date: Wed, 23 Jul 2025 17:52:53 +0200 Subject: [PATCH 2/2] Update pages/guidelines.mdx --- pages/guidelines.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/guidelines.mdx b/pages/guidelines.mdx index 5cfa61aeb2..fda051dfeb 100644 --- a/pages/guidelines.mdx +++ b/pages/guidelines.mdx @@ -462,7 +462,7 @@ categories: ``` - **title**: The title of the page, used by external search engines and the main title that displays on the documentation page. -- **description**: The description, used by external search engines. It should be between 120 and 160 characters, and SEO-optimized, using clear, engaging language suitable for a wide audience. Also displays on some documentation pages (e.g. when the page is linked to from a [product card](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-card--docs). +- **description**: The description, used by external search engines. It should be between 120 and 160 characters, and SEO-optimized, using clear, engaging language suitable for a wide audience. Also displays on some documentation pages (e.g. when the page is linked to from a [product card](https://docs-sb-storybook-staging.s3-website.fr-par.scw.cloud/?path=/docs/mdx-card--docs)). - **tags**: The tags used by internal and external search engines to help users find the page - **dates: posted**: The date the page was originally created, in the format `yyyy-mm-dd`. This displays on the generated page. - **dates: validation**: The date the page was last validated, in the format `yyyy-mm-dd`. This displays on the generated page, and is used by the Documentation team when identifying documentation pages that need reviewing.