docs: Add Global and Slide Configuration Guides

doc/website/source/guides/code-generation.md

@@ -1,6 +1,6 @@
 ---
 title: Code generation
-navOrder: 12
+navOrder: 14
 ---
 
 This package comes with a [mason](https://pub.dev/packages/mason) template that can be used to generate a new slide for the slide deck.

doc/website/source/guides/custom-shortcuts.md

@@ -1,6 +1,6 @@
 ---
 title: Custom shortcuts
-navOrder: 10
+navOrder: 12
 ---
 
 # Custom shortcuts

doc/website/source/guides/global-configuration.md

@@ -0,0 +1,183 @@
+---
+title: Global configuration
+navOrder: 2
+---
+
+# Global configuration
+
+The global configuration for the slide deck allows you to define the default settings for all slides in your presentation. You can configure the background, controls, footer, header, progress indicator, and more.
+
+Some of these configurations can be overridden on a per-slide basis. For more information, see the [Slide configuration](/guides/slide-configuration/) guide.
+
+## Defining the global configuration
+
+You can define the global configuration by passing a `FlutterDeckConfiguration` object to the `FlutterDeckApp` widget.
+
+```dart
+FlutterDeckApp(
+  configuration: const FlutterDeckConfiguration(
+    background: FlutterDeckBackgroundConfiguration(
+      light: FlutterDeckBackground.solid(Color(0xFFB5FFFC)),
+      dark: FlutterDeckBackground.solid(Color(0xFF16222A)),
+    ),
+    controls: FlutterDeckControlsConfiguration(
+      presenterToolbarVisible: true,
+      gestures: FlutterDeckGesturesConfiguration.mobileOnly(),
+      shortcuts: FlutterDeckShortcutsConfiguration(
+        enabled: true,
+      ),
+    ),
+    footer: FlutterDeckFooterConfiguration(
+      showFooter: true,
+      showSlideNumbers: true,
+      showSocialHandle: true,
+    ),
+    header: FlutterDeckHeaderConfiguration(
+      showHeader: false,
+    ),
+    marker: FlutterDeckMarkerConfiguration(
+      color: Colors.cyan,
+      strokeWidth: 8.0,
+    ),
+    progressIndicator: FlutterDeckProgressIndicator.solid(),
+    showProgress: true,
+    slideSize: FlutterDeckSlideSize.responsive(),
+    transition: FlutterDeckTransition.fade(),
+  ),
+  slides: const [
+    // ...
+  ],
+);
+```
+
+## Configuration properties
+
+### Background
+
+The `background` property configures the default background for the slide deck using `FlutterDeckBackgroundConfiguration`. By default, the background is transparent and the `FlutterDeckSlideThemeData.backgroundColor` is used.
+
+You can specify different backgrounds for light and dark themes:
+
+```dart
+const FlutterDeckConfiguration(
+  background: FlutterDeckBackgroundConfiguration(
+    light: FlutterDeckBackground.solid(Colors.white),
+    dark: FlutterDeckBackground.solid(Colors.black),
+  ),
+)
+```
+
+_Note: This configuration cannot be overridden by the slide configuration, but rather by passing a background builder to the specific slide._
+
+### Controls
+
+The `controls` property configures the controls for the slide deck using `FlutterDeckControlsConfiguration`. By default, the presenter toolbar is visible, the default keyboard controls are enabled, and gestures are enabled on mobile platforms only. For more information, see the [Controls](/playback/controls/) guide.
+
+```dart
+const FlutterDeckConfiguration(
+  controls: FlutterDeckControlsConfiguration(
+    presenterToolbarVisible: true,
+  ),
+)
+```
+
+_Note: This configuration cannot be overridden by the slide configuration._
+
+### Footer
+
+The `footer` property configures the footer component for the slide deck using `FlutterDeckFooterConfiguration`. By default, the footer is not shown.
+
+```dart
+const FlutterDeckConfiguration(
+  footer: FlutterDeckFooterConfiguration(
+    showFooter: true,
+    showSlideNumbers: true,
+    showSocialHandle: true,
+  ),
+)
+```
+
+### Header
+
+The `header` property configures the header component for the slide deck using `FlutterDeckHeaderConfiguration`. By default, the header is not shown.
+
+```dart
+const FlutterDeckConfiguration(
+  header: FlutterDeckHeaderConfiguration(
+    showHeader: true,
+    title: 'Presentation Title',
+  ),
+)
+```
+
+### Marker
+
+The `marker` property configures the drawing marker tool using `FlutterDeckMarkerConfiguration`. By default, the marker is red with a stroke width of 5px.
+
+```dart
+const FlutterDeckConfiguration(
+  marker: FlutterDeckMarkerConfiguration(
+    color: Colors.red,
+    strokeWidth: 5.0,
+  ),
+)
+```
+
+_Note: This configuration cannot be overridden by the slide configuration._
+
+### Progress indicator
+
+The `progressIndicator` property configures the progress indicator to show in the slide deck using `FlutterDeckProgressIndicator`. By default, a solid progress indicator with a primary color from the theme is used.
+
+```dart
+const FlutterDeckConfiguration(
+  progressIndicator: FlutterDeckProgressIndicator.gradient(
+    gradient: LinearGradient(
+      colors: [Colors.blue, Colors.purple],
+    ),
+  ),
+)
+```
+
+### Show progress
+
+The `showProgress` property determines whether to show the presentation progress or not. The default is `true`.
+
+```dart
+const FlutterDeckConfiguration(
+  showProgress: false,
+)
+```
+
+### Slide size
+
+The `slideSize` property configures the size of the slides in the slide deck using `FlutterDeckSlideSize`. By default, the size is responsive, which means it is not constrained and will adapt to the screen size.
+
+```dart
+const FlutterDeckConfiguration(
+  slideSize: FlutterDeckSlideSize.fromAspectRatio(
+    aspectRatio: FlutterDeckAspectRatio.ratio16x9(),
+    resolution: FlutterDeckResolution.fhd(),
+  ),
+)
+```
+
+_Note: This configuration cannot be overridden by the slide configuration._
+
+### Template overrides
+
+The `templateOverrides` property allows you to override default slide template configurations using `FlutterDeckTemplateOverrideConfiguration`.
+
+For more information, see the [Template overrides](/guides/template-overrides/) guide.
+
+### Transition
+
+The `transition` property configures the transition to use when navigating between slides. The default transition is `FlutterDeckTransition.none()`.
+
+```dart
+const FlutterDeckConfiguration(
+  transition: FlutterDeckTransition.fade(),
+)
+```
+
+For more information, see the [Transitions](/guides/transitions/) guide.

doc/website/source/guides/hiding-slides.md

@@ -1,6 +1,6 @@
 ---
 title: Hiding slides
-navOrder: 5
+navOrder: 7
 ---
 
 By default, all slides are visible and available in the slide deck. However, you can hide a slide by setting the `hidden` property to `true` for the slide configuration:

doc/website/source/guides/initial-slide.md

@@ -1,6 +1,6 @@
 ---
 title: Initial slide
-navOrder: 6
+navOrder: 8
 ---
 
 By default, the first slide in the `slides` list is the initial slide. However, you can specify a different slide as the initial one by setting the `initial` property to `true` in the `FlutterDeckSlideConfiguration`. This keeps the slide order intact while allowing you to define a different starting point.

doc/website/source/guides/localization.md

@@ -1,6 +1,6 @@
 ---
 title: Localization
-navOrder: 7
+navOrder: 9
 ---
 
 This package comes with a built-in localization support. You can change the locale of the slide deck at runtime (see [controls](/playback/controls/)). The updated locale will be applied to the whole slide deck.

doc/website/source/guides/presentation-state.md

@@ -1,6 +1,6 @@
 ---
 title: Presentation state
-navOrder: 11
+navOrder: 13
 ---
 
 The slide deck state is managed by the `FlutterDeck` widget. This widget is responsible for managing the state of the slide deck, its configuration, navigation, and other details. By using the `FlutterDeck` extensions, you can access the slide deck state and its methods from anywhere in the app:

doc/website/source/guides/slide-configuration.md

@@ -0,0 +1,139 @@
+---
+title: Slide configuration
+navOrder: 3
+---
+
+# Slide configuration
+
+You can configure each slide individually using `FlutterDeckSlideConfiguration`. This configuration overrides the global presentation configuration for the specific slide. It also includes slide-specific configurations like route, title, steps, speaker notes, and whether the slide is hidden or initial.
+
+## Defining slide configuration
+
+There are multiple ways to configure a slide, depending on how you create it.
+
+### Using `withSlideConfiguration`
+
+If you are using a standard Flutter widget as a slide, you can use the `.withSlideConfiguration()` extension to provide the configuration:
+
+```dart
+Scaffold(
+  body: Center(child: Text('Slide content')),
+).withSlideConfiguration(
+  const FlutterDeckSlideConfiguration(
+    route: '/custom-route',
+    title: 'Custom Slide',
+    speakerNotes: 'Do not forget to talk about this slide.',
+    hidden: false,
+    initial: false,
+    steps: 2,
+  ),
+)
+```
+
+### Using `FlutterDeckSlide` templates
+
+When using standard flutter_deck slide templates, pass the configuration in the template's constructor:
+
+```dart
+FlutterDeckSlide.custom(
+  configuration: const FlutterDeckSlideConfiguration(
+    route: '/custom-slide',
+    title: 'Custom Slide Template',
+    footer: FlutterDeckFooterConfiguration(showFooter: false),
+  ),
+  builder: (context) => const Center(
+    child: Text('Custom slide template content'),
+  ),
+)
+```
+
+### Subclassing `FlutterDeckSlideWidget`
+
+If you subclass `FlutterDeckSlideWidget`, you provide the configuration via the `super` constructor:
+
+```dart
+class MySlide extends FlutterDeckSlideWidget {
+  const MySlide()
+      : super(
+          configuration: const FlutterDeckSlideConfiguration(
+            route: '/my-slide',
+            title: 'My Slide',
+            steps: 3,
+            transition: FlutterDeckTransition.fade(),
+          ),
+        );
+
+  @override
+  Widget build(BuildContext context) {
+    return const Scaffold(
+      body: Center(child: Text('My custom slide')),
+    );
+  }
+}
+```
+
+## Configuration properties
+
+### Route
+
+The `route` property (required) is the URL path segment used to navigate to this slide. Each route must be unique.
+
+### Title
+
+The `title` property sets the title of the slide. If set, it will be used in the navigation drawer instead of the header title (or route as a fallback).
+
+### Speaker Notes
+
+The `speakerNotes` property sets the speaker notes for the slide. These notes are visible in the [presenter view](/playback/presenter-view/) and are not shown to the audience. The default is an empty string.
+
+### Hidden
+
+The `hidden` property determines whether the slide should be hidden from the presentation. Hidden slides cannot be navigated to using standard controls and do not appear in the slide deck overview. The default is `false`.
+
+For more information, see the [Hiding slides](/guides/hiding-slides/) guide.
+
+### Initial
+
+The `initial` property sets the slide as the initial slide of the presentation. On Web, this is only used if the URL path is not set; otherwise, the URL path determines the initial slide. The default is `false`.
+
+For more information, see the [Initial slide](/guides/initial-slide/) guide.
+
+### Steps
+
+The `steps` property defines the number of internal steps the slide has. It is useful for building animations or revealing content sequentially on a single slide. The default is `1`.
+
+For more information, see the [Slide steps](/guides/slide-steps/) guide.
+
+### Preload Images
+
+The `preloadImages` property allows you to define a set of image URLs or asset paths to preload for the slide. The images will be preloaded before the slide is shown.
+
+```dart
+const FlutterDeckSlideConfiguration(
+  route: '/image-slide',
+  preloadImages: {
+    'assets/images/my_image.png',
+    'https://example.com/my_image.png',
+  },
+)
+```
+
+## Overriding global configuration
+
+A slide configuration can override several global configuration properties on a per-slide basis:
+
+- **`footer`**: Overrides the `FlutterDeckFooterConfiguration`.
+- **`header`**: Overrides the `FlutterDeckHeaderConfiguration`.
+- **`progressIndicator`**: Overrides the `FlutterDeckProgressIndicator`.
+- **`showProgress`**: Overrides whether to show the progress indicator on this slide.
+- **`transition`**: Overrides the transition effect when navigating to this slide (`FlutterDeckTransition`).
+
+```dart
+const FlutterDeckSlideConfiguration(
+  route: '/no-footer',
+  footer: FlutterDeckFooterConfiguration(showFooter: false),
+  transition: FlutterDeckTransition.slide(),
+)
+```
+
+Properties like `background`, `controls`, `marker`, `slideSize`, and `templateOverrides` cannot be overridden via slide configuration. `background` is configured per template, while the others apply to the entire deck.

doc/website/source/guides/slide-steps.md

@@ -1,6 +1,6 @@
 ---
 title: Multi-Step slides
-navOrder: 4
+navOrder: 6
 ---
 
 Steps is a feature that allows you to navigate through a slide, well, step by step. You can access the current step from any widget. This way, you can reveal or hide content, run animations, etc.

doc/website/source/guides/template-overrides.md

@@ -1,6 +1,6 @@
 ---
 title: Template overrides
-navOrder: 9
+navOrder: 11
 ---
 
 The `flutter_deck` package comes with a set of predefined slide templates. However, sometimes you might want to customize the look and feel of these templates to match your brand or design. For instance, you might want to change the layout of the title slide or update the layout of the split slide.

doc/website/source/guides/theming.md

@@ -1,6 +1,6 @@
 ---
 title: Theming
-navOrder: 2
+navOrder: 4
 ---
 
 You can customize the theme of your slide deck by providing a `FlutterDeckThemeData` to the `FlutterDeckApp` widget: