diff --git a/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition-expanded.webp b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition-expanded.webp new file mode 100644 index 0000000000..a8490b1638 Binary files /dev/null and b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition-expanded.webp differ diff --git a/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition.webp b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition.webp new file mode 100644 index 0000000000..81e311dfe2 Binary files /dev/null and b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-collapsible-admonition.webp differ diff --git a/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-files-in-bucket.webp b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-files-in-bucket.webp new file mode 100644 index 0000000000..ab98fecab4 Binary files /dev/null and b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-files-in-bucket.webp differ diff --git a/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-website-dark-mode.webp b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-website-dark-mode.webp new file mode 100644 index 0000000000..99652ba217 Binary files /dev/null and b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-website-dark-mode.webp differ diff --git a/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-website-light-mode.webp b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-website-light-mode.webp new file mode 100644 index 0000000000..8d76bb8c14 Binary files /dev/null and b/tutorials/using-bucket-website-with-mkdocs/assets/scaleway-mkdocs-website-light-mode.webp differ diff --git a/tutorials/using-bucket-website-with-mkdocs/index.mdx b/tutorials/using-bucket-website-with-mkdocs/index.mdx new file mode 100644 index 0000000000..180bdcfd5a --- /dev/null +++ b/tutorials/using-bucket-website-with-mkdocs/index.mdx @@ -0,0 +1,462 @@ +--- +meta: + title: Creating a documentation website using Object Storage bucket website and Material for MkDocs + description: Create a sleek documentation website using the Scaleway Object Storage bucket website feature and Material for MkDocs. Simple, fast, and easy to complete! +content: + h1: Creating a documentation website using Object Storage bucket website and Material for MkDocs + paragraph: Create a sleek documentation website using the Scaleway Object Storage bucket website feature and Material for MkDocs. Simple, fast, and easy to complete! +categories: + - object-storage +tags: documentation-website bucket-website material-for-mkdocs object-storage website +dates: + validation: 2024-10-07 + posted: 2024-10-07 +--- + +This tutorial shows you how to create a documentation website using the Scaleway [Object Storage bucket website](/storage/object/concepts/#bucket-website) feature with MkDocs. + +[MkDocs](https://www.mkdocs.org/) is a static site generator that allows users to generate a static website from a set of Markdown files. It is written in Python and uses Markdown for content creation. +We will use MkDocs to generate our website, and Material for MkDocs which is a documentation framework that extends MkDocs with additional features and customization options, to create visually appealing and user-friendly documentation websites. + +Find out how to Set up MkDocs and configure your website in the first tab, then click the second tab to learn how to get a preview of your website and how to deploy it. + + + +- 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](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 + + 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 + ``` + 2. Activate the virtual environment: + + ``` + source envname/bin/activate + ``` + 3. Create a folder inside your virtual environment. This folder will contain your documentation directory. + + ``` + mkdir my-folder + ``` + + Avoid naming your folder `docs` as this is already the default name for the MkDocs directory. + + 4. Install MkDocs and the MkDocs Material theme in your virtual environment: + ``` + pip install mkdocs + pip install mkdocs-material + ``` + 5. Open the documentation folder you have created and enter the following command: + ``` + mkdocs new . + ``` + + This will create a YAML file named `mkdocs.yaml`, and a directory named `docs` containing an `index.md` file inside `my-folder`: + - `docs` is the directory where you will need to create `.md` files containing your website's content. + - `index.md` is your website's homepage. + - `mkdocs.yml` is the file in which you can configure and customize your website. + + + The architecture of your folder should look like the following: + ``` + my-folder + ├─ docs/ + │ └─ index.md + └─ mkdocs.yml + ``` + + ### 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. Delete `site_url: https://mydomain.org/mysite` as you will not need it. + + ``` + site_name: My documentation website + theme: + name: material + ``` + + #### 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. + + Copy and paste the following code template under `theme` in the `mkdocs.yml` file to define your website's color scheme. Feel free to replace `default` with `slate` if you want to use the dark mode scheme. + + ``` + palette: + - scheme: default + ``` + Your file configuration should look like the following. + + ``` + site_name: My documentation website + theme: + name: material + palette: + - scheme: default + ``` + + #### Configuring a primary color + + You can use a specific primary color for your website's header, sidebar, and text links. Refer to the [MkDocs documentation](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#primary-color)to find out which color options are available. You can also set [custom colors](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#custom-colors). + + Copy and paste the following code template under `palette` to set your primary color to black. + + ``` + primary: black + ``` + + #### Configuring an accent color + + You can use an accent color to emphasize elements such as buttons, scrollbars, and hovered links. Refer to the [MkDocs documentation](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#accent-color) for a list of available colors. + + Copy and paste the following code template under `palette` to set your accent color to orange. + + ``` + accent: purple + ``` + + #### Configuring the color palette toggle + + You can give your users the choice to read your website in dark mode or light mode using a color palette toggle. Refer to the [documentation](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle) for a list of available toggle options. + + Copy and paste the following code template under `scheme` to set a color palette toggle. + + ``` + # Palette toggle for light mode + toggle: + icon: material/toggle-switch + name: Switch to dark mode + + # Palette toggle for dark mode + toggle: + icon: material/toggle-switch-off-outline + name: Switch to light mode + ``` + + This is what your `mkdocs.yml` file should look like: + + ``` + 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 + + # Palette toggle for dark mode + - scheme: slate + primary: white + # primary defines the primary color of the theme. + accent: deep 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-off-outline + name: Switch to light mode + ``` + + #### Configuring fonts + + Material for MkDocs integrates with [Google Fonts](https://fonts.google.com/) but you can also add custom fonts if you prefer. + + Copy and paste the following code template to use the `Roboto` font. + + ``` + font: + text: Roboto + ``` + + Refer to the [documentation](https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/#changing-the-fonts) to further configure your website's font styles. + + Your `mkdocs.yml` file should look like the following: + + ``` + 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 + + # Palette toggle for dark mode + - scheme: slate + primary: white + # primary defines the primary color of the theme. + accent: deep 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-off-outline + name: Switch to light mode + font: + text: Roboto + ``` + + #### 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. + + Set up the navigation structure of your website using the code sample below. This configuration allows you to organize your navigation menu as you wish. + + ``` + 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 + ``` + + #### 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 + + Copy and paste the following code template to enable admonitions, make them collapsible, and nest content inside them. + + ``` + markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + ``` + #### Adding admonition icons + + Copy and paste the following code template to use Octicons admonition icons. You can also use the [FontAwesome admonition icons](https://squidfunk.github.io/mkdocs-material/reference/admonitions/?h=admonitions#admonition-icons-fontawesome). + + ``` + icon: + 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 + ``` + + #### Using admonitions + + 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 + + I am an information admonition. You can use me to give additional information to your user. + ``` + + You can add a custom title inside the admonition box like in the example below. + + ``` + !!! info "Information about the admonition box" + + 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 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). + + #### 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. + ``` + 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. + ``` + Add the `plugins` component to define the MkDocs plugins you want to enable on your website. The `search` plugin allows you to add the search functionality and the `glightbox` plugin allows you to add images and videos. + ``` + plugins: + # Lists the MkDocs plugins enabled for the site. + - search + # Adds search functionality. + - glightbox + # Adds lightbox functionality for images and videos. + ``` + Add the copyright notice for your website. + ``` + copyright: > + Copyright © 2016 - 2024 Martin Donath + ``` + ### 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 + + # 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 © 2016 - 2024 Martin Donath + ``` + + ## Preview and deploy your website + + ### Preview your website + + Once your website's content is ready and configured, you can preview it to make sure that everything displays properly. + + + 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 (`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. 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 + ``` + + 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. + + + ### 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. + 3. Click your bucket, then the **Bucket settings** tab. + 4. Scroll down to the **Bucket website** section and enter the names of your **index** and **error** documents and save your changes. By default, your index file is named `index.html`, and your error file is named `404.html`. + 5. Scroll back up and click the **Files** tab. + 6. On your local computer, open the `site` folder generated in the previous steps. + 7. Select all the files and folders inside your `site` folder and drag and drop them inside your bucket. + 8. Select a storage class when prompted and click **Validate storage class** to confirm. Your file architecture should look like the following. + + 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**. + + ## Example of what your website should look like + + Your website's homepage should look similar to the following in light mode: + + + Your website's homepage should look similar to the following in dark mode: + + + This is what a collapsible admonition with a custom title should look like when collapsed: + + + This is what a collapsible admonition with a custom title should look like when expanded: + +