docs(tuto): review team

Author: nerda-codes

tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition-expanded.webp

@@ -24,13 +24,15 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
 
 - A Scaleway account logged into the [console](https://console.scaleway.com)
 - [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization
-- Installed Python
-- Installed pip
-- Installed Visual Studio Code
-- Knowledge of the [Markdown](https://www.markdownguide.org/getting-started/#what-is-markdown) markup language
+- [Installed Python](https://www.python.org/downloads/)
+- [Installed pip](https://pip.pypa.io/en/stable/installation/)
+- [Installed Visual Studio Code](https://code.visualstudio.com/download)
+- Knowledge of the [markdown](https://www.markdownguide.org/getting-started/#what-is-markdown) markup language
+
+## Set up MkDocs and configure your website
+
+    ### Setting up MkDocs
 
-<Tabs id="install">
-  <TabsTab label="Set up MkDocs and configure your website">
     1. Open the Visual Studio Code terminal and paste the following command to create a virtual environment to host your MkDocs content:
         ```
          python -m venv envname
@@ -72,21 +74,20 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
             └─ mkdocs.yml
           ```
 
-    ## Configuring your website
+    ### Configuring your website
 
        MkDocs provides many [configuration options](https://squidfunk.github.io/mkdocs-material/creating-your-site/#configuration) that you can use to create a beautiful website.
 
 
-        Open your `mkdocs.yml` file. The following output should display. We will add to it as we go.
+        Open your `mkdocs.yml` file. The following output should display. We will add to it as we go. Delete `site_url: https://mydomain.org/mysite` as you will not need it.
 
             ```
             site_name: My documentation website
-            site_url: https://mydomain.org/mysite
             theme:
               name: material
             ```
 
-    ### Configuring the color palette
+    #### Configuring the color palette
 
         Material for MkDocs provides two default color schemes: `default`, which is the light mode, and `slate` which is the dark mode.
 
@@ -96,11 +97,10 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
             palette:
               - scheme: default
           ```
-        Your file configuration should look like the following:
+        Your file configuration should look like the following.
 
           ```
             site_name: My documentation website
-            site_url: https://mydomain.org/mysite
             theme:
               name: material
               palette:
@@ -149,7 +149,6 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
 
         ```
           site_name: My documentation website
-          site_url: https://mydomain.org/mysite
           theme:
             name: material
             palette:
@@ -176,7 +175,7 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
                   name: Switch to light mode
         ```
 
-    ### Configuring fonts
+    #### Configuring fonts
 
         Material for MkDocs integrates with [Google Fonts](https://fonts.google.com/) but you can also add custom fonts if you prefer.
 
@@ -193,7 +192,6 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
 
           ```
             site_name: My documentation website
-            site_url: https://mydomain.org/mysite
             theme:
               name: material
               palette:
@@ -222,7 +220,7 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
                 text: Roboto
           ```
 
-    ### Configuring navigation
+    #### Configuring navigation
 
         MkDocs provides multiple ways to configure your website's navigation depending on the amount of content your website contains. Find out [all available configurations for navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/) on the MkDocs website.
 
@@ -239,8 +237,9 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
           - How to perform action three: perform-action-three.md
         ```
 
-    ### Configuring admonitions
+    #### Configuring admonitions
 
+        An admonition also known as a call-out, is a graphical element used in user guides. It consists of a text block used to give a description or additional information to users.
         You can use admonitions to add side content to your documentation or make parts you want your users to notice stand out more. Refer to the [documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/?h=admonitions#admonition-icons) to see available admonition icons.
 
     #### Enabling admonitions
@@ -276,7 +275,7 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
 
     #### Using admonitions
 
-        The example below shows you the syntax you need to use in your files for admonitions. You can replace `info` with any of the admonitions you have added in the previous section (`abstract`, `note`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, and `quote`).
+        The example below shows you the syntax you need to use in your markdown files for admonitions. You can replace `info` with any of the admonitions you have added in the previous section (`abstract`, `note`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, and `quote`).
 
         ```
         !!! info
@@ -289,20 +288,35 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
         ```
         !!! info "Information about the admonition box"
 
-            I am an information admonition. You can use me to give additional information to your user.
+            I am an information admonition with a title. You can use me to give additional information to your user.
         ```
 
         If you want your admonition box to be collapsible, you can use the code below. The user will only see the box without its content.
 
         ```
         ??? info
 
-            I am an information admonition. You can use me to give additional information to your user.
+            I am a collapsible information admonition. You can click the arrow to the right to expand me.
         ```
 
         Find out more about admonitions on the [MkDocs website](https://squidfunk.github.io/mkdocs-material/reference/admonitions/?h=admonitions#configuration).
 
-    ### Additional configuration
+    #### Adding images
+
+        You need to add the `glightbox` plugin in your `mkdocs.yml` file to add images and videos on your website. Find out how to add the plugin in the [section below](#additional-configuration).
+
+        You can add images in your markdown files using the following example:
+              ```
+              ![Description of your image for accessibility purposes or leave this field empty](/folder-where-your-image-is-located/name-pf-image.png){align=center, width="150", loading=lazy}
+              ```
+        You can also add images inside collapsible admonitions. Notice that the image component is indented under the `info` text. Your image will not display if the indentation is incorrect.
+                  ```
+                  ??? info "Your example should look like the following"
+                      ![Description of your image for accessibility purposes or leave this field empty](/folder-where-your-image-is-located/name-pf-image.png){align=center, width="150", loading=lazy}
+                  ```
+
+
+    #### Additional configuration
 
         You can add the following additional configuration options in your `mkdocs.yml` file. The `features` component allows you to use various features of the Material theme.
           ```
@@ -332,35 +346,93 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
           copyright: >
             Copyright &copy; 2016 - 2024 Martin Donath
           ```
-    ## Downloading the mkdocs file template
+    ### Template of the mkdocs.yaml file
+
+        If you have only added the elements shown in the sections above, you can copy the code below or use it as reference to make sure you have added everything correctly in your `mkdocs.yml` file.
+
+            ```
+            site_name: My documentation website
+            theme:
+              name: 'material'
+              palette: # Palette toggle for light mode
+                - scheme: default
+                  primary: black # Primary defines the primary color of the theme.
+                  accent: purple # Accent specifies the accent color of the theme.
+                  toggle: # toggle specifies the icon and name for toggling between light and dark modes.
+                    icon: material/toggle-switch
+                    name: Switch to dark mode
 
-        If you have only added the elements shown in the sections above, you can download the `mkdcos.yml` below.
+              # Palette toggle for dark mode
+                - scheme: slate
+                  primary: white
+                  accent: deep purple
+                  toggle:
+                    icon: material/toggle-switch-off-outline
+                    name: Switch to light mode
+              font:
+                    text: Roboto
+              nav: # Defines the navigation structure of the website, linking to the corresponding markdown files.
+                - Welcome to my documentation website: index.md
+                - My documentation website's FAQ: faq.md
+                - Understanding a concept in my documentation website: understanding-concept.md
+                - How to perform action one: perform-action-one.md
+                - How to perform action two: perform-action-two.md
+                - How to perform action three: perform-action-three.md
+              markdown_extensions:
+                - admonition
+                - pymdownx.details
+                - pymdownx.superfences
+              icon: # Maps custom MkDocs icons to different types of admonitions (alerts or messages), using icons from the Octicons set.
+                admonition:
+                  note: octicons/tag-16
+                  abstract: octicons/checklist-16
+                  info: octicons/info-16
+                  tip: octicons/squirrel-16
+                  success: octicons/check-16
+                  question: octicons/question-16
+                  warning: octicons/alert-16
+                  failure: octicons/x-circle-16
+                  danger: octicons/zap-16
+                  bug: octicons/bug-16
+                  example: octicons/beaker-16
+                  quote: octicons/quote-16
+              features:
+                - content.code.copy # Adds a copy button to code blocks.
+                - navigation.sections # Enables section-based navigation.
+                - navigation.path # Shows the navigation path (breadcrumbs).
+                - navigation.top # Adds a "back to top" button.
+                - search.suggest # Enables search suggestions.
+              plugins: # Lists the MkDocs plugins enabled for the site.
+                - search # Adds search functionality.
+                - glightbox # Adds lightbox functionality for images and videos.
+              copyright: >
+                Copyright &copy; 2016 - 2024 Martin Donath
+          ```
 
-          <a href="/tutorials/using-bucket-website-with-mkdocs/mkdocs-example.yml" target="_blank" rel="noopener noreferrer" download="mkdocs-example.yml"> Download the mkdocs file </a>
+      ## Preview and deploy your website
 
-</TabsTab>
-  <TabsTab label="Preview and deploy your MkDocs website">
+      ### Preview your website
 
       Once your website's content is ready and configured, you can preview it to make sure that everything displays properly.
 
-      ## Previewing and generating a static website
 
       1. Open the folder containing your `docs` directory in Visual Studio Code. The one we have created in this tutorial is named `my-folder`.
       2. Open the Visual Studio Code terminal and paste the following command:
           ```
           mkdocs serve
           ```
-      3. Copy the localhost link that displays in the output into your browser. Your website should display.
+      3. Copy the localhost link (`http://127.0.0.1:8000/`) that displays in the output into your browser. Your website should display.
       4. Check that everything on your website displays correctly and ensure that there are no broken links.
-      5. Run the following command in your terminal to generate your folder's content into a static website:
+      5. Hit `Control` and `C` to shut down the localhost.
+      6. Run the following command in your terminal to generate your folder's content into a static website:
           ```
           mkdocs build
           ```
           <Message type="note">
            When you run the `mkdocs build` command, MkDocs processes your markdown files and other configurations specified in your `mkdocs.yml` file and outputs a complete static site in a directory named `site` by default.
           </Message>
 
-      ## Deploying your website
+      ### Deploy your website
 
       1. [Create an Object Storage bucket](/storage/object/how-to/create-a-bucket/) from the [Scaleway console](https://console.scaleway.com/).
       2. [Enable](/storage/object/how-to/use-bucket-website/) the bucket website feature on your bucket.
@@ -374,7 +446,17 @@ Find out how to Set up MkDocs and configure your website in the first tab, then
       9. Once the transfer of your files is complete, cick the **Bucket settings** tab and scroll down to the **Bucket website** section.
       10. Retrieve the URL of your website under **Website URL**.
 
-  </TabsTab>
-</Tabs>
+      ## Example of what your website should look like
+
+      Your website's homepage should look similar to the following in light mode:
+          <Lightbox src="scaleway-mkdocs-website-light-mode.webp" alt="MkDocs website in light mode" />
+
+      Your website's homepage should look similar to the following in dark mode:
+          <Lightbox src="scaleway-mkdocs-website-dark-mode.webp" alt="MkDocs website in dark mode" />
+
+      This is what a collapsible admonition with a custom title should look like when collapsed:
+          <Lightbox src="scaleway-collapsible-admonition.webp" alt="" />
 
+      This is what a collapsible admonition with a custom title should look like when expanded:
+          <Lightbox src="scaleway-collapsible-admonition-expanded.webp" alt="" />