update docs

docs/configuration.md

@@ -0,0 +1,28 @@
+The Mobile.BuildTools relies a lot on JSON configurations because JSON is easy for most developers to work with.
+
+| FileName | Schema Url |
+|:--------:|:----------:|
+| secrets.json | n/a - JSON Dictionary |
+| buildtools.json | https://mobilebuildtools.com/schemas/v2/buildtools.schema.json |
+| {imageName}.json | https://mobilebuildtools.com/schemas/v2/resourceDefinition.schema.json |
+
+## Secrets.json
+
+Everyone has a different opinion of how they would like to set things up. While the Mobile.BuildTools is opinionated in certain ways, we also try to make efforts to meet developers where their needs are giving you some flexibility in configuration. Within a CI environment, the Mobile.BuildTools relies on Environment Variables to map values you need in your app. However this is a bit of a pain to deal with for local app development. The Mobile.BuildTools has long relied on a `secrets.json` file containing the dictionary values of the various variables you need for your build. Version 2.0 has added a few benefits to this allowing you to now pick and choose which file directory you would like the secrets.json to live in. This can be any directory from the directory where your Solution file is located up to the Project directory. This can be particularly helpful when you may be using the Mobile.BuildTools to supply values across multiple projects or even where you may be replacing certain values in your AndroidManifest.xml or Info.plist.
+
+## BuildTools.json
+
+One of the biggest changes in the Mobile.BuildTools 2.0 is the introduction of the `buildtools.json`. Because we provide an easy to use json configuration with a Json Schema you have the ability to get intellisense in Visual Studio, Visual Studio Code, as well as many other editors that support Json Schemas. This makes it much easier for you to configure the Mobile.BuildTools rather than relying on MSBuild properties which can confuse many developers. 
+
+```json
+{
+  "$schema": "https://mobilebuildtools.com/schemas/v2/buildtools.schema.json"
+}
+```
+
+!!! note
+    Some features may still utilize MSBuild parameters which can be defined in your CI Build to customize behavior during a CI build. An example of this would be an override to the Image search paths which can be particularly useful for White Labeling apps.
+
+## Image Configuration Json
+
+The Images API for the Mobile.BuildTools is incredibly powerful and dynamic. One of the ways that we support powerful image creation is by incorporating a configuration file for each image. By convention the configuration file should have the same file name (minus the file extension) of the image resource. You can then customize the output image resource name. This can be done globally or be specific on a specific platform like iOS or Android. Additionally you can configure a single input image to have multiple outputs. An example of this scenario could be that you have a resource that will be used for the App Icon. On Android you may output both the standard image and the "Launcher" image which may have additional padding to look good as a round icon.

docs/images/index.md

@@ -44,8 +44,12 @@ Conditional Directories supercharges your ability deliver customized images for
 
 **Platform Conditions**
 
+A powerful feature of the Mobile.BuildTools is the ability to customize by Build Platform. This allows to to use the office Target Framework Moniker (TFM) or the more friendly platform name like the following.
+
 - Xamarin.iOS
+- iOS
 - MonoAndroid
+- Android
 
 **Build Configurations**
 
@@ -121,4 +125,4 @@ Not all platforms are supported. For more information see the grid below:
 | Blazor | Not Planned |
 | Web Assembly | Not Planned |
 
-\* Platform is theoretically supported as there should be no difference from iOS, however this has not been directly tested.
+\* Platform is theoretically supported as there should be no difference from iOS, however this has not been directly tested.

docs/index.md

@@ -7,12 +7,19 @@ The Mobile.BuildTools are a collection of MSBuild Tasks that help make MSBuild s
 !!! warning "NOTE"
     The docs on this site are specific to the Mobile.BuildTools v2.0. For those still using v1.4 please refer to the Wiki on GitHub.
 
