diff --git a/plugins/by-name/mkdnflow/default.nix b/plugins/by-name/mkdnflow/default.nix
index 78b1e6ed..a7a12f80 100644
--- a/plugins/by-name/mkdnflow/default.nix
+++ b/plugins/by-name/mkdnflow/default.nix
@@ -8,6 +8,42 @@ lib.nixvim.plugins.mkNeovimPlugin {
 
   maintainers = [ lib.maintainers.khaneliman ];
 
+  settingsOptions = {
+    mappings = lib.nixvim.mkNullOrOption' {
+      type = with lib.types; attrsOf anything;
+      description = ''
+        Key mappings for mkdnflow commands.
+
+        Use the generated positional format for mapping entries:
+        - `false` to disable a command mapping.
+        - `[modes key]`, where `modes` is a string or list of mode strings.
+      '';
+      apply = lib.mapNullable (
+        mappings:
+        let
+          isLegacyMapping = mapping: lib.isAttrs mapping && mapping ? modes && mapping ? key;
+
+          legacyMappings = lib.filterAttrs (_: isLegacyMapping) mappings;
+
+          normalizedMappings =
+            mappings
+            // lib.mapAttrs (_: mapping: [
+              mapping.modes
+              mapping.key
+            ]) legacyMappings;
+        in
+        # TODO: Added 2026-02-11, remove after 27.05
+        lib.warnIf (legacyMappings != { }) ''
+          Nixvim (plugins.mkdnflow): Setting `plugins.mkdnflow.settings.mappings.<name> = { modes = ...; key = ...; }` is deprecated.
+          Use `plugins.mkdnflow.settings.mappings.<name> = [ <modes> <key> ];` instead.
+          Example:
+            `MkdnEnter = [ [ "n" "i" ] "<CR>" ];`
+          Legacy mappings in this definition: ${lib.concatStringsSep ", " (lib.attrNames legacyMappings)}
+        '' normalizedMappings
+      );
+    };
+  };
+
   settingsExample = {
     modules = {
       bib = false;
diff --git a/tests/test-sources/plugins/by-name/mkdnflow/default.nix b/tests/test-sources/plugins/by-name/mkdnflow/default.nix
index d2b76039..0fefdca2 100644
--- a/tests/test-sources/plugins/by-name/mkdnflow/default.nix
+++ b/tests/test-sources/plugins/by-name/mkdnflow/default.nix
@@ -77,134 +77,154 @@
             override = false;
           };
         };
