Feature/learning-2d

articles/console_access.md

@@ -19,7 +19,7 @@ The process for access to the private console repositories is as follows:
 
 The instructions below will help you gain access to each platform.
 
-## Nintendo Switch
+### Nintendo Switch
 
 ![Nintendo Switch](images/nintendo_switch.png)
 
@@ -29,7 +29,7 @@ Once you are in the program, you can go to the middleware page and fill out the
 
 We will then contact you with further instructions.
 
-## PlayStation 4, PlayStation 5
+### PlayStation 4, PlayStation 5
 
 ![PlayStation Partners](images/ps_partners.png)
 
@@ -39,7 +39,7 @@ Once you are registered, you can submit a request in the [PlayStation 4 forums](
 
 We will process these requests to give you access and further instructions.
 
-## Xbox One, Xbox Series X
+### Xbox One, Xbox Series X
 
 ![ID@Xbox](images/idatxbox.png)
 

articles/contributing.md

@@ -1,13 +1,11 @@
 ---
-title: Contributing Guidelines
+title: Contributing to MonoGame Documentation
 description: Instructions on how to contribute to the documentation of the MonoGame Framework
 ---
 
-# Contributing to MonoGame Documentation
-
 Thank you for choosing to contribute to the MonoGame project! This page provides guidance on how you can help to improve the documentation for MonoGame.   
 
-# Getting Started
+## Getting Started
 
 > [!NOTE]
 > If you are new to making contributions to open source projects, it is recommended to understand the following concepts before submitting your contribution:   
@@ -17,15 +15,15 @@ Thank you for choosing to contribute to the MonoGame project! This page provides
 > - [Creating a new file](https://help.github.com/articles/creating-new-files/) or [editing an existing one](https://help.github.com/articles/editing-files-in-your-repository/) using the GitHub markup editor.
 > - [How to submit your contributions for review through a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
-## Articles and API References
+### Articles and API References
 
 The MonoGame documentation contains two types of documents: articles and API references.
 
 Articles include manuals, guides and tutorials on how to use the MonoGame Framework to create games.
 
 API references provide detailed explanation of each class and method found in the MonoGame Framework. The documentation is written in the [C# XML format](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) and is inline to the MonoGame source code. 
 
-## Generating the Documentation Site
+### Generating the Documentation Site
 
 The pages for articles and API references are hosted on a documentation site that is generated using [DocFX](https://dotnet.github.io/docfx/).
 
@@ -40,7 +38,7 @@ To generate a local copy of the documentation site:
 > [!TIP]
 > Verify your changes in your local documentation site before submitting a pull request with said changes. It is recommended to include screenshots of the pages in the pull request to help reviewers confirm these changes.
 
-# General Rules
+## General Rules
 
 The following rules **must** be observed at all times when contributing documentation to the MonoGame project.
 
@@ -52,65 +50,65 @@ The following rules **must** be observed at all times when contributing document
 > [!WARNING]
 > Breaking these rules can result in your contribution being rejected.
 
-# General Style Guide
+## General Style Guide
 
 Because there are many contributors to the MonoGame documentation, it can be difficult to maintain a coherent writing style throughout the documentation site. In addition to the [General Rules](#general-rules), this style guide serves to inform contributors of the conventions needed to maintain this writing style. So please review the following expectations before contributing any documentation.
 
-## Every Word Should Contain Value
+### Every Word Should Contain Value
 
 Every word in the reference documentation should provide information beyond the API itself.  Documentation that only rehashes or rephrases what is already apparent in the class, method, parameter, or property name has zero value and wastes time for both the writer and reader.
 
-## The First Sentence Is the Most Important
+### The First Sentence Is the Most Important
 
 There is no guarantee that the reader will read beyond the first sentence of the reference documentation.  This is why that first sentence is the most important and should convey the most key piece of information.  Take your time to write the most concise and clear first sentence possible.  This helps users tremendously and goes a long way towards having great documentation.
 
-## Surface Information Hidden in the Code
+### Surface Information Hidden in the Code
 
 Being inline with the code allows you to easily look for critical information within it that the user might not know from looking at the API alone.  Take your time to explore inner method calls and platform specific sections of the code.  The time to write the documentation is once you feel you fully understand the code you are documenting.  If you don't feel you understand the code then leave the documentation for someone else to write.
 
-## Focus on What Adds Value to the Consumer
+### Focus on What Adds Value to the Consumer
 
 Limit documentation to public methods and functions unless there is a specific reason to include internal methods, while documenting internals helps with readability of the code, it provides limited use to consumers of the MonoGame Framework.
 
-## Documentation Is Referenced Not Read
+### Documentation Is Referenced Not Read
 
 Remember that the user is searching for an answer for a specific question.  It is your job to predict these questions and provide them clear answers.
 
-## Descriptions Should Add Value and Understanding
+### Descriptions Should Add Value and Understanding
 
 Describing a thing by naming the thing does not help the developer to understand what the concept is that you are describing, for example:
 
 > "The Genre class provides information about a genre"
 
 Which does not help someone reading the documentation if they do not know what a `Genre` is.  Be descriptive and improve the readers understanding for what something is and WHY it is.
 
-# API Reference Style Guide
+## API Reference Style Guide
 
 In addition to the [General Style Guide](#general-style-guide), please consider the following conventions used for code associated with the API reference docs. 
 
-## XML Tag Guidance
+### XML Tag Guidance
 
 By default, the standard [Microsoft recommendations](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) should be used for filling in XML tags for each class, method and property.
 
 With a few points to call out:
 
-### `<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
+#### `<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
 
 To ensure that API documentation is linked to whichever reference is used, `<see>` and `<cref/>` references should be used, this helps users navigate the methods, especially when looking up initializers or use of a property or method.
 
-### Avoid self referencing `<cref/>` unless it provides value
+#### Avoid self referencing `<cref/>` unless it provides value
 
 `<cref/>` blocks are there to add links and create references to other classes, functions and methods that help inform the developer for what those concepts are.  Adding a `<cref/>` for the same class or property you are describing just creates a circular reference that does not add value.
 
 References to other methods or properties in the same class is fine, just avoid self if possible.
 
-### Use descriptors in `<see/>` and `<cref/>` statements for better readability
+#### Use descriptors in `<see/>` and `<cref/>` statements for better readability
 
 By default, a `<cref/>` or `<see/>` reference will use only the type you are referencing when rendered to the user, e.g. `<cref="Album.Genre"/>` will render as `Genre`.
 
 Instead, use the descriptor in the style to render what you actually mean, for example: `<cref="Album.Genre">Album.Genre</cref>` which will always render as `Album.Genre` which is much clearer, it is the same for `<see/>` tags.
 
-### 120 width comments for easy reading
+#### 120 width comments for easy reading
 
 Comments should be limited to **120** width, with overflow moving to the next line to make reading easier, for example:
 
@@ -125,7 +123,7 @@ and the y component uses 6 bits.
 > If the `cref` description would cause the line to exceed the 120 recommendation, this is generally ok, so long as the rendered line does not exceed the limit.
 > THe limit however, is more of a guideline than a hard rule, so common sense should be applied to keep the limit near 120 characters.
 
-### Use the packed multi-line style with surrounding tags
+#### Use the packed multi-line style with surrounding tags
 
 To keep the documentation packed and readable, each parameter should be contained to a single line, for example:
 
@@ -138,7 +136,7 @@ Creates a new instance of Bgr565.
 <param name="z">The z component</param>
 ```
 
-## Interface Documentation
+### Interface Documentation
 
 If documentation is already provided by an interface or inherited class, then the `<inheritdoc />` tag should be used.  Critically, **DO NOT** duplicate documentation as it increases maintenance later, for example:
 
@@ -152,7 +150,7 @@ public void Dispose()
 
 This applies to all derived elements within a class, property or method.
 
-## Inherited Properties
+### Inherited Properties
 
 Where a property or type is already documented in an `enum` or `static`, to avoid duplication the `<inheritdoc cref=""/>` style should be used, for example:
 
@@ -175,7 +173,7 @@ Where a property or type is already documented in an `enum` or `static`, to avoi
         public static readonly VertexDeclaration VertexDeclaration;
 ```
 
-## Protected Methods Requiring Documentation by the Linter
+### Protected Methods Requiring Documentation by the Linter
 
 By default, we do not document Finalizers or other protected methods, the recommendation is to apply an empty `<summary />` tag to suppress the warnings raised by the linter, for example:
 

articles/getting_started/content_pipeline/adding_ttf_fonts.md

@@ -3,8 +3,6 @@ title: Adding TTF Fonts
 description: Learn how to use TrueType fonts in MonoGame.
 ---
 
-# TrueType fonts
-
 MonoGame supports more than one method of using fonts, the following is an explanation of how to use TrueType fonts.
 
 ## Using TrueType Fonts with MonoGame
@@ -14,7 +12,7 @@ To be able to use a TrueType font, MonoGame requires the **TrueType font file**
 > TrueType fonts may be installed on the system, or added manually in to the same directory as the .spritefont file.
 
 1. Create the .spritefont file by selecting "Edit -> Add -> New Item" from the MGCB Editor menu, then select **SpriteFont Description** from the list and click **Create**.
-   
+
    ![Adding TTF fonts step 2](images/adding_ttf_fonts.PNG)
 
 2. Open the newly created .spritefont file in your text editor of choice, find this line and change it to your selected .ttf font.

articles/getting_started/content_pipeline/custom_effects.md

@@ -3,8 +3,6 @@ title: Custom Effects
 description: Learn how to create and use custom effects for rendering in MonoGame.
 ---
 
-# Custom Effects
-
 A core element of Microsoft XNA is the effect system which is used for all rendering.
 
 For MonoGame we have the burden of supporting stock and custom effects for desktop GLSL, mobile GLSL, DirectX HLSL, and custom formats like that of the PlayStation Mobile.  There currently is no effect system or shader language that supports all the platforms we require, forcing us to build a new custom effect system.
@@ -64,7 +62,6 @@ These are some tips for writing or converting effects for use with MonoGame.
 |  `HLSL` and `SM4` for DirectX   |
 |  `OpenGL` and `GLSL` for OpenGL |
 
-
 As an example, you can conditionally set shader models depending on the platform with the following code:
 
   ```hlsl

articles/getting_started/content_pipeline/index.md

@@ -3,8 +3,6 @@ title: Adding Content
 description: Learn how to add content to your game using the Content Pipeline.
 ---
 
-# Adding Content
-
 A big part of your game is your content.  This includes standard files like textures, sound effects, music, videos, and custom effects as well as custom content like level and enemy files.
 
 MonoGame implements its own content pipeline for transforming your unoptimized assets into platform optimized content.  This is critical in building a game which runs as fast as possible under tight resource constraints.

articles/getting_started/content_pipeline/localization.md

@@ -3,8 +3,6 @@ title: Localization
 description: Learn how to add localization to your game to support multiple regions.
 ---
 
-# Localization
-
 Localization is an important part of any game. While it can be possible to design a game that is region independent, it is quite hard. At some point you will need to produce localized text and graphics.
 
 MonoGame has a simple localization system built in. If you want to develop your own system you are still able to do so. But the default system should be good enough for
@@ -135,6 +133,6 @@ CultureInfo.CurrentCulture.Name                         // eg. "en-US"
 CultureInfo.CurrentCulture.TwoLetterISOLanguageName     // eg. "en"
 ```
 
-which are part of the **System.Globalization namespace**. 
+which are part of the **System.Globalization namespace**.
 
 > On a side note you can also use the `LoadLocalized` to load language specific SpriteFonts. They just need to be named in the same way as we have described above.

articles/getting_started/content_pipeline/using_mgcb_editor.md

@@ -170,9 +170,9 @@ After you have done these fixes, you should be able to add these new processors
 
 The MGCB Editor has 3 actions related to building content: Build, Rebuild and Clean:
 
-- **Build** - This will build all content that needs to be built and put it in the output directory (bin by default). Content will be skipped if it has not changed since the last build. The time source content was last edited is saved in the intermediate directory (obj by default) to determine if content changed since the last build.
-- **Rebuild** - Cleans the project first and then Builds it again.
-- **Clean** - Cleaning the project will empty the output and intermediate directories.
+* **Build** - This will build all content that needs to be built and put it in the output directory (bin by default). Content will be skipped if it has not changed since the last build. The time source content was last edited is saved in the intermediate directory (obj by default) to determine if content changed since the last build.
+* **Rebuild** - Cleans the project first and then Builds it again.
+* **Clean** - Cleaning the project will empty the output and intermediate directories.
 
 ## Linking Content To Your Game
 
@@ -200,10 +200,10 @@ If you are using Visual Studio, you can bypass the content pipeline all together
 
 ![Add existing item](images/existing_item.png)
 
-You will now see a file dialog from which you can add your content files. 
+You will now see a file dialog from which you can add your content files.
 
 > Note that if you do not want Visual Studio to make a local copy of the files. Make sure to use “**Add As Link**” when “Linking” files.
-> 
+>
 > ![Add as link](images/add_as_link.png)
 
 Once the files are added you will need to select them all and change their properties in the properties window to:

articles/getting_started/content_pipeline/why_content_pipeline.md

@@ -3,8 +3,6 @@ title: Why use the Content Pipeline
 description: Why would you use the Content Pipeline when MonoGame also supports loading assets natively, like .png, .mp3, .wav? Well, it all boils down to a couple of words, performance and efficiency.
 ---
 
-# Why use the Content Pipeline
-
 The MonoGame team continues to put a lot of effort into a cross-platform content pipeline, but why would you use the Content Pipeline when MonoGame also supports loading assets natively, like .png, .mp3, .wav? Well, it all boils down to a couple of words, performance and efficiency.
 
 ## Textures

articles/getting_started/tools/index.md

@@ -3,8 +3,6 @@ title: Tools
 description: Distributed tools to help mange and build content for your game.
 ---
 
-# Tools
-
 MonoGame distributes tooling to help manage and build content for your game.
 
 These tools are available as [.NET Tools](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools) and are automatically installed if you are using the MonoGame templates.