+## History
+
+The Mobile.BuildTools started out several years ago from powershell scripts I found myself writing from one project to the next to help me decouple app secrets and configuration values from the code base making these instead build time dependencies. Over the years this grew from the scripts I kept re-writing to scripts that I included out of the box with the Prism Quickstart templates. These features had nothing to do with Prism however, and I started looking at how these could be re-used for any Xamarin application. With that the Mobile.BuildTools was born. Over the years it has grown and had so many features added that I ultimately realized I better start writing a docs site as it has a solution for pretty much every problem I encounter when developing mobile apps.
+
 ## Support
 
 This project is maintained by Dan Siegel. If this project has helped you please consider sponsoring Dan on GitHub. Your contributions help make great open source projects possible.
 
 [![GitHub Sponsors](https://github.blog/wp-content/uploads/2019/05/mona-heart-featured.png?fit=600%2C315)][sponsor]
 
+!!! note
+    Enterprise Support is available through [AvantiPoint](https://avantipoint.com). Please reach out if you require support for your apps with the Mobile.BuildTools, Prism or general assistance with your Xamarin, .NET Maui, or Uno Platform apps.
+
 ## Latest NuGet's
 
 | Package | NuGet | SponsorConnect |
@@ -22,6 +29,10 @@ This project is maintained by Dan Siegel. If this project has helped you please
 
 Want to consume the CI packages? Sign up as a [GitHub sponsor][sponsor] and you can access the Sponsor Connect private feed.
 
+## Why Use the Mobile.BuildTools
+
+The Mobile.BuildTools is designed to help you with a variety of tasks that make mobile app development easier and help you to follow best practices keeping app secrets as well as environment configurations out of your source control. Additionally the Mobile.BuildTools has a variety of helpers that can help you manage your image resources, white label apps, or generally make it easier to build your app for side by side installation for different environments like Dev, Stage, and Production.
+
 ## What does it do?
 
 - Automatic app bundle copy to artifacts folder in the Solution directory
@@ -86,4 +97,4 @@ Some additional notes... the Mobile.BuildTools will help with some advanced scen
 [BuildToolsConfigNuGet]: https://www.nuget.org/packages/Mobile.BuildTools.Configuration/
 [BuildToolsConfigNuGetShield]: https://img.shields.io/nuget/vpre/Mobile.BuildTools.Configuration.svg
 [BuildToolsConfigSponsorConnect]: https://sponsorconnect.dev/nuget/package/Mobile.BuildTools.Configuration/
-[BuildToolsConfigSponsorConnectShield]: https://img.shields.io/endpoint?url=https%3A%2F%2Fsponsorconnect.dev%2Fshield%2FMobile.BuildTools.Configuration%2Fvpre
+[BuildToolsConfigSponsorConnectShield]: https://img.shields.io/endpoint?url=https%3A%2F%2Fsponsorconnect.dev%2Fshield%2FMobile.BuildTools.Configuration%2Fvpre

docs/manifests/index.md

@@ -2,9 +2,6 @@
 
 There are many times in which you may need to parameterize an AndroidManifest.xml or Info.plist. One such example would be when using the MSAL library for Azure Active Directory / Azure Active Directory B2C user authentication in which you must create a custom url scheme like:
 
-!!! danger "Critical Note"
-    While this was originally slated for v2.0, this will not be done until 2.1.
-
 ```xml
 <key>CFBundleURLTypes</key>
 <array>
@@ -38,4 +35,4 @@ We can now leave our Info.plist or AndroidManifest.xml checked into source contr
     If no environment variable can be found matching `Manifest_` as the prefix is defined, the Mobile.BuildTools will next search for a variable name matching the token name which would be `AzureADClientId` in the sample above. It will also try to do all matches case insensitive due to the issue with some build agents running `ToUpper()` on all variable names.
 
 !!! info Info
-    In order to work with the tokenized manifest locally without having to update your Environment Variables on your developer machine, you can simply drop in a `manifest.json` in the Project root with the Key/Value pairs for the Mobile.BuildTools to use. If using this file, be sure to add it to the .gitignore so as to not accidently check it into source control.
+    In order to work with the tokenized manifest locally without having to update your Environment Variables on your developer machine, you can simply drop in a `manifest.json` in the Project root with the Key/Value pairs for the Mobile.BuildTools to use. If using this file, be sure to add it to the .gitignore so as to not accidentally check it into source control.

docs/manifests/versioning.md

@@ -2,9 +2,6 @@
 
 Build versioning can be extremely important for analytics and diagnostics. What's more is that Mobile development requires unique builds. No longer can you be lazy and ship apps for 15 years at Version 1.0.0.0. Ok technically all of your binaries in the application all will show that version, but the app itself must have a unique build number to allow you to upload to the App Store and Google Play.
 
-!!! danger "Critical Note"
-    While this was originally slated for v2.0, this will not be done until 2.1.
-
 ```json
 {
   "$schema": "https://mobilebuildtools.com/schemas/v2/buildtools.schema.json",
@@ -41,4 +38,11 @@ Automatic Build Versioning supports the following `Behavior`'s:
   - Jenkins
 
 !!! info Info
-    You might use the `versionOffset` when your CI Build Number and Build Number in the App Store or Google Play are not in sync. As an example, when shipping multiple APKs with the same build number Google Play may take build 123 and make it 100123, 200123, 300123, & 400123 respectively for each of the 4 APK's you have provided. This would mean when switching to AAB that you might need to offset by 400000 in order to get your new AAB build to show up in Google Play.
+    You might use the `versionOffset` when your CI Build Number and Build Number in the App Store or Google Play are not in sync. As an example, when shipping multiple APKs with the same build number Google Play may take build 123 and make it 100123, 200123, 300123, & 400123 respectively for each of the 4 APK's you have provided. This would mean when switching to AAB that you might need to offset by 400000 in order to get your new AAB build to show up in Google Play.
+
+## Planned Enhancements
+
+Build Versioning is a brand new task that has been planned for a long time and sadly has taken a lot longer to get implemented than what was originally anticipated. Beginning with the push for 2.1 we will be looking at more advanced scenarios:
+
+- Support scenarios where you may want to control a public display version like 1.0 but need a unique build id so that you can resubmit to the store if the App Store or Google Play reject your app during review.
+- Support using GitVersioning. Git Versioning is a popular technique used by a lot of modern libraries including the Mobile.BuildTools. This occurs by evaluating the Git Height, and is generally controlled with a `version.json` in the root directory. You can look at the Mobile.BuildTools repo for an example of this using Nerdbank.GitVersioning.

docs/maui.md

@@ -0,0 +1,3 @@
+.NET Maui is the evolution of Xamarin. There is a lot to be excited about with .NET Maui. While this is still early days with .NET Maui and I have not yet had time to evaluate the Mobile.BuildTools with .NET Maui, there is also no reason why the Mobile.BuildTools would not work with .NET Maui. Many of the features included with the Mobile.BuildTools such as the Secrets API, is completely cross platform and can be used with literally any C# project including AspNetCore, Unit Tests, etc.
+
+For Platform Specific functionality such as the Image or Manifest processing, these rely on the iOS/Android SDK's which are shared by traditional Xamarin applications and .NET Maui apps. As such these should continue to work. If you encounter any issue with the Mobile.BuildTools and a .NET Maui application please be sure to file and issue on GitHub.

docs/scss-to-css/in-code.md

@@ -31,7 +31,7 @@ stacklayout > * {
 </ContentPage>
 ```
 
-do not abuse of that second syntax.
+do not abuse that second syntax.
 
 ### in C#
 
@@ -50,4 +50,4 @@ using (var reader = new StringReader(my_css_string))
 
 ## StyleSheet, XamlC and other potential optimizations
 
-At this time, CSS StyleSheets are parsed and evaluated at runtime. That aren't compiled. Every time a StyleSheet is used, it's reparsed again. If parsing time is an issue, enabling caching is trivial, but comes at memory cost.
+At this time, CSS StyleSheets are parsed and evaluated at runtime. That aren't compiled. Every time a StyleSheet is used, it's reparsed again. If parsing time is an issue, enabling caching is trivial, but comes at memory cost.

docs/scss-to-css/index.md

@@ -1,12 +1,10 @@
 # SCSS to Xamarin.Forms CSS
 
-CSS support in Xamarin.Forms is the most revolutionary change to Styling XAML. CSS though is traditionally problematic on larger projects as it can quickly become hard to maintain, and error prone as it lacks reusability of common values which could include setting various properties or reusing the same color from one element to the next. With SCSS you gain the ability to break your stylesheets into logical reusable chunks and you gain the ability to define variables and functions for creating your styles. The Mobile.BuildTools now supports Xamarin.Forms CSS generation as part of the build process.
+While CSS support in Xamarin.Forms has been a highly controversial topic in which you likely either love it or hate it, it has been my view that CSS support in Xamarin.Forms is the most revolutionary change to Styling XAML. CSS though is traditionally problematic on larger projects as it can quickly become hard to maintain, and error prone as it lacks reusability of common values which could include setting various properties or reusing the same color from one element to the next. With SCSS you gain the ability to break your stylesheets into logical reusable chunks and you gain the ability to define variables and functions for creating your styles. For those developers who want to start using CSS in their Xamarin.Forms application, the Mobile.BuildTools empowers you to leverage SCSS which is compiled into Xamarin.Forms compatible CSS at build.
 
 ## Valid Xamarin.Forms CSS
 
-
-!!! note "Note"
-    The Xamarin.Forms CSS spec does not generate valid CSS and as a result SCSS will not support the use of ^.
+Perhaps one of the most frustrating things about Xamarin.Forms CSS is that the spec is NOT compliant with standard CSS linting. Specifically Xamarin.Forms requires the `^` prefix when looking to have a style apply to any inheriting type which you may want to do for instance when styling a Page.
 
 ```css
 ^button {
@@ -17,6 +15,7 @@ CSS support in Xamarin.Forms is the most revolutionary change to Styling XAML. C
   background-color: #78909c;
 }
 ```
+
 The Mobile.BuildTools will post process your SCSS to generate valid CSS for Xamarin.Forms when using the selectors `any` or `all`.
 
 ## Valid SCSS used by the Mobile.BuildTools

mkdocs.yml

@@ -78,6 +78,7 @@ nav:
     - App Manifests:
       - Tokenized Manifests: manifests/index.md
       - Build Versioning: manifests/versioning.md
+    - Configuration: configuration.md
     - Google Firebase: google/index.md
     - Image Assets:
       - Getting Started: images/index.md
@@ -93,6 +94,7 @@ nav:
       - Usage Notes: scss-to-css/css-notes.md
       - Supported Properties: scss-to-css/properties.md
       - In Code: scss-to-css/in-code.md
+    - .NET Maui: maui.md
     - F.A.Q.: faq.md
     - Appendix:
       - Upgrading from 1.X: appendix/upgrade.md