Merge pull request #178 from Aggror/contributor-section+wiki

Contributor section+wiki

Thank you @Aggror, merging to a new Stride Docs branch with the same name so we could test it. I can deploy to staging only if the branch is present in our repo.

.gitignore

@@ -363,4 +363,5 @@ MigrationBackup/
 FodyWeavers.xsd
 
 _site
-jp_tmp/*
+jp_tmp/*
+.idea

en/contributors/documentation/content.md

@@ -0,0 +1,235 @@
+# Documentation Contents
+
+- [Content Updates](#content-updates)
+  - [Small Updates](#small-updates)
+  - [Major Updates](#major-updates)
+  - [Updating Wiki](#updating-wiki)
+- [Manual](#manual)
+  - [Creating New Page](#creating-new-manual-page)
+- [Tutorial](#tutorial)
+  - [Creating New Tutorial](#creating-new-tutorial-page)
+- [Shortcodes and Includes](#shortcodes-and-includes)
+  - [Alert](#alert)
+  - [Video](#video)
+- [Web Assets](#web-assets)
+- [Styling](#styling)
+  - [Bootstrap Customization](#bootstrap-customization)
+  - [CSS Guidelines](#css-guidelines)
+- [Submitting your Changes](#submitting-your-changes)
+
+# Content Updates
+
+If you want to contribute and update the website, please follow the instructions below.
+
+Small updates can be done directly in the GitHub web interface, for bigger updates the local development environment is required, which is described in the [Installation](Installation) section.
+
+You can use any text editor to make changes. If you are using **Visual Studio**, you can open `Stride.Docs.sln` solution file in the root of the repository and start making your updates directly from this IDE.
+
+You are always welcome to create an issue to discuss your changes before you start working on them. 
+
+## Small Updates
+
+Creating an issue is not required for small updates, but it is recommended to let others know what you are working on. If you are not sure whether your update is small or not, please create an issue first.
+
+### What is a small update?
+
+We can define small updates as changes to the content of the website:
+
+- Update the content of an existing page (manual, tutorial or release note)
+- Add a [new manual](#creating-new-manual-page) or [tutorial](#creating-new-tutorial-page)
+- Fix a typo
+
+### Steps
+
+**Note:** This guide assumes you are already familiar with updating files in GitHub.
+
+1. Go to the [Stride Docs GitHub](https://github.com/stride3d/stride-docs) repository.
+1. Locate the file you wish to edit.
+1. Click the `Edit this file` (pencil) icon in the top right corner.
+1. If prompted, fork the repository by clicking `Fork this repository`.
+1. Make your changes to the file, then write a brief commit message describing the changes.
+1. Click on the `Propose changes` button.
+1. On the next screen, click the `Create pull request` button.
+1. Provide a title and description for your pull request, and click on `Create pull request` again.
+1. Wait for the review and merge.
+
+## Major Updates
+
+[Creating an issue](https://github.com/stride3d/stride-docs/issues) is **required** for major updates, so that others can comment on your changes and provide feedback.
+
+We can define bigger updates as changes to the design of the website, where you would like to see the impact of your changes beforehand to assess the desired result:
+
+- Update docfx version
+- Update layouts
+
+You would start with the local development environment, which is described in the [Installation](Installation) section.
+
+Then you would make your changes and test them locally. Once you are happy with the result, you can create a pull request to merge your changes into the `master` branch.
+
+## Updating Wiki
+
+While wiki pages can be updated directly in the GitHub web interface, this feature is restricted only to contributors who can edit the wiki directly. We have decided to move our wiki pages to a regular folder in this repository called `wiki`, allowing us to use the same process as we do for the website content. If any changes are made directly on the wiki pages, they will be overwritten by the next wiki deployment.
+
+Wiki pages are deployed through a separate GitHub action, `stride-docs-wiki.yml`, which is triggered by updates in the `wiki` folder or can be triggered manually. The `wiki` folder is ignored by the docfx build process, ensuring that the wiki pages are not deployed to the website. Additionally, any pushes to the `wiki` folder will not trigger the website deployment.
+
+You can update the wiki pages as any other content pages, by following the steps in the [Small Updates](#small-updates) section.
+
+⚠️**Important:** If you are updating any headers in the wiki pages, please make sure to update the *Table of Contents* at the top of the page, [Home](Home) page and `_Sidebar.md`. Also, you might need to search for all the links to the updated header and update them as well.
+
+# Manual
+
+These pages contain information about how to use Stride, an open-source C# game engine.
+
+## Creating New Manual Page
+
+1. Create a new file in the `manual` folder, in the already existing folders (e.g. animation, audio, ..) or create a new folder in the `manual` folder.
+   - If you created a new folder, make sue that you create also index.md file in this folder.
+1. Use any existing page as a template for the new page.
+1. Update `toc.md` file in the `manual` folder to include the new page or folder. The `toc.md` file contains the table of contents for the manual pages, which is displayed on the left side of the manual pages.
+
+## Naming Convention
+
+Observe existing pages and folders for the naming convention.
+
+## Media
+
+You can observe that existing folders might have a `media` folder. This folder contains images and videos used in the manual pages. You can use this folder or create a new one in your folder. If possible make sure that images are `.webp` format and videos are `.mp4` format.
+
+# Tutorial
+
+These pages contain tutorials on how to use Stride, an open-source C# game engine.
+
+## Creating New Tutorial Page
+
+1. Create a new tutorial folder in the `tutorial` folder.
+1. Create a new index.md file in this folder. Observe existing tutorials for the content of this file.
+1. Create markdown files for each step of the tutorial. Observe existing tutorials structure for the content of these files.
+1. Update `toc.md` file in the `tutorial` folder to include the new tutorial folder. The `toc.md` file contains the table of contents for the tutorial pages, which is displayed on the left side of the tutorial pages.
+
+## Naming Convention
+
+Observe existing pages and folders for the naming convention.
+
+## Media
+
+You can observe that existing tutorials have a `media` folder. This folder contains images. If possible make sure that images are `.webp` format. The videos should be uploaded to YouTube and embedded in the tutorial pages.
+
+# Shortcodes and Includes
+
+Read docfx documentation about [shortcodes and inludes](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet). Some of them are briefly described below.
+
+## Alert
+
+```liquid
+> [!NOTE]
+> Information the user should notice even if skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Essential information required for user success.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+
+> [!WARNING]
+> Dangerous certain consequences of an action.
+```
+
+## Video
+
+We should consider hosting our videos on YouTube whenever possible. 
+
+You can embed a video by using the following Markdown syntax:
+
+`> [!Video embed_link]`
+
+Replace `embed_link` with the YouTube video link. This shortcode renders as:
+
+Example:
+```md
+> [!Video https://www.youtube.com/embed/-IXw64hZAqg]
+```
+
+To embed a video hosted elsewhere, use the following shortcode:
+
+### Hosting our own videos
+
+`{% video 'url' %}`
+
+Replace `url` with the video URL (e.g., .mp4 file). Make sure you have a matching .jpg file with the same name as the .mp4 file for the poster attribute. This shortcode renders as:
+
+```html
+<!-- jpgUrl = url.replace(".mp4", ".jpg") // make sure you have a pair .mp4 and .jpg -->
+<div class="ratio ratio-16x9 mb-2"><video autoplay loop class="responsive-video" poster="jpgUrl"><source src="url" type="video/mp4"></video></div>
+```
+
+### How to encode videos
+
+Videos can be generated by many software in various formats & size, so they might end up being incompatible with web browsers or mobile, or simply be way too large.
+It is better to stick to a format with low requirements such as H264 baseline profile (works almost everywhere).
+
+To do so, process the file using [fmpeg](https://ffmpeg.org/download.html):
+
+```
+ffmpeg -i myvideo_original.mp4 -profile:v baseline -level 3.0 -an myvideo.mp4
+```
+
+Also, generate a static thumbnail so that people can preview it before downloading the video (very important on mobile):
+
+ToDo: Check if webp can be generated from ffmpeg
+
+```
+ffmpeg -i myvideo.mp4 -vframes 1 -f image2 -y myvideo.jpg
+```
+
+ToDo: Maybe we could provide a simple tool to do that without using command line.
+
+
+
+# Web Assets
+
+Our main web assets are:
+
+- `css/custom-bootstrap.scss` - Slightly modified Bootstrap theme
+  - Some Bootstrap variables are overridden
+  - Some Bootstrap parts are disabled so they don't bloat the website (e.g. button-group, breadcrumb, ..)
+- `css/styles.scss` - Main stylesheet
+  - Styles also Dark Mode
+- `css/syntax-highlighting.scss` - Imported prismjs styling, Light and Dark Mode
+- `assets/search.liquid` - Script for search
+- `assets/site.liquid` - Not used
+- `assets/theme-selector.liquid` - Script for Ligth and Dark Mode selection
+- `search.liquid` - Renders as `search.json` contains search meta
+
+
+# Styling
+
+## Bootstrap Customization
+
+Our website uses the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**.
+
+Prioritize using Bootstrap styling before introducing any custom styles. 
+
+## CSS Guidelines
+
+We aim to write minimum CSS code to keep the website lightweight and use the Bootstrap framework as much as possible. 
+
+Further, we are using also [FontAwesome](https://fontawesome.com/) free icons. The icons are loaded in the `src/_includes/css/main.css` file.
+
+# Submitting your Changes
+
+Assuming you have made all necessary changes and tested them on the development server, you can submit a pull request to the `master` branch. The pull request will be reviewed and merged by the website maintainers.
+
+Steps to contribute your updates:
+
+1. Commit your changes to your forked repository:
+   - Commit the changes with a meaningful message
+   - Push the changes to your forked repository
+1. Create a pull request to the main repository:
+   - You can create a pull request from your forked repository by navigating to Pull requests page and click **New pull request** button
+   - Select the **master** branch as the base branch and your branch as the compare branch
+   - Click **Create pull request** button
+
+Once your pull request has been reviewed and approved, your changes will be merged into the main repository and deployed to the website.

en/contributors/documentation/deployment-azure.md

@@ -0,0 +1,73 @@
+# Table of Contents
+
+- [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)
+
+# Step-by-Step Guide to Deploying Azure Web Apps (Windows) with IIS
+
+This guide assumes you already have permission to access the Azure subscription.
+
+## Setting up a new Azure Web App (Windows) with IIS
+
+These instructions pertain to the staging environment. For the production environment, follow the same steps, but with a different web app name.
+
+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**
+      - Publish: **Code**
+      - Runtime stack: **ASP.NET V4.8**
+      - OS: **Windows**
+      - Region: as the current web
+      - Pricing Plan - An existing App Service Plan should appear if the region and resource group match that of the existing web app. Currently we use **Standard S1**.
+      - 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`
+   - Click **Next**
+1. In the Monitoring Tab
+   - Leave all settings as default
+   - Click **Next**
+1. Monitoring Tab
+   - Disable Application Insights - This is not needed at this stage
+   - Click **Next**
+1. In the Tags Tab
+   - Leave this blank unless you wish to add tags
+   - Click **Next**
+1. In the Review Tab
+   - Review your settings
+   - 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
+
+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. Click **Save** to apply the changes
+
+## 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.
+
+1. Navigate to the repository
+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.
+   - To disable the push trigger, retain only **workflow_dispatch** (manual trigger) as shown below:
+    ```
+    on:
+    #  push:
+    #    branches:
+    #      - staging-next
+        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.

en/contributors/documentation/deployment.md

@@ -0,0 +1,75 @@
+# Table of Contents
+
+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)
+- [Deployment To Wiki](#deployment-to-wiki)
+
+# 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).
+
+# Deployment To Wiki
+
+While the GitHub wiki offers a convenient way to document a project, it has some drawbacks, such as not being part of the repository by default and restricting edits to collaborators. To address these issues and allow community editing, we have implemented an alternative approach.
+
+We created a `wiki` folder within the repository, which contains all wiki pages. The GitHub action `stride-web-wiki.yml` deploys the `wiki` folder to the GitHub wiki.
+
+The GitHub action `stride-web-wiki.yml` is triggered when:
+
+1. A push is made to the `master` branch of the `stride-website` repository
+1. The action is manually triggered
+
+You can manually trigger the action by navigating to the **Actions** tab and clicking the **Run workflow** button.
+
+This GitHub action only monitors changes to the `wiki` folder. Any modifications made to the `wiki` folder will be deployed to the GitHub wiki. Note that changes to the `wiki` folder will not trigger other GitHub actions.
+
+We use the [Wiki Page Creator GitHub Action](https://github.com/marketplace/actions/wiki-page-creator-action) to deploy the `wiki` folder to the GitHub wiki.
+
+**Note**: ⚠️ A GitHub personal access token (GH_PAT) is required for authentication. This token is stored as a secret in the repository settings.⚠️
+
+**Recommendation**
+
+1. **ASP.NET 4.8 with IIS** for Staging
+1. **ASP.NET 4.8 with IIS** for Release