Merge pull request #16988 from unoplatform/mergify/bp/release/stable/…

…5.2/pr-16972

docs: Fix multiple docfx, css, js, mermaid layout related issues (backport #16972)

doc/.howto-template.md

@@ -53,7 +53,7 @@
 * [**Rider Version 2020.2+**](https://www.jetbrains.com/rider/download/)
 * [**Rider Xamarin Android Support Plugin**](https://plugins.jetbrains.com/plugin/12056-rider-xamarin-android-support/) (you may install it directly from Rider)
 
-***
+---
 
 <br>
 
@@ -72,6 +72,6 @@ See the completed sample on GitHub: [YourSample](https://github.com/unoplatform/
 
 <br>
 
-***
+---
 
 [!include[getting-help](includes/getting-help.md)]

doc/ReleaseNotes/LegacyReleaseNotes.md

@@ -190,7 +190,7 @@ uid: Uno.ReleaseNotes.Legacy
   - **Custom Themes** are supported. This let you specify `HighContrast` or any other custom themes.
     (this is a feature not supported in UWP)
 
-    ``` csharp
+    ```csharp
     // Put that somewhere during app initialization...
     Uno.UI.ApplicationHelper.RequestedCustomTheme = "MyCustomTheme";
     ```

doc/articles/Uno-UI-Performance.md

@@ -20,20 +20,20 @@ Here's what to look for:
   - The default [`ListViewItem` and `GridViewItem` styles](https://github.com/unoplatform/uno/blob/74b7d5d0e953fcdd94223f32f51665af7ce15c60/src/Uno.UI/UI/Xaml/Style/Generic/Generic.xaml#L951) are very feature-rich, yet that makes them quite slow. For instance, if you know that you're not likely to use selection features for a specific ListView, create a simpler ListViewItem style that some visual states, or the elements that are only used for selection.
   - If items content frequently change (e.g. live data in TextBlock) on iOS and Android, ListView items rendering can require the use of the `not_win:AreDimensionsConstrained="True"` [uno-specific property](https://github.com/unoplatform/uno/blob/7355d66f77777b57c660133d5ec011caaa810e29/src/Uno.UI/UI/Xaml/FrameworkElement.cs#L86).
 
-  This attribute prevents items in a list from requesting their parent to be re-measured when their properties change. It's safe to use the `AreDimensionsConstrained` property when items always have the same size regardless of bound data, and the items and list are stretched in the non-scrolling direction. If item sizes can change when the bound data changes (eg, if they contain bound text that can wrap over multiple lines, images of undetermined size, etc), or if the list is wrapped to the items, then you shouldn't set `AreDimensionsConstrained` because the list does need to remeasure itself when item data changes in that case.
+    This attribute prevents items in a list from requesting their parent to be re-measured when their properties change. It's safe to use the `AreDimensionsConstrained` property when items always have the same size regardless of bound data, and the items and list are stretched in the non-scrolling direction. If item sizes can change when the bound data changes (eg, if they contain bound text that can wrap over multiple lines, images of undetermined size, etc), or if the list is wrapped to the items, then you shouldn't set `AreDimensionsConstrained` because the list does need to remeasure itself when item data changes in that case.
 
-  You'll need to set the property on the top-level element of your item templates, as follows:
+    You'll need to set the property on the top-level element of your item templates, as follows:
 
-  ```xml
-  <ResourceDictionary xmlns:xamarin="http://uno.ui/xamarin" mc:Ignorable="d xamarin" ...>
-   <DataTemplate x:Key="MyTemplate">
-    <Grid Height="44" not_win:AreDimensionsConstrained="True">
-     ...
-    </Grid>
-   </DataTemplate>
-  ```
+      ```xml
+      <ResourceDictionary xmlns:xamarin="http://uno.ui/xamarin" mc:Ignorable="d xamarin" ...>
+      <DataTemplate x:Key="MyTemplate">
+        <Grid Height="44" not_win:AreDimensionsConstrained="True">
+        ...
+        </Grid>
+      </DataTemplate>
+      ```
 
-  Note that WinUI does not need this, and the issue is [tracked in Uno here](https://github.com/unoplatform/uno/issues/6910).
+    Note that WinUI does not need this, and the issue is [tracked in Uno here](https://github.com/unoplatform/uno/issues/6910).
   - Avoid controls that contain inline popups, menus, or flyouts. Doing so will create as many popups as there are items visible on the screen. As in general, there is only one popup visible at a time, it is generally best to move the popup to a separate static resource.
 
 - Updating items in `ItemsControl` can be quite expensive, using `ItemsRepeater` is generally faster at rendering similar content.
@@ -46,11 +46,11 @@ Here's what to look for:
     - `ProgressRing` and `ProgressBar` controls indeterminate mode generally consume rendering time. Make sure to set those to determinate modes when not visible.
     - Troubleshooting of animations can be done by enabling the following logger:
 
-   ```csharp
-   builder.AddFilter("Windows.UI.Xaml.Media.Animation", LogLevel.Debug);
-   ```
+      ```csharp
+      builder.AddFilter("Windows.UI.Xaml.Media.Animation", LogLevel.Debug);
+      ```
 
-   The logger will provide all the changes done to animated properties, with element names.
+      The logger will provide all the changes done to animated properties, with element names.
 
 - Image Assets
   - Try using an image that is appropriate for the DPI and screen size.
@@ -68,13 +68,13 @@ Here's what to look for:
   - Add the `Windows.UI.Xaml.BindableAttribute` or `System.ComponentModel.BindableAttribute` on non-DependencyObject classes.
     - When data binding to classes not inheriting from `DependencyObject`, in Debug configuration only, the following message may appear:
 
-   ```console
-   The Bindable attribute is missing and the type [XXXX] is not known by the MetadataProvider.
-   Reflection was used instead of the binding engine and generated static metadata. Add the Bindable  attribute to prevent this message and performance issues.
-   ```
+      ```console
+      The Bindable attribute is missing and the type [XXXX] is not known by the MetadataProvider.
+      Reflection was used instead of the binding engine and generated static metadata. Add the Bindable  attribute to prevent this message and performance issues.
+      ```
 
-   This message indicates that the binding engine will fall back on reflection based code, which is generally slow. To compensate for this, Uno use the `BindableTypeProvidersSourceGenerator`, which generates static non-generic code to avoid reflection operations during binding operations.
-   This attribute is inherited and is generally used on ViewModel based classes.
+      This message indicates that the binding engine will fall back on reflection based code, which is generally slow. To compensate for this, Uno use the `BindableTypeProvidersSourceGenerator`, which generates static non-generic code to avoid reflection operations during binding operations.
+      This attribute is inherited and is generally used on ViewModel based classes.
 - [`x:Phase`](https://learn.microsoft.com/windows/uwp/xaml-platform/x-phase-attribute)
   - For `ListView` instances with large templates, consider the use of x:Phase to reduce the number of bindings processed during item materialization.
   - It is only supported for items inside `ListViewItem` templates, it will be ignored for others.
@@ -83,13 +83,13 @@ Here's what to look for:
  attribute is ignored for templates of `ContentControl` instances, or any other control.
   - When binding to Brushes with a solid color, prefer binding to the `Color` property like this if the brush type does not change:
 
-       ```xml
-       <TextBlock Text="My Text">
-           <TextBlock.Foreground>
-               <SolidColorBrush Color="{x:Bind Color, Mode=OneWay, FallbackValue=Red}" />
-           </TextBlock.Foreground>
-       </TextBlock>
-       ```
+      ```xml
+      <TextBlock Text="My Text">
+          <TextBlock.Foreground>
+              <SolidColorBrush Color="{x:Bind Color, Mode=OneWay, FallbackValue=Red}" />
+          </TextBlock.Foreground>
+      </TextBlock>
+      ```
 
 - Resources
   - Avoid using `x:Name` in `ResourceDictionary` as those force early instantiation of the resource
@@ -105,13 +105,15 @@ Here's what to look for:
 - Adjusting the GC configuration may be useful to limit the collection runs on large allocations. Add the following to your `csproj` file:
 
     ```xml
-
- <ItemGroup>
-  <WasmShellMonoEnvironment Include="MONO_GC_PARAMS" Value="soft-heap-limit=512m,nursery-size=64m,evacuation-threshold=66,major=marksweep" />
- </ItemGroup>
+    <ItemGroup>
+      <WasmShellMonoEnvironment Include="MONO_GC_PARAMS" Value="soft-heap-limit=512m,nursery-size=64m,evacuation-threshold=66,major=marksweep" />
+    </ItemGroup>
     ```
- You can adjust the `nursery-size` and `soft-heap-limit` based on your application's memory consumption characteristics. See the [.NET GC configuration](https://learn.microsoft.com/xamarin/android/internals/garbage-collection#configuration) for more details.
+
+  You can adjust the `nursery-size` and `soft-heap-limit` based on your application's memory consumption characteristics. See the [.NET GC configuration](https://learn.microsoft.com/xamarin/android/internals/garbage-collection#configuration) for more details.
+
 - The size of the application can be reduced by:
+
   - Enabling the [IL Linker](features/using-il-linker-webassembly.md)
   - Enabling [XAML Resources Trimming](features/resources-trimming.md)
 
@@ -122,20 +124,20 @@ Here's what to look for:
 - Enable `Marshal Methods` in `Release` with `-p:AndroidEnableMarshalMethods=true` to improve startup performance (.NET 8 +)
 - [Enable Startup Tracing](https://devblogs.microsoft.com/dotnet/performance-improvements-in-dotnet-maui/#record-a-custom-aot-profile) by running the following:
 
- ```bash
- dotnet add package Mono.AotProfiler.Android
- dotnet build -t:BuildAndStartAotProfiling
- # Wait until the app launches, then navigate around the most common screens
- dotnet build -t:FinishAotProfiling
- ```
+    ```bash
+    dotnet add package Mono.AotProfiler.Android
+    dotnet build -t:BuildAndStartAotProfiling
+    # Wait until the app launches, then navigate around the most common screens
+    dotnet build -t:FinishAotProfiling
+    ```
 
- This will produce a `custom.aprof` in your project directory. Move the file to the `Android` folder and add the following to your `csproj`:
+  This will produce a `custom.aprof` in your project directory. Move the file to the `Android` folder and add the following to your `csproj`:
 
- ```xml
- <ItemGroup>
-  <AndroidAotProfile Include="Android/custom.aprof" />
- </ItemGroup>
- ```
+    ```xml
+    <ItemGroup>
+      <AndroidAotProfile Include="Android/custom.aprof" />
+    </ItemGroup>
+    ```
 
 - Enable `Full AOT` instead of `Startup Tracing` in `Release` with `-p:AndroidEnableProfiledAot=false` to get the best runtime performance
 

doc/articles/controls/ContentDialog.md

@@ -10,16 +10,7 @@ Represents a dialog box that can be customized to contain checkboxes, hyperlinks
 
 If you're considering using a dialog in your app, check out our comprehensive video for a detailed guidance on the implementation:
 
-<div style="position: relative; width: 100%; padding-bottom: 56.25%;">
-    <iframe
-        src="https://www.youtube-nocookie.com/embed/VAUYH01LMEE"
-        title="YouTube video player"
-        frameborder="0"
-        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-        allowfullscreen
-        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;">
-    </iframe>
-</div>
+> [!Video https://www.youtube-nocookie.com/embed/VAUYH01LMEE]
 
 ## Overlay Background (iOS/Android)
 

doc/articles/create-an-app-rider.md

@@ -4,19 +4,11 @@ uid: Uno.GettingStarted.CreateAnApp.Rider
 
 # Create an app with Rider
 
-<div style="position: relative; width: 100%; padding-bottom: 56.25%;">
-    <iframe
-        src="https://www.youtube-nocookie.com/embed/BQdj9rqLcos"
-        title="YouTube video player"
-        frameborder="0"
-        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-        allowfullscreen
-        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;">
-    </iframe>
-</div>
-
 > [!NOTE]
-> Make sure to setup your environment by [following our instructions](xref:Uno.GetStarted.Rider).
+> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.Rider).
+
+<!-- markdownlint-disable MD028 -->
+> [!Video https://www.youtube-nocookie.com/embed/BQdj9rqLcos]
 
 ## Create the App
 
@@ -91,7 +83,7 @@ You will be able to build the Windows project.
 
 Select the `net8.0-desktop` target framework, then Run.
 
-***
+---
 
 ## Next Steps
 

doc/articles/create-an-app-vs2022.md

@@ -4,7 +4,7 @@ uid: Uno.GettingStarted.CreateAnApp.VS2022
 # Creating an app with Visual Studio 2022 for Windows
 
 > [!NOTE]
-> Make sure to setup your environment by [following our instructions](xref:Uno.GetStarted.vs2022).
+> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022).
 
 ## Create the App
 
@@ -115,7 +115,7 @@ To debug the **Android** platform:
     > [!NOTE]
     > If no android devices are available, a Visual Studio 17.7+ issue may require unloading/reloading the project. Right-click on the `MyApp` project and select **Unload Project** then **Load project**.
 
-***
+---
 
 You're all set!
 

doc/articles/create-an-app-vscode.md

@@ -4,7 +4,7 @@ uid: Uno.GettingStarted.CreateAnApp.VSCode
 # Creating an app with VS Code
 
 > [!NOTE]
-> Make sure to setup your environment by [following our instructions](xref:Uno.GetStarted.vscode).
+> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vscode).
 
 ## Create the App
 
@@ -213,11 +213,11 @@ In the status bar :
 
 Finally press `F5` to start the debugging session.
 
-***
+---
 
 You're all set!
 
-You can also find [additional VS Code topics](xref:Uno.vscode.additional), such as using snippets, updating existing apps to use VS Code
+You can also find [additional VS Code topics](xref:Uno.vscode.additional), such as using snippets, updating existing apps to use VS Code.
 
 ## Next Steps
 

doc/articles/features/ElevatedView.md

@@ -20,7 +20,7 @@ xmlns:toolkit="using:Uno.UI.Toolkit"
 
 After that, use the `ElevatedView` to host the content you need to be elevated:
 
-``` xml
+```xml
 <StackPanel Orientation="Horizontal" Spacing="20">
 
     <Button>Non-Elevated Button</Button>

doc/articles/features/Lottie.md

@@ -94,7 +94,7 @@ On UWP, you'll need to reference the following packages in your head project:
 * `Microsoft.Toolkit.Uwp.UI.Lottie` (for the `LottieVisualSource`)
 * `Microsoft.UI.Xaml` (for the `AnimatedVisualPlayer`)
 
-***
+---
 
 For more information, see [AnimatedVisualPlayer Class](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer).
 
@@ -131,15 +131,15 @@ Here's how to use this feature:
 
 1. Add a _css-like_ declaration to your Lottie shape like this then put this in the name of the shape. That means the `nm` property in the json-generated file.
 
-   ``` css
+   ```css
    { Color: var(MyColor); }
    ```
 
    In that case, it will create a property (variable) named `MyColor`. It is possible to reuse the same property name on many layers in the same lottie file.
 
 2. Use it that way:
 
-   ``` xml
+   ```xml
    <winui:AnimatedVisualPlayer
        x:Name="player"
        AutoPlay="true">

doc/articles/features/PasswordVault.md

@@ -46,7 +46,7 @@ There is no way to persist a secured data in a Web browser. Even if we generate
 there is no safe place to store this key except by relying on server components, which broke the offline support (and Progressive Web App).
 So currently we preferred to **not** implement the `PasswordVault`. It will throw a `NotSupportedException` when you try to create a new instance.
 
-***
+---
 
 ## PasswordCredential
 

doc/articles/features/applicationdata.md

@@ -52,7 +52,7 @@ string text = await FileIO.ReadTextAsync(file);
 
 The `LocalSettings` and `RoamingSettings` properties provide access to simple key-value containers that allow storage of lightweight user and application preferences. The values stored in settings should be simple serializable types. To store more complex data structures, it is preferred to serialize them first into a string (for example using a JSON serializer).
 
-``` csharp
+```csharp
 ApplicationDataContainer localSettings = ApplicationData.Current.LocalSettings;
 
 // Save a setting.

doc/articles/features/clipboard.md

@@ -23,16 +23,7 @@ uid: Uno.Features.Clipboard
 
 ## Using Clipboard with Uno
 
-<div style="position: relative; width: 100%; padding-bottom: 56.25%;">
-    <iframe
-        src="https://www.youtube-nocookie.com/embed/bfT4_LZrSQQ"
-        title="YouTube video player"
-        frameborder="0"
-        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-        allowfullscreen
-        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;">
-    </iframe>
-</div>
+> [!Video https://www.youtube-nocookie.com/embed/bfT4_LZrSQQ]
 
 * `SetContent` and `GetContent` APIs currently support textual data on all platforms. On Android, they also support URI and HTML formats, but the clipboard can hold only one item. Setting multiple items at once does not work reliably.
 * `ContentChanged` event can observe clipboard changes only when the application is in the foreground. On macOS, the `ContentChanged` event checks for clipboard changes by polling the current `NSPasteboard` change count in 1-second intervals. The polling starts only after the first subscriber attaches to the `ContentChanged` event and stops after the last subscriber unsubscribes.

doc/articles/features/custom-fonts.md

@@ -25,7 +25,7 @@ In order to use a custom font in your application:
 
 On Wasm platform, fonts files are loaded by the browser and can take some time to load, resulting in performance degradation and potential flickering when the font is actually available for rendering. In order to prevent this, it is possible to instruct the browser to preload the font before the rendering:
 
-``` csharp
+```csharp
 // Preloading of font families on Wasm. Add this before the Application.Start() in the Program.cs
 
 public static void Main(string[] args)
@@ -203,7 +203,7 @@ First, the font needs to be defined in CSS.
 
 Second, you can use it in XAML in this way:
 
-``` xml
+```xml
 <!-- XAML usage of CSS defined font -->
 
 <TextBlock FontFamily="MyCustomFontAsBase64">This text should be rendered using the font defined as base64 in CSS.</TextBlock>

doc/articles/features/progressring.md

@@ -48,4 +48,4 @@ To use the MUX `ProgressRing` on non-Skia targets and WUX `ProgressRing` on Skia
 </Page>
 ```
 
-***
+---

doc/articles/features/routed-events.md

@@ -10,7 +10,7 @@ This article covers some of the finer technical details of Uno Platform's routed
 
 ## Event Bubbling Flow
 
-``` plain
+```plain
 [1]---------------------+
 | An event is fired     |
 +--------+--------------+
@@ -80,7 +80,7 @@ platform propagate the events. But this will cause more interop between managed
 You can control which events are bubbling in managed code by using the `EventsBubblingInManagedCode`
 dependency property. The value of this property is inherited to children. Example:
 
-``` csharp
+```csharp
   // Make sure PointerPressed and PointerReleased are always bubbling in
   // managed code when they are originating from myControl and its children.
   myControl.EventsBubblingInManagedCode =

doc/articles/features/svg.md

@@ -42,7 +42,7 @@ To use SVG, install the following NuGet packages into the iOS, macOS, Mac Cataly
 
 Add the SVG Image to the app project and make sure that the build action is set to Content.
 
-***
+---
 
 Now, you can display the SVG image in an `Image` by referencing it from the `Source` property. For example:
 

doc/articles/features/using-skia-desktop.md

@@ -41,7 +41,7 @@ This builder allows us to configure the SkiaHost and setup which platforms will
 
 [!include[linux-setup](../includes/additional-linux-setup-inline.md)]
 
-***
+---
 
 ### Troubleshooting OpenGL integration