From 21e76f6bb6e522d554ce6fa222b155f149fba7de Mon Sep 17 00:00:00 2001
From: Maximilian Koeller <maximilian.koeller@siemens.com>
Date: Mon, 17 Aug 2026 12:14:40 +0200
Subject: [PATCH] docs: add configuration documentation

See https://github.com/siemens/ngx-datatable/issues/805
---
 docs/features/configuration.md                | 37 +++++++++++++++++++
 .../features.md => features/index.md}         |  4 +-
 zensical.toml                                 |  5 ++-
 3 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 docs/features/configuration.md
 rename docs/{introduction/features.md => features/index.md} (91%)

diff --git a/docs/features/configuration.md b/docs/features/configuration.md
new file mode 100644
index 000000000..093307b2f
--- /dev/null
+++ b/docs/features/configuration.md
@@ -0,0 +1,37 @@
+# Configuration
+
+Use `providedNgxDatatableConfig` to set defaults shared by all `ngx-datatable` instances in an application.
+Register it during bootstrap:
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { providedNgxDatatableConfig } from '@siemens/ngx-datatable';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    providedNgxDatatableConfig({
+      rowHeight: 48,
+      headerHeight: 48,
+      defaultColumnWidth: 200,
+      messages: {
+        emptyMessage: 'No results found',
+        totalMessage: 'results'
+      }
+    })
+  ]
+});
+```
+
+See the [NgxDatatableConfig API reference](../api/reference/ngx-datatable-config.md) for available configuration options.
+
+## Per-table Overrides
+
+Most properties can be overridden per table instance.
+`messages` and `cssClasses` support partial overrides.
+They are merged with the global configuration and the built-in defaults.
+
+```html
+<ngx-datatable [rows]="rows" [rowHeight]="64" [messages]="{ emptyMessage: 'No orders found' }">
+  ...
+</ngx-datatable>
+```
diff --git a/docs/introduction/features.md b/docs/features/index.md
similarity index 91%
rename from docs/introduction/features.md
rename to docs/features/index.md
index b0e23dc16..6b1141304 100644
--- a/docs/introduction/features.md
+++ b/docs/features/index.md
@@ -19,6 +19,8 @@ The current features include:
 - Decoupled theme'ing with included Google Material theme
 - Light codebase / No external dependencies
 
+See [Configuration](configuration.md) to configure shared defaults for all tables.
+
 ### Roadmap
 
 We are really excited about the table and wanted to get it out into the open as quickly as
@@ -31,7 +33,7 @@ possible so we had to delay some of the features but we plan to add the followin
 ### Alternatives
 
 This might not be the best fit for you given the above, there are some other great solutions
-and some this project borrows from; heres a short list:
+and some this project borrows from; here's a short list:
 
 - [ng2-super-table](https://github.com/andyperlitch/ng2-super-table)
 - [ng2-table](https://github.com/valor-software/ng2-table)
diff --git a/zensical.toml b/zensical.toml
index c61f64ffb..373f91760 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -16,12 +16,15 @@ nav = [
     { "Introduction" = [
         "index.md",
         { "Getting Started" = "introduction/getting-started.md" },
-        { "Features" = "introduction/features.md" },
         { "Modes" = "introduction/column-modes.md" },
         { "Architecture" = "introduction/architecture.md" },
         { "Theming" = "introduction/themes.md" },
         { "Change Detection" = "introduction/cd.md" },
     ] },
+    { "Features" = [
+        "features/index.md",
+        { "Configuration" = "features/configuration.md" },
+    ] },
     { "API" = [
         "api/index.md",
     ] },