+        mappings = {
+          MkdnEnter = [
+            [
+              "n"
+              "v"
+              "i"
+            ]
+            "<CR>"
+          ];
+          MkdnTab = false;
+          MkdnSTab = false;
+          MkdnNextLink = [
+            "n"
+            "<Tab>"
+          ];
+          MkdnPrevLink = [
+            "n"
+            "<S-Tab>"
+          ];
+          MkdnNextHeading = [
+            "n"
+            "]]"
+          ];
+          MkdnPrevHeading = [
+            "n"
+            "[["
+          ];
+          MkdnGoBack = [
+            "n"
+            "<BS>"
+          ];
+          MkdnGoForward = [
+            "n"
+            "<Del>"
+          ];
+          MkdnFollowLink = false;
+          MkdnCreateLink = false;
+          MkdnCreateLinkFromClipboard = [
+            [
+              "n"
+              "v"
+            ]
+            "<leader>p"
+          ];
+          MkdnDestroyLink = [
+            "n"
+            "<M-CR>"
+          ];
+          MkdnMoveSource = [
+            "n"
+            "<F2>"
+          ];
+          MkdnYankAnchorLink = [
+            "n"
+            "ya"
+          ];
+          MkdnYankFileAnchorLink = [
+            "n"
+            "yfa"
+          ];
+          MkdnIncreaseHeading = [
+            "n"
+            "+"
+          ];
+          MkdnDecreaseHeading = [
+            "n"
+            "-"
+          ];
+          MkdnToggleToDo = [
+            [
+              "n"
+              "v"
+            ]
+            "<C-Space>"
+          ];
+          MkdnNewListItem = false;
+          MkdnNewListItemBelowInsert = [
+            "n"
+            "o"
+          ];
+          MkdnNewListItemAboveInsert = [
+            "n"
+            "O"
+          ];
+          MkdnExtendList = false;
+          MkdnUpdateNumbering = [
+            "n"
+            "<leader>nn"
+          ];
+          MkdnTableNextCell = [
+            "i"
+            "<Tab>"
+          ];
+          MkdnTablePrevCell = [
+            "i"
+            "<S-Tab>"
+          ];
+          MkdnTableNextRow = false;
+          MkdnTablePrevRow = [
+            "i"
+            "<M-CR>"
+          ];
+          MkdnTableNewRowBelow = [
+            "n"
+            "<leader>ir"
+          ];
+          MkdnTableNewRowAbove = [
+            "n"
+            "<leader>iR"
+          ];
+          MkdnTableNewColAfter = [
+            "n"
+            "<leader>ic"
+          ];
+          MkdnTableNewColBefore = [
+            "n"
+            "<leader>iC"
+          ];
+          MkdnFoldSection = [
+            "n"
+            "<leader>f"
+          ];
+          MkdnUnfoldSection = [
+            "n"
+            "<leader>F"
+          ];
+        };
+      };
+    };
+
+  };
+
+  mappings-deprecated = {
+    plugins.mkdnflow = {
+      enable = true;
+      settings = {
         mappings = {
           MkdnEnter = {
             modes = [
               "n"
-              "v"
               "i"
             ];
             key = "<CR>";
           };
-          MkdnTab = false;
-          MkdnSTab = false;
-          MkdnNextLink = {
-            modes = "n";
-            key = "<Tab>";
-          };
-          MkdnPrevLink = {
-            modes = "n";
-            key = "<S-Tab>";
-          };
-          MkdnNextHeading = {
-            modes = "n";
-            key = "]]";
-          };
-          MkdnPrevHeading = {
-            modes = "n";
-            key = "[[";
-          };
-          MkdnGoBack = {
-            modes = "n";
-            key = "<BS>";
-          };
-          MkdnGoForward = {
-            modes = "n";
-            key = "<Del>";
-          };
-          MkdnFollowLink = false;
-          MkdnCreateLink = false;
-          MkdnCreateLinkFromClipboard = {
-            modes = [
-              "n"
-              "v"
-            ];
-            key = "<leader>p";
-          };
-          MkdnDestroyLink = {
-            modes = "n";
-            key = "<M-CR>";
-          };
-          MkdnMoveSource = {
-            modes = "n";
-            key = "<F2>";
-          };
-          MkdnYankAnchorLink = {
-            modes = "n";
-            key = "ya";
-          };
-          MkdnYankFileAnchorLink = {
-            modes = "n";
-            key = "yfa";
-          };
-          MkdnIncreaseHeading = {
-            modes = "n";
-            key = "+";
-          };
-          MkdnDecreaseHeading = {
-            modes = "n";
-            key = "-";
-          };
-          MkdnToggleToDo = {
-            modes = [
-              "n"
-              "v"
-            ];
-            key = "<C-Space>";
-          };
-          MkdnNewListItem = false;
-          MkdnNewListItemBelowInsert = {
-            modes = "n";
-            key = "o";
-          };
-          MkdnNewListItemAboveInsert = {
-            modes = "n";
-            key = "O";
-          };
-          MkdnExtendList = false;
-          MkdnUpdateNumbering = {
-            modes = "n";
-            key = "<leader>nn";
-          };
-          MkdnTableNextCell = {
-            modes = "i";
-            key = "<Tab>";
-          };
-          MkdnTablePrevCell = {
-            modes = "i";
-            key = "<S-Tab>";
-          };
-          MkdnTableNextRow = false;
-          MkdnTablePrevRow = {
-            modes = "i";
-            key = "<M-CR>";
-          };
-          MkdnTableNewRowBelow = {
-            modes = "n";
-            key = "<leader>ir";
-          };
-          MkdnTableNewRowAbove = {
-            modes = "n";
-            key = "<leader>iR";
-          };
-          MkdnTableNewColAfter = {
-            modes = "n";
-            key = "<leader>ic";
-          };
-          MkdnTableNewColBefore = {
-            modes = "n";
-            key = "<leader>iC";
-          };
-          MkdnFoldSection = {
-            modes = "n";
-            key = "<leader>f";
-          };
-          MkdnUnfoldSection = {
-            modes = "n";
-            key = "<leader>F";
-          };
         };
       };
     };
+
+    test.runNvim = false;
   };
 }