Heading
Structure content with headings using `toggleHeading`.
Type: Node
Headings organize content into sections. Supports levels 1 through 6, rendering as <h1> through <h6> in HTML output.
Demo
Installation
import { Heading } from "@arkpad/extension-heading";Commands
The extension provides two primary commands for managing headings:
// Toggles the current block between the specified heading level and a paragraph
editor.runCommand("toggleHeading", { level: 1 });
// Strictly sets the current block to the specified heading level
editor.runCommand("setHeading", { level: 2 });Chaining Commands
For optimal user experience, chain the focus command together with heading toggles to ensure focus is maintained:
editor.chain().focus().toggleHeading({ level: 3 }).run();Keyboard Shortcuts
The keyboard shortcuts are automatically registered for all configured heading levels:
| Heading | Shortcut |
|---|---|
| H1 | Mod-Alt-1 |
| H2 | Mod-Alt-2 |
| H3 | Mod-Alt-3 |
| H4 | Mod-Alt-4 |
| H5 | Mod-Alt-5 |
| H6 | Mod-Alt-6 |
Markdown Input Rules
Type markdown hashes at the beginning of a line followed by a space to quickly transform the block:
| Shortcut | Result |
|---|---|
# | H1 |
## | H2 |
### | H3 |
#### | H4 |
##### | H5 |
###### | H6 |
Active States & Shorthands
You can check if a heading level is active using standard active state methods or convenient shorthands provided by the engine's activeMapping:
// Standard API
editor.isActive("heading", { level: 1 });
// Shorthand API (Mapped automatically by the engine)
editor.isActive("h1");
editor.isActive("h2");Configuration
Options
| Name | Type | Default | Description |
|---|---|---|---|
levels | number[] | [1, 2, 3, 4, 5, 6] | Configures which heading levels are enabled, shortcutted, and parsed. |
HTMLAttributes | Record<string, any> | {} | Key-value pairs of attributes to be rendered on all heading DOM elements. |
Heading.configure({
// Only enable H1, H2, and H3
levels: [1, 2, 3],
// Apply a custom CSS class to all headings
HTMLAttributes: {
class: "arkpad-heading",
},
});Note on Robust Rendering: If an invalid level (e.g.,
99) is passed to a heading node, the editor's renderer will gracefully fall back to the first level in your configured list (defaulting to1).