Merge branch 'main' into docs/vs-code-setup

Author: SimonDarksideJ

.github/workflows/pullrequest.yml

@@ -25,6 +25,8 @@ jobs:
     steps:
       - name: Clone Repository
         uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - name: Setup .NET SDK
         uses: actions/setup-dotnet@v4

README.md

@@ -17,26 +17,47 @@ With your environment setup properly, the following explains how to build from s
     git clone https://github.com./MonoGame/monogame.github.io.git
     ```
 
-2. Install npm dependencies
+2. Install DotNet dependencies
 
     ```sh
-    npm install
+    dotnet tool restore
     ```
 
 3. Optional Steps
 
-   If you want to generate the API Reference documentation locally, you will need to ensure that the MonoGame submodule has been initialized by running 
+   If you want to generate the API Reference documentation locally, you will need to ensure that the MonoGame submodule has been initialized by running
 
    `git submodule update --init --recursive`
 
-4. Run a local build and serve it with hot reloading.  Depending on what part of the site you are working on, there are different commands you can use. They are explained in the table below
+4. Run a local build and serve it. The site is full DocFX now so a single build command will do:
 
-| Command | Generates Website | Generates Articles | Generates API | Description |
-| --- | --- | --- | --- | --- |
-| `npm run dev` | ✔ | ✔ | ✔ | This will run and serve the full website, including the web pages generated by 11ty and the articles and api documentation built by docfx.  This can be slower to use when developing since all API documentation (~500 files) will be built initially and again during each hot reload change.  If you're not working specifically on the API documentation page, it is suggested to use one of the other commands instead. |
-| `npm run website` | ✔ | ❌ | ❌ | This will run and serve the website with only the web pages generated by 11ty.  The articles and api documentation generated by docfx will be bypassed.  This is useful when you're only working on the main website pages and want fast hot reloading.|
-| `npm run articles` | ✔ | ✔ | ❌ | This will run and serve the website including the webpages generated by 11ty and the articles generated by docfx only.  It will not generate the API documentation.  This is to allow fast hot reloading while working on the articles by not having all API documentation files (~500 files) be included. |
-| `npm run build` | ✔ | ✔ | ✔ | This will perform a full build of the website, including the web pages built in 11ty and the articles and api documentation built by docfx. |
+  `dotnet docfx docfx.json --serve`
+
+> [!NOTE]
+> Docfx hosting does not support hot reload, so to refresh the hosted site you will need to stop the agent (ctrl-c) and run the above command again to refresh pages
+
+## Document styling
+
+The use of DocFX with the updated MonoGame docs site has afforded the use of some custom stylings to improve consistency and more stylized docs:
+
+- Document Frontmatter now drives the Title, Description and whether or not a MS license statement is needed in the document.
+
+  ```text
+  ---
+  title: How to create a Render Target
+  description: Demonstrates how to create a render target using a RenderTarget2D.
+  requireMSLicense: true
+  ---
+  ```
+
+- DocFX admonitions are supported for adding Notes, Info Panels etc, for more details see the MS docs on DocFX markdown:
+
+  [DocFX Markdown style guide](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#alerts)
+
+As an example of a document written using the above notes, please refer to the [HowTo: Create a Render Target tutorial](https://github.com./MonoGame/docs.monogame.github.io/blob/feature/docsmigration/articles/monogame/howto/graphics/HowTo_Create_a_RenderTarget.md)
+
+> [!TIP]
+> No additional text is needed at the bottom of document pages as the licenses and requirements are automatically added by the DocFX build system
 
 ## LICENSE
 

api/index.md

@@ -7,4 +7,4 @@ Welcome to the **MonoGame** reference documentation!
 
 This area provides detailed information on each class and method in the API.
 
-Please view the [documentation](../articles/) for how to get started and step-by-step guidance.
+Please view the [documentation](../articles/index.md) for how to get started and step-by-step guidance.

articles/toc.yml

@@ -69,4 +69,4 @@
 - name: Help and Support
   href: help_and_support.md
 - name: Contributing to documentation
-  href: contributing
+  href: contributing.md

docfx.json

@@ -19,6 +19,12 @@
       "EnumSortOrder": "alphabetic"
     }
   ],
+  "rules": {
+    "InvalidFileLink": "error",
+    "InvalidBookmark": "error",
+    "UidNotFound": "error",
+    "ReferencedXrefPropertyNotString": "error"
+  },  
   "build": {
     "content": [
       {
@@ -34,7 +40,8 @@
           "foundation/**/*.md",
           "toc.yml",
           "*.md"
-        ]
+        ],
+        "exclude": [ "_site/**", "README.md" ]
       }
     ],
     "resource": [