From 6c290d2320a12a95aa31b10464149ee7964e96f5 Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Thu, 30 Nov 2023 22:50:52 +0000 Subject: [PATCH 1/5] feat: Various content revisions --- en/contributors/documentation/index.md | 1 + en/contributors/documentation/installation.md | 20 +++++-------------- .../documentation/major-release-workflow.md | 5 ++++- en/contributors/website/installation.md | 5 +---- en/includes/docs-prerequisites.md | 5 +++++ 5 files changed, 16 insertions(+), 20 deletions(-) create mode 100644 en/includes/docs-prerequisites.md diff --git a/en/contributors/documentation/index.md b/en/contributors/documentation/index.md index c6ce88945..33452b869 100644 --- a/en/contributors/documentation/index.md +++ b/en/contributors/documentation/index.md @@ -9,6 +9,7 @@ For more extensive updates 🤯🤦‍♂️ or for a deeper understanding of th Here are the technologies we use to build our website: - [docfx](https://dotnet.github.io/docfx/index.html) (static site generator) + - A specific version of docfx is utilized in GitHub Actions, one that has been thoroughly tested. Should you wish to upgrade this version, please ensure it is properly tested before implementation. - Markdown - [Mustache](https://mustache.github.io/) template engine (docfx dropped Liquid template engine support) - Bootstrap diff --git a/en/contributors/documentation/installation.md b/en/contributors/documentation/installation.md index 0c9d31e2f..9ec012f81 100644 --- a/en/contributors/documentation/installation.md +++ b/en/contributors/documentation/installation.md @@ -1,27 +1,17 @@ # Local installation This guide will walk you through the steps to install the Stride Docs website on your local machine for development purposes. Although we use the Windows operating system for development, the steps should be similar for other operating systems. -[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the **docfx** static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. +[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the [docfx](https://dotnet.github.io/docfx/index.html) static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. This guide assumes you have a basic understanding of the technologies used in the Stride docs website. -# Table of Contents - -- [Prerequisites](#prerequisites) -- [Installation Steps](#installation-steps) -- [Running the Development Server](#running-the-development-server) - -# Prerequisites +## Prerequisites Before updating the Stride Docs, ensure you are familiar with the following prerequisites: -1. Familiarity with the command line -1. **.NET SDK 6.0 or higher:** You can download the installer from the [.NET SDK website](https://dotnet.microsoft.com/en-us/download) - - If .NET SDK is already installed, ensure you have version 6.0 or higher. You can check your version by running `dotnet --info` in a terminal. -1. **Git installed:** You will need Git for version control. If you don't have Git installed, you can download it from the [Git website](https://git-scm.com/downloads) -1. **Development IDE of choice:** Choose an Integrated Development Environment (IDE) that you're comfortable with for development. Although there are various popular choices, such as Visual Studio, Visual Studio Code, and others, this guide will focus on using **Visual Studio**, as it is the primary IDE for the Stride project, and as of writing, we use **Visual Studio 2022**. You can download the free Community edition from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/) +[!INCLUDE [docs-prerequisites](../../includes/docs-prerequisites.md)] -# Installation Steps +## Installation Steps 1. ❓You might want to create an issue so we can track your contribution and avoid duplicate work. If you're unsure whether your contribution is needed, feel free to create an issue and ask 1. 🍴 Fork the repository by navigating to the [Stride Docs repository](https://github.com/stride3d/stride-docs) and clicking the **Fork** button in the top-right corner @@ -65,7 +55,7 @@ Uninstall docfx if you need to downgrade dotnet tool uninstall -g docfx ``` -# Running the Development Server +## Running the Development Server We've created a PowerShell script [BuildDocs.ps1](https://github.com/stride3d/stride-docs/blob/master/BuildDocs.ps1) with a context menu where you can select the language, include the API build, and run the development server. diff --git a/en/contributors/documentation/major-release-workflow.md b/en/contributors/documentation/major-release-workflow.md index 5c640d87b..74d4cf8b2 100644 --- a/en/contributors/documentation/major-release-workflow.md +++ b/en/contributors/documentation/major-release-workflow.md @@ -22,4 +22,7 @@ The `BuildDocs.ps1` script will manage the deployment to the `4.2` folder while ## 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 \ No newline at end of file +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 + +1. Modify `contributors\documentation\installation.md` + - Update SDK version \ No newline at end of file diff --git a/en/contributors/website/installation.md b/en/contributors/website/installation.md index 0bda44b61..52a712e92 100644 --- a/en/contributors/website/installation.md +++ b/en/contributors/website/installation.md @@ -10,10 +10,7 @@ This guide assumes you have a basic understanding of the technologies used in th Before updating the Stride website, ensure you are familiar with the following prerequisites: -1. **Node.js 16+ (including npm) installed:** You can download the installer from the [Node.js website](https://nodejs.org/en/download) - - If Node.js is already installed, ensure you have version 16 or higher. You can check your version by running `node -v` in a terminal. Note that `npm`, the package manager for Node.js, is included with the installation -1. **Git installed:** You will need Git for version control. If you don't have Git installed, you can download it from the [Git website](https://git-scm.com/downloads) -1. **Development IDE of choice:** Choose an Integrated Development Environment (IDE) that you're comfortable with for development. Although there are various popular choices, such as Visual Studio, Visual Studio Code, and others, this guide will focus on using **Visual Studio**, as it is the primary IDE for the Stride project, and as of writing, we use **Visual Studio 2022**. You can download the free Community edition from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/) +[!INCLUDE [docs-prerequisites](../../includes/docs-prerequisites.md)] ## Installation Steps diff --git a/en/includes/docs-prerequisites.md b/en/includes/docs-prerequisites.md new file mode 100644 index 000000000..c12538c58 --- /dev/null +++ b/en/includes/docs-prerequisites.md @@ -0,0 +1,5 @@ +1. Familiarity with the command line +1. **.NET SDK 8.0 or higher:** You can download the installer from the [.NET SDK website](https://dotnet.microsoft.com/en-us/download) + - If .NET SDK is already installed, ensure you have version 8.0 or higher. You can check your version by running `dotnet --info` in a terminal. +1. **Git installed:** You will need Git for version control. If you don't have Git installed, you can download it from the [Git website](https://git-scm.com/downloads) +1. **Development IDE of choice:** Choose an Integrated Development Environment (IDE) that you're comfortable with for development. Although there are various popular choices, such as Visual Studio, Visual Studio Code, and others, this guide will focus on using **Visual Studio**, as it is the primary IDE for the Stride project, and as of writing, we use **Visual Studio 2022**. You can download the free Community edition from the [Visual Studio website](https://visualstudio.microsoft.com/downloads/) \ No newline at end of file From c36b1852de363673a302d69833d7db74cbf73975 Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Thu, 30 Nov 2023 23:48:07 +0000 Subject: [PATCH 2/5] feat: Content section updated --- en/contributors/documentation/content.md | 219 ++++++------------ .../documentation/major-release-workflow.md | 1 - en/contributors/website/content.md | 32 +-- en/docfx.json | 2 +- en/includes/small-update-instructions.md | 9 + en/includes/submitting-changes.md | 13 ++ en/template/public/main.css | 2 +- 7 files changed, 97 insertions(+), 181 deletions(-) create mode 100644 en/includes/small-update-instructions.md create mode 100644 en/includes/submitting-changes.md diff --git a/en/contributors/documentation/content.md b/en/contributors/documentation/content.md index cdbb0f217..45495ab95 100644 --- a/en/contributors/documentation/content.md +++ b/en/contributors/documentation/content.md @@ -1,21 +1,6 @@ # Documentation content -- [Content Updates](#content-updates) - - [Small Updates](#small-updates) - - [Major Updates](#major-updates) -- [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 + +## Content Updates If you want to contribute and update the website, please follow the instructions below. @@ -23,201 +8,129 @@ Small updates can be done directly in the GitHub web interface, for bigger updat 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. +You are always welcome to [create an issue](https://github.com/stride3d/stride-docs/issues) to discuss your changes before you start working on them. -## Small Updates +### 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? +#### 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) +- 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) or any new content - Fix a typo -### Steps +#### Steps + +> [!NOTE] +> This guide assumes that you are already familiar with updating files on GitHub. -**Note:** This guide assumes you are already familiar with updating files in GitHub. +For the following instructions, use the [Stride Docs GitHub repository](https://github.com/stride3d/stride-docs): -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. +[!INCLUDE [small-updates](../../includes/small-update-instructions.md)] -## Major Updates +### 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: +Major updates can be defined as significant changes to the website's design, where it's beneficial to preview the impact of your changes to ensure they achieve the desired result. This may include: - Update docfx version -- Update layouts +- Modifying layouts +- Revamping design elements -You would start with the local development environment, which is described in the [Installation](installation.md) section. +Start by setting up your local development environment, as described in the [Installation](installation.md) section. After making and testing your changes locally, you should create a pull request to merge your changes into the `master` branch. -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. +When submitting a pull request, especially for substantial changes, it's recommended to include **screenshots** or a link to your local deployment. This approach helps maintainers visualize and assess your proposed changes more effectively. If you prefer to use GitHub infrastructure for your demonstrations, refer to our [Deployment to GitHub Pages guide](deployment-azure.md#deployment-to-github-pages) for instructions on deploying via GitHub Actions. -# Manual +## Manual These pages contain information about how to use Stride, an open-source C# game engine. -## Creating New Manual Page +> [!IMPORTANT] +> **SEO Note:** Ensure that the file name includes essential keywords related to the content of the article. This is crucial because the file name dictates the URL of the content page, which plays a significant role in search engine optimization (SEO). + +### 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. + - 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. +1. Update `toc.yml` (or `toc.md`) file in the `manual` folder to include the new page or folder. The `toc.yml` file contains the table of contents for the manual pages, which is displayed on the left side of the manual pages. These pages are also included in the optionally generated PDF file. -## Naming Convention +### Naming Convention Observe existing pages and folders for the naming convention. -## Media +### 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 +## Tutorial These pages contain tutorials on how to use Stride, an open-source C# game engine. -## Creating New Tutorial Page +### 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 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. +1. Update `toc.yml` file in the `tutorial` folder to include the new tutorial folder. The `toc.yml` file contains the table of contents for the tutorial pages, which is displayed on the left side of the tutorial pages. -## Naming Convention +### Naming Convention Observe existing pages and folders for the naming convention. -## Media +### 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]` +## Other Sections -Replace `embed_link` with the YouTube video link. This shortcode renders as: +In addition to the Manual and Tutorial sections mentioned above, the same principles apply to both existing and new sections. Follow the established formats and conventions to ensure consistency and clarity throughout the documentation. -Example: -```md -> [!Video https://www.youtube.com/embed/-IXw64hZAqg] -``` +## Shortcodes and Includes -To embed a video hosted elsewhere, use the following shortcode: +Docfx supports additional markdown syntax to enrich content. These syntaxes are specific to docfx and **may not render** correctly on other platforms, like GitHub. -### Hosting our own videos +For more information, read the docfx documentation on [shortcodes and includes](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet). Some commonly used features include: -`{% video 'url' %}` +- **Alert**: These are block quotes that render with distinct colors and icons, highlighting the importance or nature of the content +- **Video**: Embed video content directly into your documentation +- **Image**: Insert images to enhance the visual aspect of the documentation +- **Math Expressions**: Integrate mathematical notations and expressions +- **Mermaid Diagrams**: Embed [mermaid diagrams](https://mermaid.js.org/) for flowcharts and other graphical representations +- **Include Markdown Files**: Include content from other markdown files seamlessly +- **Code Snippet**: Insert code snippets for better clarity and demonstration +- **Tabs**: Organize content into tabbed sections for improved readability -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: +## Web Assets -```html - -
-``` +Our main web assets include: -### How to encode videos +- `template/partials/affix.tmpl.partial` - Currently not functioning +- `template/partials/footer.tmpl.partial` - Currently not functioning +- `template/public/main.css` - Contains minor Bootstrap CSS overrides +- `template/public/main.js`: + - Sets the top navigation icons, such as GitHub, Discord, Twitter + - Injects the Stride Docs version selection above the filter in the side navigation + - Injects the Stride Docs language selection into the top navigation +- `docfx.json` - The HTML footer is included in the `_appFooter` section -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). +## Styling -To do so, process the file using [fmpeg](https://ffmpeg.org/download.html): +### Bootstrap Customization -``` -ffmpeg -i myvideo_original.mp4 -profile:v baseline -level 3.0 -an myvideo.mp4 -``` +We utilize the `modern` template provided by docfx, which employs the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**. This includes the dark theme, enabled by docfx. -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 +> [!IMPORTANT] +> Prioritize the use of Bootstrap's inherent styling before integrating any custom styles. You should be familiar with [Bootstrap Utilities](https://getbootstrap.com/docs/5.3/utilities/api/) which help you to achieve most of the styling requirements. -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. +### CSS Guidelines -Steps to contribute your updates: +Our goal is to write minimal CSS code to keep the website lightweight, leveraging the Bootstrap framework to the fullest extent possible. -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 +## Submitting your Changes -Once your pull request has been reviewed and approved, your changes will be merged into the main repository and deployed to the website. \ No newline at end of file +[!INCLUDE [submitting-changes](../../includes/submitting-changes.md)] \ No newline at end of file diff --git a/en/contributors/documentation/major-release-workflow.md b/en/contributors/documentation/major-release-workflow.md index 74d4cf8b2..711b75e85 100644 --- a/en/contributors/documentation/major-release-workflow.md +++ b/en/contributors/documentation/major-release-workflow.md @@ -23,6 +23,5 @@ The `BuildDocs.ps1` script will manage the deployment to the `4.2` folder while ## 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 - 1. Modify `contributors\documentation\installation.md` - Update SDK version \ No newline at end of file diff --git a/en/contributors/website/content.md b/en/contributors/website/content.md index 1fdf2d217..c00b84c45 100644 --- a/en/contributors/website/content.md +++ b/en/contributors/website/content.md @@ -8,7 +8,7 @@ Small updates can be done directly in the GitHub web interface, for bigger updat You can use any text editor to make changes. If you are using **Visual Studio**, you can open `Stride.Web.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. +You are always welcome to [create an issue](https://github.com/stride3d/stride-website) to discuss your changes before you start working on them. ### Small Updates @@ -28,17 +28,11 @@ We can define small updates as changes to the content of the website: #### Steps > [!NOTE] -> This guide assumes you are already familiar with updating files in GitHub. - -1. Go to the [Stride Website GitHub](https://github.com/stride3d/stride-website) 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 +> This guide assumes that you are already familiar with updating files on GitHub. + +For the following instructions, use the [Stride Website GitHub repository](https://github.com/stride3d/stride-website): + +[!INCLUDE [small-updates](../../includes/small-update-instructions.md)] ### Major Updates @@ -221,16 +215,4 @@ Further, we are using also [FontAwesome](https://fontawesome.com/) free icons. T ## 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. \ No newline at end of file +[!INCLUDE [submitting-changes](../../includes/submitting-changes.md)] \ No newline at end of file diff --git a/en/docfx.json b/en/docfx.json index 2de9be8c2..0da66bf99 100644 --- a/en/docfx.json +++ b/en/docfx.json @@ -147,4 +147,4 @@ "keepFileLink": false, "disableGitFeatures": false } -} +} \ No newline at end of file diff --git a/en/includes/small-update-instructions.md b/en/includes/small-update-instructions.md new file mode 100644 index 000000000..31d40f731 --- /dev/null +++ b/en/includes/small-update-instructions.md @@ -0,0 +1,9 @@ +1. Go to the 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 \ No newline at end of file diff --git a/en/includes/submitting-changes.md b/en/includes/submitting-changes.md new file mode 100644 index 000000000..b360f5054 --- /dev/null +++ b/en/includes/submitting-changes.md @@ -0,0 +1,13 @@ +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. \ No newline at end of file diff --git a/en/template/public/main.css b/en/template/public/main.css index 0b3888511..90cda5be0 100644 --- a/en/template/public/main.css +++ b/en/template/public/main.css @@ -43,4 +43,4 @@ footer .link-danger { color: var(--stride-red-web); -} +} \ No newline at end of file From e5d4320e1bb12ca739740521155eef4dade76501 Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Thu, 30 Nov 2023 23:55:04 +0000 Subject: [PATCH 3/5] feat: Roadmap page updated --- en/contributors/documentation/roadmap.md | 15 +++++++-------- en/contributors/website/roadmap.md | 14 +++++++------- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/en/contributors/documentation/roadmap.md b/en/contributors/documentation/roadmap.md index a495e6468..704274f83 100644 --- a/en/contributors/documentation/roadmap.md +++ b/en/contributors/documentation/roadmap.md @@ -1,9 +1,8 @@ -# Documentation roadmap -This is a proposal for our website roadmap and ongoing website development plan. +# Documentation Roadmap -- Tackle existing issues listed in the [Issues](https://github.com/stride3d/stride-website/issues) -- Convert images to WebP for better performance -- 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 \ No newline at end of file +This document outlines a proposed roadmap and an ongoing development plan for our Stride Docs website. + +- **Address Existing Issues**: Prioritize resolving issues listed in the [Issues](https://github.com/stride3d/stride-docs/issues) section on GitHub. +- **Image Optimization**: Convert existing images to the WebP format to enhance website performance. +- **Content Enhancement**: Implement improvements across all sections of the documentation to ensure clarity, accuracy, and comprehensiveness. +- **Guidance for Contributors**: Provide clear instructions for contributors on writing XML comments in C#, which play a crucial role in enhancing the API documentation. \ No newline at end of file diff --git a/en/contributors/website/roadmap.md b/en/contributors/website/roadmap.md index 28c6b81c8..7fd8df866 100644 --- a/en/contributors/website/roadmap.md +++ b/en/contributors/website/roadmap.md @@ -1,9 +1,9 @@ # Website roadmap -This is a proposal for our website roadmap and ongoing website development plan. -- Tackle existing issues listed in the [Issues](https://github.com/stride3d/stride-website/issues) -- Convert images to WebP for better performance -- 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 \ No newline at end of file +This document outlines a proposed roadmap and an ongoing development plan for our Stride website. + +- **Address Existing Issues**: Prioritize resolving issues listed in the [Issues](https://github.com/stride3d/stride-website/issues) section on GitHub. +- **Image Optimization**: Convert existing images to the WebP format to enhance website performance. +- **Decoupling Media**: Streamline the website by decoupling media from the site + - Consider hosting videos on YouTube + - Consider hosting images in Azure Blob Storage or another location \ No newline at end of file From 22b64d4c02aa9b2e9a861f0e70d9226674790917 Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Fri, 1 Dec 2023 00:07:37 +0000 Subject: [PATCH 4/5] feat: docfx file updated --- en/contributors/documentation/docfx.md | 28 ++++++++------------------ 1 file changed, 8 insertions(+), 20 deletions(-) diff --git a/en/contributors/documentation/docfx.md b/en/contributors/documentation/docfx.md index 0ea51a3b2..f91c9fe33 100644 --- a/en/contributors/documentation/docfx.md +++ b/en/contributors/documentation/docfx.md @@ -1,28 +1,16 @@ -# DocFX -[docfx](https://www.11ty.dev/) is a static site generator that uses JavaScript as its templating language. It is a very powerful tool that allows us to create a website with a lot of flexibility and customization. It is also very easy to use and learn. This section will cover the basics of Eleventy configuration on the Stride website. Creating and updating the content is described in our [Content](content.md) section. +# Docfx -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. +[Docfx](https://dotnet.github.io/docfx/index.html) is a static site generator that uses C# as its templating language. It is an exceptionally powerful tool, offering immense flexibility and customization options for creating a documentation website. Moreover, Docfx is user-friendly and easy to learn. This section covers the basics of Docfx configuration for the Stride Docs website, while the creation and updating of content are detailed in our [Content](content.md) section. + +After reviewing various static site generator options, we decided to continue using Docfx, particularly in light of the release of the new `modern` Docfx template. This template leverages Bootstrap 5.3 and has recently introduced a dark theme feature. ## 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: - -- Dev Dependencies - - `@11ty/eleventy` v2.0 - Main package for the static site generator - - `@11ty/eleventy-plugin-rss` - RSS feed plugin - - `@11ty/eleventy-plugin-syntaxhighlight` - Syntax highlighting plugin (dark and light theme in `/css/syntax-highlighting.scss`) -- Dependencies - - `@11ty/eleventy-fetch` - Fetch plugin - - `@fortawesome/fontawesome-free` - Font Awesome with a variety of awesome icons 😃🤩 - - `bootstrap` - Bootstrap 5.3 - - `lunr` - Lunr search plugin that consumes local `search.json (/search.liquid)` and remote `index.json` from the docs website; the script is in `/assets/scripts/search.liquid` - - `markdown-it-anchor` - Anchor plugin for markdown-it - - `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 + +Currently, we are not utilizing any additional packages. ## 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. + +The configuration for Docfx is located in the `en\docfx.json` file. This file contains all the settings necessary for the Docfx build process. **What do you find in this file?** From cceaaab9d20fa2d20cf933424cafdf8acede33be Mon Sep 17 00:00:00 2001 From: Vaclav Elias Date: Fri, 1 Dec 2023 00:11:22 +0000 Subject: [PATCH 5/5] feat: DoxFX renamed to official Docfx --- en/contributors/documentation/content.md | 8 ++++---- .../documentation/documentation-generation-pipeline.md | 8 ++++---- en/contributors/documentation/index.md | 6 +++--- en/contributors/documentation/installation.md | 10 +++++----- en/contributors/toc.yml | 2 +- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/en/contributors/documentation/content.md b/en/contributors/documentation/content.md index 45495ab95..8043884be 100644 --- a/en/contributors/documentation/content.md +++ b/en/contributors/documentation/content.md @@ -37,7 +37,7 @@ For the following instructions, use the [Stride Docs GitHub repository](https:// Major updates can be defined as significant changes to the website's design, where it's beneficial to preview the impact of your changes to ensure they achieve the desired result. This may include: -- Update docfx version +- Update Docfx version - Modifying layouts - Revamping design elements @@ -92,9 +92,9 @@ In addition to the Manual and Tutorial sections mentioned above, the same princi ## Shortcodes and Includes -Docfx supports additional markdown syntax to enrich content. These syntaxes are specific to docfx and **may not render** correctly on other platforms, like GitHub. +Docfx supports additional markdown syntax to enrich content. These syntaxes are specific to Docfx and **may not render** correctly on other platforms, like GitHub. -For more information, read the docfx documentation on [shortcodes and includes](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet). Some commonly used features include: +For more information, read the Docfx documentation on [shortcodes and includes](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet). Some commonly used features include: - **Alert**: These are block quotes that render with distinct colors and icons, highlighting the importance or nature of the content - **Video**: Embed video content directly into your documentation @@ -122,7 +122,7 @@ Our main web assets include: ### Bootstrap Customization -We utilize the `modern` template provided by docfx, which employs the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**. This includes the dark theme, enabled by docfx. +We utilize the `modern` template provided by Docfx, which employs the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**. This includes the dark theme, enabled by Docfx. > [!IMPORTANT] > Prioritize the use of Bootstrap's inherent styling before integrating any custom styles. You should be familiar with [Bootstrap Utilities](https://getbootstrap.com/docs/5.3/utilities/api/) which help you to achieve most of the styling requirements. diff --git a/en/contributors/documentation/documentation-generation-pipeline.md b/en/contributors/documentation/documentation-generation-pipeline.md index 9503528b0..3cf6e98cc 100644 --- a/en/contributors/documentation/documentation-generation-pipeline.md +++ b/en/contributors/documentation/documentation-generation-pipeline.md @@ -2,7 +2,7 @@ ## 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. +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: @@ -15,16 +15,16 @@ Here's a straightforward explanation of how the documentation generation process 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: +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: ``` /_site/4.1/en /_site/4.1/jp ``` -### DocFX Files Processed +### Docfx Files Processed -This section outlines the file processing carried out by DocFX during the documentation generation: +This section outlines the file processing carried out by Docfx during the documentation generation: - **Table of Contents (TOC) Files:** 7 files processed - **Assets:** 1620 items (images, videos, etc.) included diff --git a/en/contributors/documentation/index.md b/en/contributors/documentation/index.md index 33452b869..c8b2da96c 100644 --- a/en/contributors/documentation/index.md +++ b/en/contributors/documentation/index.md @@ -8,10 +8,10 @@ For more extensive updates 🤯🤦‍♂️ or for a deeper understanding of th Here are the technologies we use to build our website: -- [docfx](https://dotnet.github.io/docfx/index.html) (static site generator) - - A specific version of docfx is utilized in GitHub Actions, one that has been thoroughly tested. Should you wish to upgrade this version, please ensure it is properly tested before implementation. +- [Docfx](https://dotnet.github.io/docfx/index.html) (static site generator) + - A specific version of Docfx is utilized in GitHub Actions, one that has been thoroughly tested. Should you wish to upgrade this version, please ensure it is properly tested before implementation. - Markdown -- [Mustache](https://mustache.github.io/) template engine (docfx dropped Liquid template engine support) +- [Mustache](https://mustache.github.io/) template engine (Docfx dropped Liquid template engine support) - Bootstrap - Emojis (because why not? 😎) - HTML, JavaScript, CSS, JSON diff --git a/en/contributors/documentation/installation.md b/en/contributors/documentation/installation.md index 9ec012f81..c7275aa66 100644 --- a/en/contributors/documentation/installation.md +++ b/en/contributors/documentation/installation.md @@ -1,7 +1,7 @@ # Local installation This guide will walk you through the steps to install the Stride Docs website on your local machine for development purposes. Although we use the Windows operating system for development, the steps should be similar for other operating systems. -[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the [docfx](https://dotnet.github.io/docfx/index.html) static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. +[Minor updates](content.md#small-updates) can be made directly on GitHub. However, for [more significant updates](content.md#major-updates) that affect multiple pages, we recommend using a local development environment so you can see the impact of your changes beforehand. This is because we use the [Docfx](https://dotnet.github.io/docfx/index.html) static site generator, and in some cases, all pages need to be regenerated. This approach helps you assess your changes before submitting a pull request. This guide assumes you have a basic understanding of the technologies used in the Stride docs website. @@ -20,7 +20,7 @@ Before updating the Stride Docs, ensure you are familiar with the following prer 1. Make sure you have also Stride repo cloned on **the same level** as stride-docs, read more about it [here](https://github.com/stride3d/stride) - This repo is needed for API documentation generation 1. 📁 Go to the project folder `cd stride-docs` -1. 🚀 Let's start with the **docfx** +1. 🚀 Let's start with the **Docfx** Enter the following command to install the latest docfx @@ -36,19 +36,19 @@ docfx --version **Other options** -Update to the latest docfx +Update to the latest Docfx ``` dotnet tool update -g docfx ``` -Install a specific version of docfx +Install a specific version of Docfx ``` dotnet tool update -g docfx --version 2.67.0 ``` -Uninstall docfx if you need to downgrade +Uninstall Docfx if you need to downgrade ``` diff --git a/en/contributors/toc.yml b/en/contributors/toc.yml index 9880a53af..9b1683a2f 100644 --- a/en/contributors/toc.yml +++ b/en/contributors/toc.yml @@ -52,7 +52,7 @@ items: # href: documentation/new-language.md - name: Roadmap href: documentation/roadmap.md - - name: DocFX + - name: Docfx href: documentation/docfx.md - name: Deployment href: documentation/deployment-azure.md