llm-in-text/milkdown-docs/guide/keyboard-shortcuts.md

Keyboard Shortcuts

Keyboard shortcuts are a crucial part of the editor's user experience. Milkdown provides a flexible system for configuring keyboard shortcuts through presets and plugins.

Default Shortcuts

---

Milkdown comes with a set of default keyboard shortcuts from both presets and plugins. Here's a comprehensive list of all internal shortcuts:

💡 Note

Mod represents the platform-specific modifier key:

• Windows/Linux: Ctrl
• macOS: Command

Commonmark Preset Shortcuts

Headings

Shortcut	Description
Mod-Alt-1	Turn block into h1
Mod-Alt-2	Turn block into h2
Mod-Alt-3	Turn block into h3
Mod-Alt-4	Turn block into h4
Mod-Alt-5	Turn block into h5
Mod-Alt-6	Turn block into h6
Delete/Backspace	Downgrade heading level

Block Elements

Shortcut	Description
Mod-Shift-b	Wrap selection in blockquote
Mod-Shift-8	Wrap in bullet list
Mod-Shift-7	Wrap in ordered list
Mod-Shift-c	Wrap in code block
Shift-Enter	Insert hard break
Mod-Alt-0	Wrap in paragraph

Text Formatting

Shortcut	Description
Mod-b	Toggle bold
Mod-i	Toggle italic
Mod-e	Toggle inline code

GFM Preset Shortcuts

Text Formatting

Shortcut	Description
Mod-Alt-x	Toggle strikethrough

Tables

Shortcut	Description
Mod-]	Move to next cell
Mod-[	Move to previous cell
Mod-Enter/Enter	Exit table and break if possible

Configuring Shortcuts

---

You can customize keyboard shortcuts by configuring the keymap in the editor setup:

import { blockquoteKeymap, commonmark } from "@milkdown/kit/preset/commonmark";

Editor.make()
  .config((ctx) => {
    ctx.set(blockquoteKeymap.key, {
      WrapInBlockquote: "Mod-Shift-b",
      // or you may want to bind multiple keys:
      WrapInBlockquote: ["Mod-Shift-b", "Mod-b"],
    });
  })
  .use(commonmark);

Defining Keymaps

---

Keymaps in Milkdown are defined using the $useKeymap utility. Here's how to define keymaps for different features:

Heading Keymap Example

import { $useKeymap } from "@milkdown/utils";
import { commandsCtx } from "@milkdown/core";

export const headingKeymap = $useKeymap("headingKeymap", {
  TurnIntoH1: {
    shortcuts: "Mod-Alt-1",
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => commands.call(wrapInHeadingCommand.key, 1);
    },
  },
  TurnIntoH2: {
    shortcuts: "Mod-Alt-2",
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => commands.call(wrapInHeadingCommand.key, 2);
    },
  },
  // ... more heading levels
  DowngradeHeading: {
    shortcuts: ["Delete", "Backspace"],
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => commands.call(downgradeHeadingCommand.key);
    },
  },
});

Strong (Bold) Keymap Example

import { $useKeymap } from "@milkdown/utils";
import { commandsCtx } from "@milkdown/core";

export const strongKeymap = $useKeymap("strongKeymap", {
  ToggleBold: {
    shortcuts: ["Mod-b"],
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => commands.call(toggleStrongCommand.key);
    },
  },
});

Keymap Structure

Each keymap definition follows this structure:

$useKeymap('keymapName', {
  CommandName: {
    shortcuts: string | string[],  // Single shortcut or array of shortcuts
    priority?: number,             // (Optional) Priority of the shortcut
    command: (ctx) => () => {      // Command to execute
      const commands = ctx.get(commandsCtx);
      return () => commands.call(commandKey, ...args);
    },
  },
});

Creating Custom Shortcuts

---

If you need to add custom shortcuts, you can create a keymap plugin:

import { $useKeymap } from "@milkdown/utils";
import { commandsCtx } from "@milkdown/core";

const customKeymap = $useKeymap("customKeymap", {
  CustomCommand: {
    shortcuts: "F1",
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => commands.call(someCommand.key);
    },
  },
});

// Usage
Editor.make().use(customKeymap).use(commonmark);

Example: Custom Command with Shortcut

import { $command, $useKeymap } from "@milkdown/utils";
import { commandsCtx } from "@milkdown/core";

// Create a custom command
const customCommand = $command("CustomCommand", (ctx) => () => {
  return (state, dispatch) => {
    // Command implementation
    return true;
  };
});

// Create a keymap
const customKeymap = $useKeymap("customKeymap", {
  CustomCommand: {
    shortcuts: ["F1", "Mod-F1"], // Multiple shortcuts
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => commands.call(customCommand.key);
    },
  },
});

// Usage
Editor.make().use(customCommand).use(customKeymap);

Shortcut Priority

You can control the order in which shortcuts are handled by specifying a priority property. Shortcuts with higher priority values are handled before those with lower values. This is useful if you want your custom shortcut to override or take precedence over other shortcuts that use the same key combination.

When multiple shortcuts are registered for the same key, they are executed in order of priority. If a shortcut command returns false, the next shortcut with the same key will be tried. If it returns true, no further commands for that key will be run. This allows you to chain or override shortcut behaviors as needed.

• The default priority is 50.
• Normal priority values should be between 1 and 100.
• Use higher numbers to ensure your shortcut is registered before others with the same key.

Example: Using Priority

import { $useKeymap } from "@milkdown/utils";
import { commandsCtx } from "@milkdown/core";

export const customKeymap = $useKeymap("customKeymap", {
  CustomBold: {
    shortcuts: "Mod-b",
    priority: 100, // Highest in the normal range, so this runs first
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => {
        // Custom bold logic
        return true;
      };
    },
  },
  CustomAnotherBold: {
    shortcuts: "Mod-b",
    priority: 75, // Lower priority, will run only if CustomBold returns false
    command: (ctx) => {
      const commands = ctx.get(commandsCtx);
      return () => {
        // Custom italic logic
        return true;
      };
    },
  },
});