You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+66-3Lines changed: 66 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,13 +26,76 @@ If the original block contains an ordered list, the split blocks will maintain t
26
26
27
27
28
28
29
+
### 4. Hierarchical Headers
30
+
31
+
The plugin can intelligently apply and adjust heading levels to maintain a clear document structure. When the `useHeader` option is enabled in a mode, it recursively processes the selected blocks and their children, ensuring that a child block's heading level is always one greater than its parent's. This is perfect for creating well-structured outlines from nested blocks.
32
+
33
+
34
+
### 5. Change Block Heading Level
35
+
36
+
This feature provides an enhanced way to change the heading level of a block, with the key advantage of being able to handle blocks that have leading hidden newline characters, a situation where Logseq's native heading shortcuts might not work as expected.
37
+
38
+
**Note:** This feature is disabled by default. To use it, you need to enable `enableHeaderShortcuts` in the plugin settings.
39
+
40
+
The available shortcuts are:
41
+
-`ctrl+0` (or `cmd+0` on macOS): Reset to a normal text block.
42
+
-`ctrl+1` (or `cmd+1` on macOS): Change to Heading 1.
43
+
-`ctrl+2` (or `cmd+2` on macOS): Change to Heading 2.
44
+
-`ctrl+3` (or `cmd+3` on macOS): Change to Heading 3.
45
+
-`ctrl+4` (or `cmd+4` on macOS): Change to Heading 4.
46
+
-`ctrl+5` (or `cmd+5` on macOS): Change to Heading 5.
47
+
-`ctrl+6` (or `cmd+6` on macOS): Change to Heading 6.
48
+
29
49
## Usage
30
50
31
-
1. Select one or multiple blocks you want to split in Logseq.
51
+
1.**Select Blocks**: Choose one or more blocks in Logseq that you want to transform.
52
+
2.**Open Toolbar**: Click the **Block Transformer** icon in the Logseq toolbar. This will open a panel where you can manage and customize transformation modes.
53
+
3.**Configure Modes**: In the panel, you can:
54
+
***Switch between modes**: Select the active transformation mode from a list of presets (e.g., "Split", "Header", "Full").
55
+
***Edit modes**: Adjust the settings for each mode, such as whether to split by lines, convert bold to headers, or handle code blocks.
56
+
***Add/Remove modes**: Create new custom modes or delete existing ones to fit your workflow.
57
+
4.**Transform**: Once your modes are configured, press the transform shortcut (`ctrl+t` by default) to apply the currently active mode's settings to your selected blocks. You can also switch between modes quickly using `ctrl+shift+t`.
58
+
59
+
This system allows for powerful customization directly from the UI, letting you define multiple transformation styles and switch between them easily.
60
+
61
+
## Settings
62
+
63
+
The plugin's behavior is primarily controlled through **Transform Modes**, which are fully editable from the toolbar panel. Here are the core concepts:
64
+
65
+
| Key | Description | Type | Default |
66
+
| --- | --- | --- | --- |
67
+
|`transformModes`| A list of customizable transformation profiles. Each mode has its own set of rules. |`object[]`| See below |
68
+
|`activeModeId`| The ID of the currently active transformation mode. |`number`|`1`|
69
+
|`transformShortcut`| Keyboard shortcut to apply the active transformation mode. |`string`|`ctrl+t`|
70
+
|`transformModeShortcut`| Keyboard shortcut to cycle through the available transformation modes. |`string`|`ctrl+shift+t`|
71
+
|`enableHeaderShortcuts`| Enable shortcuts (`ctrl+0` to `ctrl+6`) to change heading levels. |`boolean`|`false`|
72
+
73
+
### Default Transform Modes
74
+
75
+
The plugin comes with four default modes:
76
+
77
+
1.**Split**: Splits blocks by newlines and list items.
78
+
2.**Header**: Converts markdown heading syntax within blocks to actual block headers.
79
+
3.**Split+Header**: Combines the functionality of the first two modes.
80
+
4.**Full**: A comprehensive mode that splits blocks, handles headers, converts ordered lists to non-ordered, and turns bolded text into headers.
81
+
82
+
### Mode Options Explained
83
+
84
+
When you edit or create a transform mode, you can configure the following options based on the logic in [`src/block_handler.ts`](src/block_handler.ts):
32
85
33
-
2. Press `Ctrl+T` or `Cmd+T`.
86
+
| Option | Description |
87
+
| --- | --- |
88
+
|`name`| The display name for the mode in the toolbar UI. |
89
+
|`useSplit`| If enabled, splits a block's content into multiple new blocks based on line breaks, list items (`-`, `*`, `1.`), and tables. This effectively unnests content within a single block into separate, structured blocks. |
90
+
|`useHeader`| If enabled, this option recursively traverses the selected blocks and their children, applying hierarchical heading levels. It ensures that child blocks have a heading level exactly one greater than their parent, creating a structured outline. This affects existing content that looks like a header. |
91
+
|`removeEmptyLine`| When `useSplit` is active, this will cause any empty lines in the original block(s) to be discarded instead of being turned into empty blocks. |
92
+
|`splitCodeBlock`| When `useSplit` is active, this allows the content inside code fences (```) to be split. If disabled, the entire code block is treated as a single unit. |
93
+
|`orderedToNonOrdered`| If enabled, converts ordered list items (e.g., `1. First`) into non-ordered list items (e.g., `- First`). It also removes numbering from lines that are converted to headers. |
94
+
|`boldToHeader`| If enabled, any line that is only **bold text** (and optional trailing punctuation) will be converted into a header during the `useHeader` action. |
95
+
|`removeTailPunctuation`| When converting text to a header (e.g., with `boldToHeader`), this option removes any trailing punctuation marks like commas or periods. |
96
+
|`maxHeaderLevel`| Sets the maximum heading level (from 1 to 6) that the `useHeader` action can apply. |
34
97
35
-
3. The split blocks will be automatically added to your notes.
98
+
**Note:** All settings, including shortcuts and modes, can be modified. If you change a shortcut, you may need to restart Logseq for it to take effect.
0 commit comments