Improve maintainability of website (#94)

* Restructure to make site easier to maintain

* Seperate website and documentation

* Configure website part for new directory structure

* Update docfx config to genereate articles

* Hook docfx generation into eleventy events

* Created three separate configs for docfx based on all, api, or just articles for dev

* Removed files that are no longer needed

* Added main navigation toc for docfx pages

* Updated to include the .md extensions like it originally did

* Moved foundation page into documentation since it's pure md file

* Presskit uses base layout now

* Create monogame template for docfx

* New npm scripts to use when developing to specify website, api, or articles only for generation. This is to help speed up development hotreloading when reloading all api documents isn't neccessary.

* Ignore all of the website directory if we are only working on api or articles.

* Fixed infinite loop bug where watching docfx documenation files would trigger a build, which triggers the watch to rebuild which triggers docfx to rebuild, etc, etc.

* Move docfxBuilder to its own module file.

* Remove index.js

This was being used to processes the env variable to determien which configuration of docfx to use.  The environment variable logic was moved to the script in package.json using the %npm_lifecycle_event% variable to determien the run mode to use.

* Renamed to docfx.js

* Created docfx.js

This was initially docfxBuilder, which was renamed to docfx.  Outputs relavent information into console when building to inform the the user which docfx files are being generated (articles, api, both, or neither).

* Update path to docfx after file rename.

* Output newline to console

Ensure that a newline is output to console when finished to seperate docfx output from 11ty output.

* Add sitemap generation.

* Remove unneeded excludes

* _appLogoPath not used

Intead this is used directly in the template to pick the logo path up from the 11ty output

* Update year in footer

* Simplify scripts and ensure cross os compatible

The scripts were simplified from 12 scripts to 4.  Setting the RUN_MODE environment variable is also done in a cross platform compatbiel way between Windoes, Mac, and Linux system.

Using the cross-env package was considered but initial testing showed issues where it would spawn multiple processes due to the terminal signal chaining, which could cause the termianl to hang after ending the initial process.

* Don't output logo and favicon from docfx

11ty generates the logo and favicon files, docfx should not also output these as they will be overwritten anyway.

* Use `<xref>` for API document links

DocFx will internally resolve `<xref>` links appropriatly to the API documentation.

* Perform dotnet tool restore

This ensures that the docfx tool is restored before executing the command.  This way users dont' have to worry about manually restoring it themselves.

* Update readme

Readme updated to reflect changes in the new npm script commands.

* cross-env is needed after testing to ensure compatibility between OSs

* Update scripts to use cross-env

* Add twitter and rss icons to documentation footer

* Use same theme switch icons between site and documentation

* No longer need to run docfx as separate command in workflow

* Remove excludes from configuration

The excludes are not needed and can be removed to simplify the configuration file(s).

* Clean up resources confguration

There is no codeCnippit or scripts directory to pull resources from. Removed these to simplify configuration file(s).

* Include the foundation directory in build for all

Ensure the foundation .md files are built as part of the all configuration.

* Use correct opengraph image path.

* Change hostname from monogame.github.io to monogame.net

* Update year in footer

* Use correct path for favicon

* Update favicon path in template

Template was using the _rel path which is incorrect. The path should not be relative.

* Update to ensure api/index.md is not ignored.

* Fix broken links on documentation page.

.github/workflows/main.yaml

@@ -26,9 +26,6 @@ jobs:
       - name: Restore NPM Packages
         run: npm install
 
-      - name: Build DocFX MetaData
-        run: npm run docfx
-
       - name: Build Site
         run: npm run build
 

.gitignore

@@ -15,11 +15,13 @@ _site/
 node_modules/
 
 ###############################################################################
-### All markdown files inside the /content/api directory.  These files are
-### automatically generated by docfx and should not be commited to the repo
+### All files inside the /documentation/api directory except for the index.md
+### DocFx will generate .yml files in this directory as part of the build
+### process and they should not be committed to the.
 ###############################################################################
-/content/api/*.md
-/content/api/toc.yml
+/documentation/api/*
+!/documentation/api/index.md
+
 
 ###############################################################################
 ### OS Specific

README.md

@@ -24,13 +24,14 @@ npm install
 
 3. Optional Steps
    1. 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`
-   2. Next execute the command `npm run docfx` to generate the API Reference markdown pages.  They will be placed in the **/content/api** directory
-
-4. Run a local build and serve it with hot reloading
-
-```sh
-npm run dev
-```
+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
+
+| 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 genereated 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 genereated 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. |
 
 ## LICENSE
 

documentation/api/index.md

@@ -0,0 +1,10 @@
+---
+title: Reference
+description: MonoGame API reference documentation.
+---
+
+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.

content/articles/content_pipeline/adding_ttf_fonts.md → documentation/articles/content_pipeline/adding_ttf_fonts.md

@@ -26,19 +26,19 @@ To be able to use a TrueType font, MonoGame requires the **TrueType font file**
 
 ## Usage Example
 
-Make a class variable of type [`Spritefont`](../../api/Microsoft.Xna.Framework.Graphics.SpriteFont)
+Make a class variable of type <xref:Microsoft.Xna.Framework.Graphics.SpriteFont>
 
 ```csharp
 SpriteFont font;
 ```
 
-Load the font with [`ContentManager.Load`](../../api/Microsoft.Xna.Framework.Content.ContentManager)
+Load the font with <xref:Microsoft.Xna.Framework.Content.ContentManager>
 
 ```csharp
 font = myGame.Content.Load<SpriteFont>("Fonts/myFont")
 ```
 
-Draw text with [`SpriteBatch.Draw`](../../api/Microsoft.Xna.Framework.Graphics.SpriteBatch)
+Draw text with <xref:Microsoft.Xna.Framework.Graphics.SpriteBatch>
 
 ```csharp
 spriteBatch.Begin();

content/articles/content_pipeline/custom_effects.md → documentation/articles/content_pipeline/custom_effects.md

@@ -38,7 +38,7 @@ Under the hood these effects use the same system and tools as one would for a cu
 
 To use a custom effect with MonoGame you must do one of the following:
 
-* Run the effect file through the [MonoGame Effect content processor](../tools/mgcb.md) for loading via the [`ContentManager`](../../api/Microsoft.Xna.Framework.Content.ContentManager) (Recommended).
+* Run the effect file through the [MonoGame Effect content processor](../tools/mgcb.md) for loading via the <xref:Microsoft.Xna.Framework.Content.ContentManager> (Recommended).
 * Process your effect file with the [MGFXC tool](../tools/mgfxc.md) and load them yourself at runtime.
 
 ## Effect Writing Tips

content/articles/content_pipeline/using_mgcb_editor.md → documentation/articles/content_pipeline/using_mgcb_editor.md

@@ -81,7 +81,7 @@ Additionally, the following options are configurable per image asset when import
 
 MonoGame supports several audio formats to cope with a wide variety of audio needs, from Wav files for effects to MP3's for songs/background music. The type of audio you use will depend on the audio needs for your project.
 
-Audio can be configured to use either the **Sound Effect** processor which imports audio as a [SoundEffect](../../api/Microsoft.Xna.Framework.Audio.SoundEffect) which is generally used for short and quick audio sounds. Alternatively, by selecting the **Song** processor, the audio will be imported as a **Song** which is used for long-running audio using the Media Player class.
+Audio can be configured to use either the **Sound Effect** processor which imports audio as a <xref:Microsoft.Xna.Framework.Audio.SoundEffect> which is generally used for short and quick audio sounds. Alternatively, by selecting the **Song** processor, the audio will be imported as a **Song** which is used for long-running audio using the Media Player class.
 
 | Property  | Description                                                                                                                                                            |
 | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -175,7 +175,7 @@ The MGCB Editor has 3 actions related to building content: Build, Rebuild and Cl
 
 ## Linking Content To Your Game
 
-Once you have built your content, you have a few different ways to add it to your game project. They all have the same goal, to get the built XNB's in your project output folder so a [`ContentManager`](../../api/Microsoft.Xna.Framework.Content.ContentManager) can easily find and load them.
+Once you have built your content, you have a few different ways to add it to your game project. They all have the same goal, to get the built XNB's in your project output folder so a <xref:Microsoft.Xna.Framework.Content.ContentManager> can easily find and load them.
 
 ### MonoGameContentReference
 

content/articles/migrate_xna.md → documentation/articles/migrate_xna.md

@@ -30,14 +30,14 @@ XNA uses the DirectX 9 graphics API. MonoGame uses the newer Direct X 11 API for
 
 DirectX 9 interprets UV coordinates differently from other graphics API's. This is typically referred to as the half-pixel offset.
 
-MonoGame supports replicating XNA's behavior (currently only on OpenGL platforms) by setting the `PreferHalfPixelOffset` flag in [`GraphicsDeviceManager`](../api/Microsoft.Xna.Framework.GraphicsDeviceManager) to `true`. This flag is set to `false` by default to encourage users to use the modern style of pixel addressing.
+MonoGame supports replicating XNA's behavior (currently only on OpenGL platforms) by setting the `PreferHalfPixelOffset` flag in <xref:Microsoft.Xna.Framework.GraphicsDeviceManager> to `true`. This flag is set to `false` by default to encourage users to use the modern style of pixel addressing.
 
 DirectX platforms will ignore setting the `PreferHalfPixelOffset` flag and will
 always render with a half pixel offset compared to XNA. This is usually not noticeable.
 
-This value is passed to `UseHalfPixelOffset` in [`GraphicsDevice`](../api/Microsoft.Xna.Framework.Graphics.GraphicsDevice). If `UseHalfPixelOffset` is `true`, you have to add half-pixel offset to a Projection matrix.
+This value is passed to `UseHalfPixelOffset` in <xref:Microsoft.Xna.Framework.Graphics.GraphicsDevice>. If `UseHalfPixelOffset` is `true`, you have to add half-pixel offset to a Projection matrix.
 
-[`SpriteBatch`](../api/Microsoft.Xna.Framework.Graphics.SpriteBatch) rendering is not affected by the flag.
+<xref:Microsoft.Xna.Framework.Graphics.SpriteBatch> rendering is not affected by the flag.
 
 Regardless of what value the flag has, `SpriteBatch` will render things exactly the same as in XNA.