Merge pull request #208 from VaclavElias/update-12-content-improvements

Nice work @VaclavElias 🤣

en/contributors/documentation/deployment-azure.md

@@ -1,16 +1,17 @@
-# Deployment in Azure
-- [Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS](#step-by-step-guide-to-deploying-azure-web-apps-windows-with-iis)
-  - [Setting up a new Azure Web App (Windows) with IIS](#setting-up-a-new-azure-web-app-windows-with-iis)
-  - [Adjusting the Web App Configuration](#adjusting-the-web-app-configuration)
-  - [Modifying the GitHub Action](#modifying-the-github-action)
+# Deployment
 
-# Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS
+Our team has explored various deployment options, ultimately selecting the method detailed in this guide for its efficacy. Additionally, for demonstration purposes, you can refer to the [Deployment to GitHub Pages](deployment-azure.md#deployment-to-github-pages) section for alternative deployment strategies you can use to showcase your updates.
 
-This guide assumes you already have permission to access the Azure subscription.
+## Deploying to Azure Web Apps (Windows) with IIS
 
-## Setting up a new Azure Web App (Windows) with IIS
+This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name.
 
-These instructions pertain to the staging environment. For the production environment, follow the same steps, but with a different web app name.
+> [!NOTE]
+> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required.
+
+### Setting up a new Azure Web App
+
+Follow these instructions carefully to establish your Azure Web App in a staging environment. For deploying in a production environment, replicate these steps with an alternate web app name for differentiation.
 
 1. Navigate to the [Azure Portal](https://portal.azure.com/)
 1. Select **Create a resource**
@@ -18,7 +19,7 @@ These instructions pertain to the staging environment. For the production enviro
 1. In the Basic Tab
    - Choose your existing subscription and resource group
    - Under Instance Details, enter:
-      - Name: **stride-website-staging**
+      - Name: **stride-docs-staging**
       - Publish: **Code**
       - Runtime stack: **ASP.NET V4.8**
       - OS: **Windows**
@@ -27,7 +28,7 @@ These instructions pertain to the staging environment. For the production enviro
       - Click **Next**
 1. In the Deployment Tab - This step can be completed later if preferred.
    - Enable Continuous deployment
-   - Select account, organisation `Stride`, repository `stride-website` and branch `staging-next`
+   - Select account, organisation `Stride`, repository `stride-docs` and branch `staging`
    - Click **Next**
 1. In the Monitoring Tab
    - Leave all settings as default
@@ -43,30 +44,57 @@ These instructions pertain to the staging environment. For the production enviro
    - Click **Create**
    - The GitHub Action will be added to the repository and run automatically. It will fail at this stage, but this will be resolved in the subsequent steps.
 
-## Adjusting the Web App Configuration
+> [!CAUTION]
+> If you have completed the **Deployment Tab** process, ensure that the deployment profile includes the **DeleteExistingFiles** property. This property may need to be set to `False` or `True` depending on the specific requirements of your deployment. For instance, Stride Docs deployment retains files from previous deployments, allowing multiple versions like `4.2`, `4.1`, etc., to be maintained. Adjust this setting based on your deployment needs.
+
+### Adjusting the Web App Configuration
 
 1. Proceed to the newly created Web App
 1. Click on **Configuration**
 1. Select **General Settings**
-1. Change the Http Version to **2.0**
+1. Change the `Http version` to **2.0**
+1. Change `Ftp state` to **FTPS only**
+1. Change `HTTPS Only` to **On**
 1. Click **Save** to apply the changes
 
-## Modifying the GitHub Action
+### Modifying the GitHub Action
 
-The previous step will have added a GitHub Action to the repository, which will fail at this point. You need to modify the GitHub Action to correct the issue.
+The previous step will have added a GitHub Action to your repository, which might fail initially. To address this, you need to modify the GitHub Action:
 
 1. Navigate to the repository
-1. Select Actions
+1. Select **Actions**
 1. You have the option to stop the currently running action
-1. Locate the new GitHub Action *(within this folder Stride Website -> staging-next repo -> .github -> workflows)* which was automatically generated by the Azure Portal. We will need to reference the properties app-name and publish-profile and disable the push trigger.
+1. Locate the new GitHub Action file *(stride-docs/blob/master/.github/workflows/some-file-name.yml)* that was automatically generated by Azure Portal. We need to extract the `app-name` and `publish-profile` values from it and disable the push trigger.
    - To disable the push trigger, retain only **workflow_dispatch** (manual trigger) as shown below:
     ```
     on:
     #  push:
     #    branches:
-    #      - staging-next
+    #      - staging
         workflow_dispatch:
     ```
-1. Open the `stride-website-staging-azure.yml` workflow and update it with the properties from the previous step. Save your changes.
-1. This workflow may also need to be added to the production branch master if it is not already there.
-1. Execute the workflow stride-website-staging-azure.yml. Ensure you select the correct branch staging-next and click **Run workflow**. This action will deploy the website to the Azure Web App.
+1. Open the `stride-docs-staging-azure.yml` workflow and update it with the values obtained in the previous step. Save your changes.
+1. This workflow might also need to be added to the `master` branch if it is not already present.
+1. Execute the workflow `stride-docs-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App.
+
+## Deployment to GitHub Pages
+
+To showcase your updates, especially helpful for design changes pending review, you can deploy the docs website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review.
+
+### Prerequisites
+
+In your `stride-docs` repository:
+
+1. Navigate to **Settings** → **Actions** → **General** → **Workflow Permissions**
+   - Choose **Read and write permissions**
+
+### Run GitHub Action
+
+1. Go to **Actions**, select **Build Stride Web for GitHub Staging**
+   - Click **Run workflow**; you may optionally select a branch
+2. Monitor the build logs while the action is in progress
+3. Upon successful build, a `gh-pages` branch will be created
+4. Navigate to **Settings** → **Pages**
+   - Choose the `gh-pages` branch with the root option and click **Save**
+5. After saving, an internal GitHub Action **pages build and deployment** is automatically created and triggered, deploying the content to the GitHub Pages website
+6. The website will be accessible at `https://[your-username].github.io/stride-docs`

en/contributors/documentation/deployment.md

@@ -1,54 +0,0 @@
-# Deployment
-We tested five different deployment methods and chose Azure Web Apps IIS ASP.NET 4.8.
-
-- [GitHub Pages](#github-pages)
-- [Azure Web Apps](#azure-web-apps)
-  - [Deploying with .NET Framework](#deploying-with-net-framework)
-
-# GitHub Pages
-
-GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files directly from a repository on GitHub, optionally processes the files through a build process, and publishes a website. It is an excellent way to host a website for free and serves as an effective method for testing a website before deploying it to a paid hosting service.
-
-We use GitHub Pages to test our website. Any content pushed to the `staging` branch of the `stride-website` repository is automatically deployed to the `gh-pages` branch, from which GitHub Pages builds and publishes the website.
-
-To manage the build and deployment process, we use the GitHub action `stride-web-staging-github.yml`. This action is triggered when:
-
-1. A push is made to the staging branch
-1. The action is manually triggered
-
-You can manually trigger the action by navigating to the **Actions** tab and clicking the **Run workflow** button.
-
-The `gh-pages` branch is a special branch used by GitHub Pages to host the website and should not be edited directly. Any changes made to the `gh-pages` branch will be overwritten by the subsequent `staging` branch deployment.
-
-The GitHub action `stride-web-staging-github.yml` works as follows:
-
-1. The action is triggered when:
-   - A push is made to the staging branch
-   - The action is manually triggered
-1. `paths-ignore` is used to ignore specific changes to the `staging` branch
-   - Current exclusions: `README.md`, `wiki/**`, `.github/**`
-1. The remaining steps in the action are self-explanatory
-
-# Azure Web Apps
-
-## Deploying with .NET Framework
-
-The .NET Framework uses IIS to host the website, which serves any static files.
-
-The `web.config` file is used to configure IIS, including:
-
-- Mime types for static files
-- Redirects
-- Gzip compression
-- Static file caching
-- Custom Headers
-- Custom 404
-
-The GitHub action `stride-website-staging-azure` builds the website and deploys it to Azure Web Apps.
-
-[Step-by-Step Deployment Guide for Azure Web Apps (Windows) with IIS and Stride Website](deployment-azure.md).
-
-**Recommendation**
-
-1. **ASP.NET 4.8 with IIS** for Staging
-2. **ASP.NET 4.8 with IIS** for Release

en/contributors/documentation/docfx.md

@@ -3,17 +3,7 @@
 
 We used to use **Jekyll** as our static site generator, but we decided to switch to Eleventy because of its flexibility and ease of use. We also wanted to use a tool that is more widely used and supported, which is why we decided to switch to Eleventy.
 
-# Table of Contents
-- [Packages and Dependencies](#packages-and-dependencies)
-- [Configuration](#configuration)
-- [Global Data](#global-data)
-- [Folder Structure](#folder-structure)
-- [Layouts](#layouts)
-- [Includes](#includes)
-- [Advanced Topics](#advanced-topics)
-  - [Creating Custom Shortcodes and Includes](#creating-custom-shortcodes-and-includes)
-  
-# Packages and Dependencies
+## Packages and Dependencies
 Eleventy is a **Node.js** application. Please follow our [installation](installation.md) guide to install Node.js and all the required dependencies.
 
 Packages we currently use:
@@ -31,7 +21,7 @@ Packages we currently use:
   - `markdown-it-table-of-contents` - Table of contents plugin for markdown-it, used mainly in blog posts as `[[TOC]]`
   - `sass` - Sass compiler for our `/css/*.scss` files
 
-# Configuration
+## Configuration
 The Eleventy configuration is located in the `.eleventy.js` file at the root of the project. This file contains all the configuration settings for the Eleventy build process. As it is a JavaScript file, you can utilize all JavaScript features and syntax within it.
 
 **What do you find in this file?**
@@ -44,7 +34,7 @@ The Eleventy configuration is located in the `.eleventy.js` file at the root of
 
 The file is well-commented and should be self-explanatory. If you need to add a new configuration, please follow the existing structure and include a comment to explain the new configuration.
 
-# Global Data
+## Global Data
 
 Global data is located in the `/_data` folder. It contains all the global data that is accessible in all the templates. Currently, we have these JSON files:
 
@@ -61,7 +51,7 @@ Our `site.json` file contains these main properties, with only some listed below
 - `authors` - Contains all the authors used in the blog posts
 - repeated data - like `csharp-version`, `dotnet-version`, `download-version` which are used in multiple places on the website and are updated with every release
 
-# Folder Structure
+## Folder Structure
 
 The folder structure is crucial for Eleventy, as it determines the output of the build process. The folder structure is organized as follows:
 
@@ -82,7 +72,7 @@ The folder structure is crucial for Eleventy, as it determines the output of the
 - `/posts/2014-2021` - Old blog posts which are merged to the same output folder as `/posts`
   - this folder is only for convenience to easily access new posts
 
-**Files**
+### Files
 
 - `/posts/posts.json` - Blog post defaults so they don't have to be repeated in the front matter
 - `*.html` - HTML content pages
@@ -93,7 +83,7 @@ The folder structure is crucial for Eleventy, as it determines the output of the
 - `.eleventyignore` - Lists files and folders not to be processed by Eleventy
 - `package.json` - Eleventy project metadata used by `npm`
 
-**Non Eleventy files:**
+### Non Eleventy files
 
 - `.nojekyll` - Special file for GitHub Pages
 - `CNAME` - Custom domain for GitHub Pages
@@ -106,11 +96,10 @@ The folder structure is crucial for Eleventy, as it determines the output of the
 - `web.config` - Configuration file for IIS deployment
 - `web.Release.config` - Configuration file for Windows ASP.NET Core deployment
 
+> [!NOTE]
+> This project includes Visual Studio solution and files so you can edit the files from the Visual Studio project.
 
-**Note:** This project includes ASP.NET Core solution and files, as they can be used seamlessly with Eleventy. Read more about this in our [Installation](installation.md#asp-net-core.md) section.
-
-
-# Layouts
+## Layouts
 
 All the layouts are located in the `/_layouts` folder. The `default` layout is the main layout page and is used by all the other layouts. 
 
@@ -119,15 +108,15 @@ All the layouts are located in the `/_layouts` folder. The `default` layout is t
 - `page` - Used by most of the pages
 - `post` - Used by blog posts
 
-# Includes
+## Includes
 
 All the includes are located in the `/_includes` folder. The includes are reusable code snippets that can be included in multiple pages.
 
 Some includes are used solely by the layouts, while others are used by the content pages.
 
-# Advanced Topics
+## Advanced Topics
 
-## Creating Custom Shortcodes and Includes
+### Creating Custom Shortcodes and Includes
 
 If you need to create a custom shortcode or include, please follow the existing structure and [include a comment](content.md#shortcodes-and-includes) to explain the new shortcode or include.
 
@@ -135,6 +124,6 @@ The shortcodes are defined in the `.eleventy.js` file, while the includes are lo
 
 You can explore the existing shortcodes and includes to get a better understanding of how they work and how to create new ones.
 
-## Performance Optimization
+### Performance Optimization
 
-ToDo: Remove this section if not needed
+ToDo: Remove this section if not needed

en/contributors/documentation/documentation-generation-pipeline.md

@@ -1,10 +1,7 @@
-# Documentation generation pipeline
-- [Introduction](#introduction)
-- [A Simplified Overview](#a-simplified-overview)
-- [Docs Build Workflow](#docs-build-workflow)
-- [Workflow Diagram](#workflow-diagram)
+# Generation Pipeline
+
+## Introduction
 
-# Introduction
 As of now, **DocFX** does not natively support the generation of multi-language and multi-version documentation. To address this limitation, the Stride team has developed a PowerShell script. Initially, separate scripts were created for each language; however, these have since been consolidated into a single script named [`BuildDocs.ps1`](https://github.com/stride3d/stride-docs/blob/staging/BuildDocs.ps1). This unified script is capable of generating documentation in all supported languages.
 
 The script serves two main purposes:
@@ -12,11 +9,11 @@ The script serves two main purposes:
 - It features a non-interactive mode, utilized by the Continuous Integration/Continuous Deployment (CI/CD) pipeline to automatically generate documentation for all languages and the most recent version, eliminating the need for user intervention.
 - It also offers an interactive command-line UI, allowing users to select which languages they wish to generate documentation for.
 
-# A Simplified Overview
+## A Simplified Overview
 
 Here's a straightforward explanation of how the documentation generation process works.
 
-The `/en` folder serves as the repository for the primary documentation files. When documentation for another language (e.g., Japanese) is built, the files from `/en` are copied over to a temporary folder, for example, `/jp-tmp`. This ensures that the non-English versions will contain all the files present in the `/en` folder. Files that have been translated (found in folders like `/jp`) will overwrite their English counterparts in the temp folder.
+The `/en` folder serves as the repository for the primary documentation files. When documentation for another language (e.g., Japanese) is built, the files from `/en` are copied over to a temporary folder, for example, `/jp-tmp`. This ensures that the non-English versions will contain all the files present in the `/en` folder. Files that have been translated (found in folders like `/jp`) will overwrite their English counterparts in the temp folder `/jp-tmp`.
 
 DocFX is invoked multiple times, once for each language, to create the documentation. The generated documents are stored in the `_site` folder, organized according to the latest version information obtained from `version.json`. For example:
 
@@ -25,18 +22,18 @@ DocFX is invoked multiple times, once for each language, to create the documenta
 /_site/4.1/jp
 ```
 
-## DocFX Files Processed
+### DocFX Files Processed
 
 This section outlines the file processing carried out by DocFX during the documentation generation:
 
-- **Table of Contents (TOC) Files:** 4 files processed
-- **Assets:** 1607 items (images, videos, etc.) included
-- **Conceptual Files:** 304 files processed, resulting in 304 HTML files
+- **Table of Contents (TOC) Files:** 7 files processed
+- **Assets:** 1620 items (images, videos, etc.) included
+- **Conceptual Files:** 358 files processed, resulting in 304 HTML files
 - **Warnings (No API Metadata):** 44 instances encountered
 - **Warnings (API Metadata):** 200 instances of missing or incorrect references
-- **API Files:** 2821 files processed, resulting in 2133 HTML files
+- **API Files:** 2825 files processed, resulting in 2133 HTML files
 
-# Docs Build Workflow
+## Docs Build Workflow
 
 In this part, we elaborate on the individual steps involved in the documentation build workflow for the Stride Docs project.
 
@@ -77,7 +74,7 @@ In this part, we elaborate on the individual steps involved in the documentation
 - **PostProcessing-DocFxDocUrl**
   - Adjusts HTML tags and GitHub links, removing any `_tmp` suffixes. Also updates GitHub links to English if the translation is unavailable.
 
-# Workflow Diagram
+## Workflow Diagram
 
 
 ``` mermaid
@@ -135,7 +132,8 @@ graph TB
     R -->|No| T
     S --> T
     T --> X{{docfx build}}
-    X --> Y
+    X --> X1{{docfx pdf}}
+    X1 --> Y
     Y --> Z
     end
 ```

en/contributors/documentation/index.md

@@ -1,4 +1,5 @@
 # Contributing to documentation
+
 This documentation serves as a comprehensive guide to help you navigate and contribute to the **Stride Docs** website.
 
 If you're looking to make minor changes, such as adding or updating a manual, tutorial or page, or fixing a typo, feel free to jump straight to the [Content Updates](content.md#content-updates) section.
@@ -14,76 +15,15 @@ Here are the technologies we use to build our website:
 - Emojis (because why not? 😎)
 - HTML, JavaScript, CSS, JSON
 - PowerShell scripts
-- GitHub Actions (CI/CD) - Don't worry, this is already set up, you don't need to worry about it.
-
-## Major Version Release Instructions
-
-Assuming the transition is from version `4.1` to `4.2`, and that the Stride source code has been updated to the corresponding .NET version, follow these steps. Note that some steps can be executed at a later stage if needed.
-
-1. Duplicate `ReleaseNotes\ReleaseNotes.md` and rename the copy to `ReleaseNotes-4.1.md`
-1. Update `ReleaseNotes.md`:
-   - Change the content title to `4.2`
-   - Replace the content with the new release notes for version `4.2`
-   - [GitHub Release](https://github.com/stride3d/stride/releases) can be used to generate a list **What's Changed**, once the new tag was added
-1. Modify `ReleaseNotes\toc.yml`
-   - `name: 4.2 release notes` with `href: ReleaseNotes.md`
-   - `name: 4.1 release notes` with `href: ReleaseNotes-4.1.md`
-1. In `en\docfx.json`
-   - `_appFooter`: Increase the version number
-   - Change `TargetFramework` to the current framework version being used. Ensure to test this step locally
-1. Edit `versions.json`
-   - Under `versions`, add the new version `4.2`
-1. For GitHub Actions deployment update `*.yml` files in the `.github\workflows\` folder
-   - `dotnet-version:` Update to the related .NET version
-
-The `BuildDocs.ps1` script will manage the deployment to the `4.2` folder while maintaining accessibility to previous versions. Note, that the deployment profile must be set to not delete existing items.
-
-### Other locations to update
+- GitHub Actions (CI/CD)
+  - Our [GitHub Actions](https://github.com/stride3d/stride-docs/tree/master/.github/workflows) are already configured for deploying to both staging and release environments.
+  - For personal testing or demonstration purposes, you may need to set up your own GitHub Actions. This is especially useful for showcasing proposed changes to maintainers for their approval. For guidance on this, refer to our [Deployment to GitHub Pages guide](deployment-azure.md#deployment-to-github-pages).
 
-1. Update [README.md](https://github.com/stride3d/stride/blob/master/README.md) in the Stride repo, Building from source - Prerequisites section, bump .NET version
+## Dependencies
 
-## Table of Contents
+Various Stride systems rely on content fetched and processed from either the Stride website or the Stride Docs website. It's crucial to ensure that the following links remain active and accessible. Please refrain from removing or altering these links unless the dependent systems have been updated accordingly to accommodate any changes.
 
-- [Understanding the Stride Documentation Generation Pipeline](documentation-generation-pipeline.md)
-    - [Introduction](documentation-generation-pipeline.md#introduction)
-    - [A Simplified Overview](documentation-generation-pipeline.md#a-simplified-overview)
-    - [Docs Build Workflow](documentation-generation-pipeline.md#docs-build-workflow)
-    - [Workflow Diagram](documentation-generation-pipeline.md#workflow-diagram)
-- [Installation](installation.md)
-    - [Prerequisites](installation.md#prerequisites)
-    - [Installation Steps](installation.md#installation-steps)
-    - [Running the Development Server](installation.md#running-the-development-server)
-- [Content Updates](content.md#content-updates)
-    - [Small Updates](content.md#small-updates)
-    - [Major Updates](content.md#major-updates)
-    - [Manual](content.md#manual)
-      - [Creating New Page](content.md#creating-new-manual-page)
-    - [Tutorial](content.md#tutorial)
-      - [Creating New Tutorial](content.md#creating-new-tutorial-page)
-    - [Shortcodes and Includes](content.md#shortcodes-and-includes)
-      - [Alert](content.md#alert)
-      - [Video](content.md#video)
-    - [Web Assets](content.md#web-assets)
-    - [Styling](content.md#styling)
-      - [Bootstrap Customization](content.md#bootstrap-customization)
-      - [CSS Guidelines](content.md#css-guidelines)
-    - [Submitting your Changes](content.md#submitting-your-changes)
-- [New Language](new-language.md)
-    - [Adding a New Language](new-language.md#adding-a-new-language)
-- [Roadmap](roadmap.md)
-- [DocFX](docfx.md)
-    - [Packages and Dependencies](docfx.md#packages-and-dependencies)
-    - [Configuration](docfx.md#configuration)
-    - [Global Data](docfx.md#global-data)
-    - [Folder Structure](docfx.md#folder-structure)
-    - [Layouts](docfx.md#layouts)
-    - [Includes](docfx.md#includes)
-    - [Advanced Topics](docfx.md#advanced-topics)
-        - [Creating Custom Shortcodes and Includes](docfx.md#creating-custom-shortcodes-and-includes)
-- [Deployment](deployment.md)
-    - [GitHub Pages](deployment.md#github-pages)
-    - [Azure Web Apps](deployment.md#azure-web-apps)
-- [Troubleshooting and FAQ](troubleshooting-and-faq.md)
-    - [Known Issues](troubleshooting-and-faq.md#known-issues)
-    - [Common Issues and Solutions](troubleshooting-and-faq.md#common-issues-and-solutions)
-    - [Frequently Asked Questions](troubleshooting-and-faq.md#frequently-asked-questions)
+1. https://doc.stride3d.net/latest/en/index.json
+   - This JSON file is crucial for integrating the Stride Docs search functionality with the Stride Website. It ensures that search results are comprehensive, including relevant information from both the Stride website and Stride Docs.
+1. https://doc.stride3d.net/latest/en/ReleaseNotes/ReleaseNotes.md
+   - The **Stride Launcher** utilizes this file when you click a release notes button.

en/contributors/documentation/major-release-workflow.md

@@ -0,0 +1,25 @@
+# Major Release Workflow
+
+Assuming the transition is from version `4.1` to `4.2`, and that the Stride source code has been updated to the corresponding .NET version, follow these steps. Note that some steps can be executed at a later stage if needed.
+
+1. Duplicate `ReleaseNotes\ReleaseNotes.md` and rename the copy to `ReleaseNotes-4.1.md`
+1. Update `ReleaseNotes.md`:
+   - Change the content title to `4.2`
+   - Replace the content with the new release notes for version `4.2`
+   - [GitHub Release](https://github.com/stride3d/stride/releases) can be used to generate a list **What's Changed**, once the new tag was added
+1. Modify `ReleaseNotes\toc.yml`
+   - `name: 4.2 release notes` with `href: ReleaseNotes.md`
+   - `name: 4.1 release notes` with `href: ReleaseNotes-4.1.md`
+1. In `en\docfx.json`
+   - `_appFooter`: Increase the version number
+   - Change `TargetFramework` to the current framework version being used. Ensure to test this step locally
+1. Edit `versions.json`
+   - Under `versions`, add the new version `4.2`
+1. For GitHub Actions deployment update `*.yml` files in the `.github\workflows\` folder
+   - `dotnet-version:` Update to the related .NET version
+
+The `BuildDocs.ps1` script will manage the deployment to the `4.2` folder while maintaining accessibility to previous versions. Note, that the deployment profile must be set to not delete existing items.
+
+## Other locations to update
+
+1. Update [README.md](https://github.com/stride3d/stride/blob/master/README.md) in the Stride repo, Building from source - Prerequisites section, bump .NET version

en/contributors/documentation/roadmap.md

@@ -6,6 +6,4 @@ This is a proposal for our website roadmap and ongoing website development plan.
 - Streamline the website by decoupling media from the site
   - Host videos on YouTube
   - Host images in Azure Blob Storage or another location
-- Optimize the website for possible deployment on Azure Static Web Apps
-  
-
+- Optimize the website for possible deployment on Azure Static Web Apps

en/contributors/documentation/troubleshooting-and-faq.md

@@ -16,6 +16,4 @@ Any issue should be added to Stride Website [GitHub issues](https://github.com/s
 
 **Q:** I just want to fix a typo in a post. Do I need to follow your installation steps?
 
-**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).*
-
-
+**A:** *No, you can fix the typo directly on the GitHub website. However, you will still need to fork the repo, make your update on the main branch or a new branch, and then create a pull request. You can follow this guide for [minor updates](content.md#small-updates).*

en/contributors/engine/architecture/build-details.md

@@ -1,8 +1,8 @@
-# Build details
+# Build details
 This is a technical description what happens in our build and how it is organized. This covers mostly the build architecture of Stride itself.
 
 * [Targets](../Targets) contains the MSBuild target files used by Games
-* [sources/common/targets](../sources/common/targets) (generic) and [sources/targets](../sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself.
+* [sources/common/targets](../sources/common/targets) (generic) and [sources/targets](https://github.com/stride3d/stride/tree/master/sources/targets) (Stride-specific) contains the MSBuild target files used to build Stride itself.
 
 Since 3.1, we switched from our custom build system to the new csproj system with one nuget package per assembly.
 
@@ -18,7 +18,7 @@ Also, we use `RuntimeIdentifiers` to select graphics platform. [MSBuild.Sdk.Extr
 
 Since we want to package tools (i.e. GameStudio, ConnectionRouter, CompilerApp) with a package that contains only the executable with proper dependencies to other NuGet runtime packages, we use NuGet API to resolve assemblies at runtime.
 
-The code responsible for this is located in [Stride.NuGetResolver](../../../sources/shared/Stride.NuGetResolver).
+The code responsible for this is located in [Stride.NuGetResolver](https://github.com/stride3d/stride/tree/master/sources/shared/Stride.NuGetResolver).
 
 Later, we might want to take advantage of .NET Core dependency resolving to do that natively. Also, we might want to use actual project information/dependencies to resolve to different runtime assemblies and better support plugins.
 

en/contributors/toc.yml

@@ -24,8 +24,8 @@ items:
     href: engine/source-debugging.md
   - name: Visual Studio plugin
     href: engine/visual-studio-plugin.md
-  - name: 🏗️️ Architecture
-    expanded: false
+  - name: 🏗️ Architecture
+    expanded: true
     href: engine/architecture/index.md
     items:
     - name: Build pipeline
@@ -37,27 +37,29 @@ items:
     - name: Dependency graph
       href: engine/architecture/dependency-graph.md
     - name: Asset introspection
-      href: engine/architecture/asset-introspection.html
-- name: 🎓 Contribute to the documentation
+      href: engine/architecture/asset-introspection.md
+- name: 📖 Contribute to the documentation
   expanded: false
   href: documentation/index.md
   items:
-  - name: Documentation generation pipeline
-    href: Documentation/documentation-generation-pipeline.md
+  - name: Generation Pipeline
+    href: documentation/documentation-generation-pipeline.md
   - name: Installation
-    href: Documentation/installation.md
+    href: documentation/installation.md
   - name: Content
-    href: Documentation/content.md
+    href: documentation/content.md
 #  - name: New language
-#    href: Documentation/new-language.md
+#    href: documentation/new-language.md
   - name: Roadmap
-    href: Documentation/roadmap.md
+    href: documentation/roadmap.md
   - name: DocFX
-    href: Documentation/docfx.md
+    href: documentation/docfx.md
   - name: Deployment
-    href: Documentation/deployment-azure.md
+    href: documentation/deployment-azure.md
+  - name: Major Release Workflow
+    href: documentation/major-release-workflow.md
   - name: Troubleshooting and FAQ
-    href: Documentation/troubleshooting-and-faq.md
+    href: documentation/troubleshooting-and-faq.md
 - name: 🌐️ Contribute to the website
   expanded: false
   href: website/index.md

en/index.md

@@ -48,6 +48,15 @@ Welcome to the Stride documentation, specifically designed for game developers,
             <p class="px-3 mb-4"><a class="stretched-link" href="api/index.md">View Stride API Reference</a></p>
         </div>
     </div>
+    <div class="col-md-6">
+        <div class="card h-100">
+            <div class="card-body">
+                <h2 class="card-title h5">🔍 Diagnostics</h2>
+                <p class="card-text">In the world of game development, unexpected behavior is a common challenge. Stride's diagnostic tools are designed to help you quickly and effectively diagnose and resolve these issues.</p>
+            </div>
+            <p class="px-3 mb-4"><a class="stretched-link" href="diagnostics/index.md">Explore Diagnostics</a></p>
+        </div>
+    </div>
 </div>
 
 ## 📥 Download PDF Versions