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

Nice work @VaclavElias 🤣

en/contributors/documentation/deployment-azure.md

@@ -1,24 +1,25 @@
-# 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**
 1. Choose **Create a Web App**
 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/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,22 +108,22 @@ 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.
 
 The shortcodes are defined in the `.eleventy.js` file, while the includes are located in the `/_includes` folder.
 
 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,22 +1,19 @@
-# 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:
 
 - 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
 ```