diff --git a/.gitignore b/.gitignore
index b78c59c6..84341d6d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@
### Mkdocs Site ###
site/
+.venv-*/
# Ignore codespaces / C# Dev Kit files
.mono
diff --git a/Directory.Packages.props b/Directory.Packages.props
index 4d26d91e..98af520b 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -46,6 +46,17 @@
+
+
diff --git a/README.md b/README.md
index 75237819..3f7cddc3 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,26 @@ The majority of tests in the test suite provide [TestContainers](https://testcon
> **NOTE**: The `.runsettings` file contains secrets. It should not be checked in. We have added this file to the `.gitignore` to ensure that it is
> not checked into public GitHub repositories.
+## 📖 Building the documentation site
+
+The documentation site is built with [MkDocs](https://www.mkdocs.org/). To build and serve it locally:
+
+```sh
+python3 -m venv .venv-docs
+source .venv-docs/bin/activate
+pip install mkdocs mkdocs-mermaid2-plugin
+
+mkdocs serve
+```
+
+Browse to [http://localhost:7000](http://localhost:7000) to view the site. `mkdocs serve` watches the `docs` folder and live-reloads whenever you make changes.
+
+To produce a static build instead (the output is written to `./site`, which is git-ignored):
+
+```sh
+mkdocs build
+```
+
## 🌍 Roadmap
Read what we [plan for next iterations](https://github.com/CommunityToolkit/Datasync/milestones), and feel free to ask questions.
diff --git a/docs/in-depth/client/index.md b/docs/in-depth/client/index.md
index 5a8a27f5..29d6b8e6 100644
--- a/docs/in-depth/client/index.md
+++ b/docs/in-depth/client/index.md
@@ -2,7 +2,7 @@
This guide shows you how to perform common scenarios using the Datasync Community Toolkit. Use the client library in any .NET 9 application, including AvaloniaUI, MAUI, Uno Platform, WinUI, and WPF applications.
-!!! note **Blazor WASM and Blazor Hybrid**
+!!! note "Blazor WASM and Blazor Hybrid"
The offline capabilities are known to have issues with Blazor WASM and Blazor Hybrid (since EF Core and SQLite do not work in those environments when running in the browser). Use online-only operations in these environments. For more information, see [our guide on Blazor WASM](./advanced/blazor-wasm.md)
This guide primary deals with offline operations. For online operations, see the [Online operations guide](./online.md).
@@ -26,6 +26,15 @@ Use the `OfflineDbContext` as the base for your offline storage:
}
}
+!!! note "Resolving the SQLitePCLRaw NuGet audit warning (NU1903)"
+ `OfflineDbContext` uses Entity Framework Core's SQLite provider for local storage, which transitively depends on an older version of `SQLitePCLRaw.bundle_e_sqlite3` that triggers a high-severity `NU1903` NuGet audit warning ([GHSA-2m69-gcr7-jv3q](https://github.com/advisories/GHSA-2m69-gcr7-jv3q)). If you see this warning in your own application, force the patched `SQLitePCLRaw` 3.x line by adding an explicit package reference to your client `.csproj` file:
+
+ ```xml
+
+ ```
+
+ See [issue #492](https://github.com/CommunityToolkit/Datasync/issues/492) for more details.
+
!!! warning
Sqlite stores DateTimeOffset using a second accuracy by default. We strongly recommend using [a ValueConverter](https://learn.microsoft.com/ef/core/modeling/value-conversions?tabs=data-annotations) to store date/time values.
@@ -38,7 +47,7 @@ Each synchronizable entity in an offline context **MUST** have the following pro
* `Version` - `string?` or `byte[]?` - the opaque version for the entity on the service - changes on each write.
* `Deleted` - boolean (optional) - only needed if using soft-delete on the service; marks the entity as deleted.
-!!! warning DO NOT USE THE SAME ENTITY TYPE FOR BOTH SERVICE AND CLIENT
+!!! warning "Do not use the same entity type for both service and client"
You may be tempted to use the same entity type for both service and client. This is a mistake:
* The service side entity types have automatic updates configured on UpdatedAt and Version which are not appropriate for the client.
diff --git a/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/TodoApp.BlazorWasm.Client.csproj b/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/TodoApp.BlazorWasm.Client.csproj
index b5006326..16e6e879 100644
--- a/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/TodoApp.BlazorWasm.Client.csproj
+++ b/samples/todoapp-blazor-wasm/TodoApp.BlazorWasm.Client/TodoApp.BlazorWasm.Client.csproj
@@ -11,6 +11,8 @@
+
+
diff --git a/samples/todoapp-tutorial/ClientApp/ClientApp.csproj b/samples/todoapp-tutorial/ClientApp/ClientApp.csproj
index c3c6132f..d39763a7 100644
--- a/samples/todoapp-tutorial/ClientApp/ClientApp.csproj
+++ b/samples/todoapp-tutorial/ClientApp/ClientApp.csproj
@@ -11,6 +11,8 @@
+
+
diff --git a/samples/todoapp/TodoApp.Avalonia/TodoApp.Avalonia/TodoApp.Avalonia.csproj b/samples/todoapp/TodoApp.Avalonia/TodoApp.Avalonia/TodoApp.Avalonia.csproj
index e2c0899e..3824f904 100644
--- a/samples/todoapp/TodoApp.Avalonia/TodoApp.Avalonia/TodoApp.Avalonia.csproj
+++ b/samples/todoapp/TodoApp.Avalonia/TodoApp.Avalonia/TodoApp.Avalonia.csproj
@@ -19,5 +19,7 @@
+
+
diff --git a/samples/todoapp/TodoApp.MAUI/TodoApp.MAUI.csproj b/samples/todoapp/TodoApp.MAUI/TodoApp.MAUI.csproj
index 424870a2..6235f7b9 100644
--- a/samples/todoapp/TodoApp.MAUI/TodoApp.MAUI.csproj
+++ b/samples/todoapp/TodoApp.MAUI/TodoApp.MAUI.csproj
@@ -54,6 +54,8 @@
+
+
diff --git a/samples/todoapp/TodoApp.Uno/Directory.Packages.props b/samples/todoapp/TodoApp.Uno/Directory.Packages.props
index 73f9c81f..6ab74fca 100644
--- a/samples/todoapp/TodoApp.Uno/Directory.Packages.props
+++ b/samples/todoapp/TodoApp.Uno/Directory.Packages.props
@@ -11,6 +11,8 @@
+
+
diff --git a/samples/todoapp/TodoApp.Uno/TodoApp.Uno/TodoApp.Uno.csproj b/samples/todoapp/TodoApp.Uno/TodoApp.Uno/TodoApp.Uno.csproj
index 741c2b8b..fe818551 100644
--- a/samples/todoapp/TodoApp.Uno/TodoApp.Uno/TodoApp.Uno.csproj
+++ b/samples/todoapp/TodoApp.Uno/TodoApp.Uno/TodoApp.Uno.csproj
@@ -61,6 +61,8 @@
+
+
diff --git a/samples/todoapp/TodoApp.WPF/TodoApp.WPF.csproj b/samples/todoapp/TodoApp.WPF/TodoApp.WPF.csproj
index 1dcc8772..4da1bdf8 100644
--- a/samples/todoapp/TodoApp.WPF/TodoApp.WPF.csproj
+++ b/samples/todoapp/TodoApp.WPF/TodoApp.WPF.csproj
@@ -11,5 +11,7 @@
+
+
diff --git a/samples/todoapp/TodoApp.WinUI3/TodoApp.WinUI3.csproj b/samples/todoapp/TodoApp.WinUI3/TodoApp.WinUI3.csproj
index c4863a84..890eaff5 100644
--- a/samples/todoapp/TodoApp.WinUI3/TodoApp.WinUI3.csproj
+++ b/samples/todoapp/TodoApp.WinUI3/TodoApp.WinUI3.csproj
@@ -36,6 +36,8 @@
+
+