Skip to content

Build your personal knowledge base with Trilium Notes

client/text editor: highlight the current block when hovering the drag handle

Adorian Doran180575985fdd
diff --git a/apps/server/src/assets/help/help_content.json b/apps/server/src/assets/help/help_content.json
index a6558d179b..a33d8e2d24 100644
--- a/apps/server/src/assets/help/help_content.json
+++ b/apps/server/src/assets/help/help_content.json
@@ -127,7 +127,7 @@
"_help_QxEyIjRBizuC": "<p><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Developer-specific%20formatting/Code%20blocks_image.jpg\"></p><p>The code blocks feature allows entering pieces of code in text notes.</p><p>Note that this feature is meant for generally small snippets of code. For larger files such as an entire log, see the&nbsp;<a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a>&nbsp;note type instead.</p><h2>Inserting a code block</h2><ul><li>Via the&nbsp;<a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>, look for the&nbsp;<span class=\"tn-icon cke cke-code-block\"></span> button.<ul><li>Pressing directly on the icon will insert a code block with the language that was selected most recently. If this is the first time a code block is inserted, the language will be “Auto-detected” by default.</li><li>Pressing the arrow next to the icon, which will show a popup with the available languages.</li></ul></li><li>Type <code>```</code> (as in Markdown).<ul><li>Note that it's not possible to specify the language, as it will default to the last selected language.</li></ul></li><li>Paste several lines of code copied from Visual Studio Code.<ul><li>The code block uses the language of the file in Visual Studio Code.</li><li>If that language is not in the list of languages, the code block uses <em>Auto-detected</em>.</li><li>The colors of the Visual Studio Code theme are removed.</li><li>A single line becomes inline code instead of a code block.</li><li>In Firefox, the code block always uses <em>Auto-detected</em>. Firefox can't read the language from Visual Studio Code.</li></ul></li></ul><h2>Exiting out of the code block</h2><ul><li>To exit out of a code block and enter a normal paragraph, move the cursor at the end of the code block and press Enter twice.</li><li>Similarly, to insert a paragraph above the note block, move the cursor at the beginning of the code block and press Enter twice.</li></ul><aside class=\"admonition note\"><p>If you've pasted a code block with a more complex HTML structure, exiting out of the code block by pressing Enter multiple times might not work. In that case the best approach is to delete the code block entirely and use Ctrl+Shift+V (paste as plain text).</p></aside><h2>Syntax highlighting &amp; color schemes</h2><p>Since TriliumNext v0.90.12, Trilium will try to offer syntax highlighting to the code block. Note that the syntax highlighting mechanism is slightly different than the one in&nbsp;<a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a>&nbsp;notes as different technologies are involved.</p><p>Interaction:</p><ul><li>When the language is set to <em>Auto-detected</em> (by default), Trilium will try to identify the programming language (or similar) that corresponds to the given snippet of text and highlight it. Only the languages enabled in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Code Notes</em> → <em>Available MIME types in the dropdown</em> are considered. If this is problematic, consider changing the language of the code block manually.</li><li>When the language is set to <em>Plain text</em>, there will be no syntax highlighting.</li></ul><p>Note that when editing a text note, syntax highlighting is automatically disabled if the code block is too big (somewhere around 500 lines). In&nbsp;<a class=\"reference-link\" href=\"#root/_help_CoFPLs3dRlXc\">Read-Only Notes</a>, in print and on a <a href=\"#root/_help_R9pX4DGra2Vt\">shared page</a>, a code block of more than 500 lines or 50,000 characters is shown without syntax highlighting. These limits are not configurable.</p><p>In order to configure this new feature, a section has been added in&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;→ <em>Appearance</em> to control the syntax highlighting. There the color scheme can be chosen, from a builtin selection of themes from Highlight.js. <em>VS Code (Light)</em> and <em>VS Code (Dark)</em> use the same colors as the default themes of <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes, so a code block and a code note color the same code alike.</p><ul><li>It is possible to disable the syntax highlighting for all the notes by selecting “No syntax highlighting” in the “Color scheme” option.</li><li>Word wrapping is disabled by default, but can be configured from the same section.</li><li>The tab width can also be adjusted from Options.</li></ul><aside class=\"admonition note\"><p><strong>Context regarding syntax highlighting</strong></p><p>In order to achieve the syntax highlight, the Highlight.js library is being used. Do note that support for syntax highlighting in code blocks is not a supported feature of the text editor we are using CKEditor), but rather a hack which makes use of the highlights API (used for highlighting search results for example). Nevertheless, we haven't noticed any major issues during the development of the feature, but feel free to report any issues you might have.</p><p>Most of the work to achieve the syntax highlight itself was already done by <a href=\"https://github.com/antoniotejada\">antoniotejada</a> in <a href=\"https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget\">https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget</a>. On our side we added customization but also additional functionality.</p></aside><h3>Migrating from existing syntax highlight plugins</h3><p>If you are already using a syntax highlighting plugin such as the <a href=\"https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget\">Trilium-SyntaxHighlightWidget</a> we are basing off of, it is important to disable that plugin before upgrading in order for it not to conflict with our implementation.</p><p>Should you encounter any issues after the migration, try running Trilium in safe mode.</p><h2>Changing the language of a code block</h2><p>Simply click anywhere inside the code block and press again the code block button in the&nbsp;<a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>:<br><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Developer-specific%20formatting/Code%20blocks_image.png\"></p><h2>Adjusting the list of languages</h2><p>The code blocks feature shares the list of languages with the&nbsp;<a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a>&nbsp;note type.</p><p>The supported languages, and the order in which they are listed, can be adjusted by going to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Code Notes</em> → <em>Available MIME types in the dropdown</em>. See <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> for how to add, remove and reorder them.</p><p>Note that the list of languages is not immediately refreshed, you'd have to manually <a href=\"#root/_help_s8alTXmpFR61\">refresh the application</a>.</p><h2>Text replacements and ligatures</h2><p><a class=\"reference-link\" href=\"#root/_help_oI7GoyilXXAr\">Automatic replacements</a>&nbsp;are a feature of text notes which converts some character sequences into another and some of them interfere with programming text, such as the conversion of quotes. While in a code block, the automatic replacements <strong>are not effect</strong>. The only way the automatic replacements can interfere is if the text is typed/pasted before being put in a code block.</p><p>A different feature is <em>programming ligatures</em>, which is simply a display affordance which turns <code>!=</code> into <code>≠</code> or <code>-&gt;</code> as <code>→</code> . These come from the <a href=\"#root/_help_w4rMEhJsALlA\">font</a>. The underlying text is not actually changed, and copying it out gives you back <code>!=</code> and <code>-&gt;</code>.</p><p>Ligatures can be disabled in&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a><em>→ Appearance → Fonts → Programming ligatures.</em></p>",
"_help_AgjCISero73a": "<figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:199/187;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Footnotes_image.png\" width=\"199\" height=\"187\"></figure><p>Footnotes are a good place to insert references to a paragraph or details that are displayed at the bottom of the note.</p><h2>Interaction</h2><ul><li>To insert a new footnote, press&nbsp;<span class=\"tn-icon cke cke-trilium-insert-footnote\"></span> (or press the right arrow and select <em>New footnote</em>).</li><li>To insert a reference to an existing footnote, press the right arrow and select <em>Insert footnote</em>, followed by the number of the footnote to insert.</li><li>Hovering over a reference (e.g. <code>[1]</code>) will display the content of the footnote in a tooltip for easy reference.</li><li>Clicking on a reference in the text (e.g. <code>[1]</code>) will navigate to the corresponding footnote.</li><li>Similarly, clicking on the <code>^</code> button of a footnote will navigate to the corresponding reference in the text.</li></ul>",
"_help_5wZallV2Qo1t": "<figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:220/76;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Format%20Painter_image.png\" width=\"220\" height=\"76\"></figure><p>The Format Painter is a feature in text notes that allows users to copy the formatting of text (such as <strong>bold</strong>, <em>italic</em>, <del>Strikethrough</del>, etc.) and apply it to other parts of the document. It helps maintain consistent formatting and accelerates the creation of rich content.</p><h2>Usage Instructions</h2><p>Click the text that you want to copy the formatting from and use the <em>Copy formatting</em> toolbar button (<span class=\"tn-icon cke cke-paint-roller\"></span>) to copy the style. Then select the target text with your mouse, or click a word, to apply the formatting.</p><ul><li><strong>To copy the formatting</strong>: Place the cursor inside text with some formatting and click the <em>Copy formatting</em> toolbar button. The mouse cursor changes to indicate the painter is armed.</li><li><strong>To paint with the copied formatting</strong>: Select the target text with your mouse. The formatting is applied when you release the button, and the painter disarms — the cursor returns to normal. Clicking or tapping a word applies it to the whole word.</li><li><strong>To paint a selection made otherwise</strong>, such as with the keyboard or the selection handles of a touch screen: select the target text, then use the toolbar button again, which reads <em>Apply formatting</em> once the selection has moved. On a phone, the formatting row stays open while the painter is armed, so the button stays in reach.</li><li><strong>To cancel without painting</strong>: Click the toolbar button again before selecting other text, or press <kbd>Escape</kbd>.</li></ul><h2>Limitations</h2><ol><li>Painting with block-level formatting (like headings or image styles) is not supported yet. This is because, in&nbsp;<a class=\"reference-link\" href=\"#root/_help_MI26XDLSAlCD\">CKEditor</a>, they are considered a part of the content rather than text formatting.</li><li>A click outside a word, such as between two spaces or at the end of a line, only primes the caret, so text you type there takes the copied formatting.</li><li>The painter is one-shot; each paint requires copying the formatting again.</li></ol>",
- "_help_nRhnJkTT8cPs": "<p>Trilium allows two different editing experiences for text notes, based on your preference.</p><p>The type of formatting toolbar can be changed by going to&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;and then looking for the&nbsp;<a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsTextNotes\">Text Notes</a>&nbsp;section. In it, look for the <em>Formatting toolbar</em> category.</p><h2>Floating</h2><p>The floating bar is a more minimalist option, in which the formatting is hidden behind two different popups.</p><h3>Block-level popup</h3><p>The first popup is the block-level popup. This will appear to the left of the current paragraph you are currently editing, as a sequence of dots:<br><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Formatting%20toolbar_image.jpg\"></p><p>Clicking this popup will reveal the formatting options that are specific to the entire paragraph, such as setting a heading, lists, tables, etc.</p><p>The dots are also a drag handle: drag them to move the paragraph, all the selected paragraphs, or a selected element such as an image, a table or an included note to another place in the note. Right-clicking them copies a reference to the paragraph or to the selected paragraphs, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>.</p><figure class=\"image\"><img style=\"aspect-ratio:1404/156;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/2_Formatting%20toolbar_image.png\" width=\"1404\" height=\"156\"></figure><h3>Inline popup</h3><p>The inline popup appears automatically when selecting a text:</p><figure class=\"image\"><img style=\"aspect-ratio:1008/154;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/1_Formatting%20toolbar_image.png\" width=\"1008\" height=\"154\"></figure><p>All the options here apply only to the selected portion of text, such as changing the font size, or making the text bold.</p><h2>Fixed</h2><p>The fixed formatting offers a more traditional editing paradigm, usually useful if a lot of formatting is needed.</p><p>All the options are combined into a single toolbar that will appear at the above the note. When using&nbsp;<a class=\"reference-link\" href=\"#root/_help_luNhaphA37EO\">Split View</a>, a single toolbar will be available to save space and it acts on the active note.</p><p>The sequence of dots to the left of the current paragraph is still shown, but only as a drag handle: drag it to move the paragraph, all the selected paragraphs, or a selected element such as an image, a table or an included note to another place in the note. Releasing it above the first paragraph or below the last one moves it to the start or the end of the note. Clicking it does not open a popup, and right-clicking it copies a reference to the block, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>. The drag handle is not shown in the mobile layout.</p><figure class=\"image\"><img style=\"aspect-ratio:1440/60;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Formatting%20toolbar_image.png\" width=\"1440\" height=\"60\"></figure><p>By default, if the toolbar does not fit on the screen, the rest of the options will be grouped into a single option at the end. It is possible to display items on multiple lines by checking the corresponding option in the <em>Formatting toolbar</em> section.</p>",
+ "_help_nRhnJkTT8cPs": "<p>Trilium allows two different editing experiences for text notes, based on your preference.</p><p>The type of formatting toolbar can be changed by going to&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;and then looking for the&nbsp;<a class=\"reference-link\" href=\"#root/_hidden/_options/_optionsTextNotes\">Text Notes</a>&nbsp;section. In it, look for the <em>Formatting toolbar</em> category.</p><h2>Floating</h2><p>The floating bar is a more minimalist option, in which the formatting is hidden behind two different popups.</p><h3>Block-level popup</h3><p>The first popup is the block-level popup. This will appear to the left of the current paragraph you are currently editing, as a sequence of dots:<br><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Formatting%20toolbar_image.jpg\"></p><p>Clicking this popup will reveal the formatting options that are specific to the entire paragraph, such as setting a heading, lists, tables, etc.</p><p>The dots are also a drag handle: drag them to move the paragraph, all the selected paragraphs, or a selected element such as an image, a table or an included note to another place in the note. Right-clicking them copies a reference to the paragraph or to the selected paragraphs, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>.</p><figure class=\"image\"><img style=\"aspect-ratio:1404/156;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/2_Formatting%20toolbar_image.png\" width=\"1404\" height=\"156\"></figure><h3>Inline popup</h3><p>The inline popup appears automatically when selecting a text:</p><figure class=\"image\"><img style=\"aspect-ratio:1008/154;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/1_Formatting%20toolbar_image.png\" width=\"1008\" height=\"154\"></figure><p>All the options here apply only to the selected portion of text, such as changing the font size, or making the text bold.</p><h2>Fixed</h2><p>The fixed formatting offers a more traditional editing paradigm, usually useful if a lot of formatting is needed.</p><p>All the options are combined into a single toolbar that will appear at the above the note. When using&nbsp;<a class=\"reference-link\" href=\"#root/_help_luNhaphA37EO\">Split View</a>, a single toolbar will be available to save space and it acts on the active note.</p><p>The sequence of dots to the left of the current paragraph is still shown, but only as a drag handle: drag it to move the paragraph, all the selected paragraphs, or a selected element such as an image, a table or an included note to another place in the note. Releasing it above the first paragraph or below the last one moves it to the start or the end of the note. Clicking it does not open a popup, and right-clicking it copies a reference to the block, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>. Hovering the drag handle shades the blocks that it moves: inside a table, this is the paragraph in the current cell, and with several cells selected, the whole table. The drag handle is not shown in the mobile layout.</p><figure class=\"image\"><img style=\"aspect-ratio:1440/60;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Formatting%20toolbar_image.png\" width=\"1440\" height=\"60\"></figure><p>By default, if the toolbar does not fit on the screen, the rest of the options will be grouped into a single option at the end. It is possible to display items on multiple lines by checking the corresponding option in the <em>Formatting toolbar</em> section.</p>",
"_help_Gr6xFaF6ioJ5": "<h2>Headings</h2><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:255/284;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/2_General%20formatting_image.png\" width=\"255\" height=\"284\"></figure><p>Trilium provides headings to define sections within text. Headings are numbered from 2 to 6.</p><p>The reason why Heading 1 is missing from the list is that it is being reserved for the title of note.</p><p>To turn a heading back into a normal text, select <em>Paragraph</em> from the list.</p><p>Apart from using the UI, it is also possible to quickly insert headings using the Markdown-like shortcuts:</p><ul><li><code>##</code> for Heading 2</li><li><code>###</code> for Heading 3</li><li><code>####</code> for Heading 4</li><li><code>#####</code> for Heading 5</li><li><code>######</code> for Heading 6</li></ul><h2>Font size</h2><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:363/249;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/General%20formatting_image.png\" width=\"363\" height=\"249\"></figure><p>One way to highlight a portion of text is to increase the size of the font.</p><p>To do so, select some text and choose an option from the <em>Font size</em> (<span class=\"tn-icon cke cke-font-size\"></span>) selector (as pictured to the right).</p><p>Unlike other text editors such as Microsoft Word, the font size is relative (i.e. “Tiny”, “Small” instead of a number like 12).</p><p>Avoid using this feature just to simply make all text bigger. In that case it's generally better to adjust the font size for all notes in&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;or by zooming.</p><h2>Bold, italic, underline, strike-through</h2><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:215/71;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/3_General%20formatting_image.png\" width=\"215\" height=\"71\"></figure><p>Text can be formatted as <strong>Bold,</strong> <em>Italic,</em> Underline or <del>Strike-through</del> via the dedicated buttons (<span class=\"tn-icon cke cke-bold\"></span>, <span class=\"tn-icon cke cke-italic\"></span>, <span class=\"tn-icon cke cke-underline\"></span>, <span class=\"tn-icon cke cke-strikethrough\"></span>) in the formatting toolbar.</p><p>This formatting can be easily removed using the <em>Remove formatting</em> (<span class=\"tn-icon cke cke-remove-format\"></span>) item.</p><p>The following keyboard shortcuts can be used here:</p><ul><li><kbd>Ctrl</kbd>+<kbd>B</kbd> for bold</li><li><kbd>Ctrl</kbd>+<kbd>I</kbd> for italic</li><li><kbd>Ctrl</kbd>+<kbd>U</kbd> for underline</li></ul><p>Alternatively, Markdown-like formatting can be used:</p><ul><li><strong>Bold</strong>: Type <code>**text**</code> or <code>__text__</code></li><li><em>Italic</em>: Type <code>*text*</code> or <code>_text_</code></li><li><del>Strikethrough</del>: Type <code>~~text~~</code></li></ul><h2>Superscript, subscript</h2><p>This allows writing superscript or subscript text.</p><p>This is mostly useful for units of measure (e.g. cm3 for cubic centimeters) and chemical notations (e.g. NaHCO3)</p><p>For mathematical formulas, prefer the&nbsp;<a class=\"reference-link\" href=\"#root/_help_YfYAtQBcfo5V\">Math Equations</a>&nbsp;feature instead.</p><h2>Font color and background color</h2><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:167/204;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/1_General%20formatting_image.png\" width=\"167\" height=\"204\"></figure><p>Selected text can be colored with one of the predefined colors from a palette or any color can be selected using the color picker (<span class=\"tn-icon cke cke-color-palette\"></span>).</p><p>Once there is at least one color defined in the document, it will appear in the list for easy reuse.</p><p>Colors adapt to the <a href=\"#root/_help_Wy267RK4M69c\">theme</a>. Trilium shows each color in a lighter or darker shade that suits the current theme, so the text stays readable after switching between light and dark themes. The hue stays the same: red text is red in both themes, only lighter or darker. This applies to the palette, the color picker and the document colors alike, and to shared notes too. Printed notes and PDF exports always use the shades of light themes, which suit white paper. The note itself keeps the color as it was picked, so an exported note shows it unchanged.</p><p>Colors applied with older versions of Trilium are shown exactly as they were picked, until the note is next edited.</p><p>Older browsers that can't adapt colors show them exactly as they were picked.</p><p>When you paste text copied from a web page in Chrome, Edge or a Chromium-based app (such as Visual Studio Code), Trilium removes the page's styling:</p><ul><li>Text and background colors.</li><li>Fonts and font sizes.</li><li>Table borders, backgrounds and spacing.</li></ul><p>The following formatting is preserved:</p><ul><li>Bold, italic, underline and strikethrough.</li><li>Subscript and superscript.</li><li>Links, code and tables.</li></ul><p>Colors are preserved when pasting from Word, Google Docs or another note.</p><p>To remove either the background or foreground color of a text, select the corresponding formatting button (<span class=\"tn-icon cke cke-font-color\"></span> or <span class=\"tn-icon cke cke-font-background\"></span>) and press <em>Remove color</em> (<span class=\"tn-icon cke cke-eraser\"></span>) or use the <em>Remove formatting</em> (<span class=\"tn-icon cke cke-remove-format\"></span>) toolbar item.</p><h2>Remove formatting</h2><p>The&nbsp;<span class=\"tn-icon cke cke-remove-format\"></span> <em>Remove formatting</em> button is a quick way to eliminate the general formatting styling of a particular text.</p><p>Simply select the text and press the button to remove the formatting (bold, italic, colors, sizes, etc.). If the text does not have any removable formatting, the button will appear disabled.</p><p>Note that heading styles are not taken into consideration, these must be manually changed back to a paragraph according to the <em>Headings</em> section.</p><p>When pasting content that comes with undesired formatting, an alternative to pasting and then removing formatting is pasting as plain text via <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd>.</p><h2>Format painter</h2><p>The&nbsp;<a class=\"reference-link\" href=\"#root/_help_5wZallV2Qo1t\">Format Painter</a>&nbsp;allows users to copy the formatting of text (such as bold, italic, Strikethrough, etc.) and apply it to other parts of the document. It helps maintain consistent formatting and accelerates the creation of rich content.</p><h2>Support for Markdown</h2><p>When exported to&nbsp;<a class=\"reference-link\" href=\"#root/_help_Oau6X9rCuegd\">Markdown</a>, most of the general formatting is maintained such as headings, bold, italic, underline, etc.</p>",
"_help_AxshuNRegLAv": "<aside class=\"admonition note\"><p>This page has been relocated to&nbsp;<a class=\"reference-link\" href=\"#root/_help_2dcGDhp9WFKb\">Outline tab</a>.</p></aside>",
"_help_mT0HEkOsz6i1": "<p>Trilium supports storing and displaying images. Supported formats are PNG, JPEG, GIF, BMP, WebP, AVIF and SVG.</p><p>An image can be uploaded in the form of note's <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> or as a standalone <a href=\"#root/_help_kBrnXNG3Hplm\">note</a> placed into the <a href=\"#root/_help_kBrnXNG3Hplm\">note tree</a>. Its reference can be copied into a text note, in order to display it in the text itself.</p><h2>Uploading images</h2><p>To add an image to the note:</p><ul><li>Simply drag it from file explorer onto the note editor inside Trilium and the image will be uploaded.</li><li>Alternatively, in the&nbsp;<a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>, press the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button and select <em>Image</em>.</li><li>On the&nbsp;<a class=\"reference-link\" href=\"#root/_help_RDslemsQ6gCp\">Mobile Frontend</a>, the same menu also offers <em>Camera</em>, which takes a photo and inserts it.</li><li>You can also copy and paste an image from web (see section below).</li></ul><aside class=\"admonition tip\"><p>To link a picture instead of displaying it, attach it with <em>Attach file as a link</em>, from the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button. See&nbsp;<a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>.</p></aside><h2>Clipboard &amp; automatic download of images</h2><p>Trilium has a special handling for images copied to and pasted from the clipboard.</p><ul><li>For a mix of text and images, the images are downloaded automatically by the server (or desktop app, depending on what is being used).<ul><li>This means that the image must be publicly accessible and reachable from wherever Trilium is running. Inaccessible images will end up as broken images.</li></ul></li><li>If a single image is pasted into Trilium, it will prefer the image that comes in the clipboard. This makes it possible to copy images that Trilium would not otherwise be able to reach, such as Google Chat, Slack, etc.</li><li>When a text with images is copied from Trilium and pasted in another app (such as Microsoft Word or LibreOffice Writer), the images will be preserved.</li></ul><p>The automatic download of images is enabled by default and can be toggled from&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;→ <em>Media</em> → <em>Download images automatically.</em></p><h2>Configuring the images</h2><p>Clicking on an image will reveal a popup with multiple options:<br><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Images_image.png\"></p><h3>Alignment</h3><p>The first button of the popup, <em>Image position</em>, shows the icon of the image's current position. It opens a menu that groups the positions by how text runs around the image:</p><figure class=\"table\"><table><thead><tr><th>Icon</th><th>Option</th><th>Preview</th><th>Description</th></tr></thead><tbody><tr><td><span class=\"tn-icon cke cke-object-inline\"></span></td><td><em>In line</em></td><td><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Images_image.jpg\"></td><td>The image sits inside a paragraph, like a large character, and moves with the text around it. Use drag &amp; drop or cut-paste to move it around.</td></tr><tr><td><span class=\"tn-icon cke cke-object-center\"></span></td><td><em>Break text</em> → <em>Align left</em>, <em>Align center</em> or <em>Align right</em></td><td><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/1_Images_image.jpg\"> <img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/2_Images_image.jpg\"></td><td>The image is displayed on a line of its own, at the left, in the center or at the right; text continues above and below it but not beside it.</td></tr><tr><td><span class=\"tn-icon cke cke-object-inline-right\"></span></td><td><em>Wrap text</em> → <em>Align left</em> or <em>Align right</em></td><td><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/3_Images_image.jpg\"></td><td>The image is displayed at the left or the right, and the text flows beside it.</td></tr></tbody></table></figure><h3>Drawing over an image</h3><p>To draw or write over an image, press the <span class=\"tn-icon bx bxs-pen\"></span> <em>Convert image to a drawing canvas</em> button of its toolbar. The image becomes a drawing canvas that shows all of it, locked in place. See the drawing canvases section of <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>.</p><h2>Compression</h2><p>Since Trilium isn't really meant to be primary storage for image data, it attempts to compress and resize (with pretty aggressive settings) uploaded images before storing them to the database. You may then notice some quality degradation. Basic quality settings is available in&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;→ <em>Media</em>.</p><p>If you want to save images in their original resolution, it is recommended to save them as attachment to note (look for the contextual menu in&nbsp;<a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>&nbsp;→ <em>Import files</em>).</p><h2>Aligning images side-by-side</h2><p>There are generally two ways to display images side by side:</p><ul><li>If they are roughly the same size, simply make the two images in-line, according to the alignment section above. The images can be dragged &amp; dropped onto the same line.</li><li>If they are on different size, create a <a href=\"#root/_help_NdowYOC1GFKS\">table</a> with invisible borders.</li></ul>",
diff --git a/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md b/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md
index c153a228a0..00b2596eb9 100644
--- a/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md
+++ b/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md
@@ -32,7 +32,7 @@ The fixed formatting offers a more traditional editing paradigm, usually useful
All the options are combined into a single toolbar that will appear at the above the note. When using <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Split%20View.md">Split View</a>, a single toolbar will be available to save space and it acts on the active note.
-The sequence of dots to the left of the current paragraph is still shown, but only as a drag handle: drag it to move the paragraph, all the selected paragraphs, or a selected element such as an image, a table or an included note to another place in the note. Releasing it above the first paragraph or below the last one moves it to the start or the end of the note. Clicking it does not open a popup, and right-clicking it copies a reference to the block, see <a class="reference-link" href="Block%20references.md">Block references</a>. The drag handle is not shown in the mobile layout.
+The sequence of dots to the left of the current paragraph is still shown, but only as a drag handle: drag it to move the paragraph, all the selected paragraphs, or a selected element such as an image, a table or an included note to another place in the note. Releasing it above the first paragraph or below the last one moves it to the start or the end of the note. Clicking it does not open a popup, and right-clicking it copies a reference to the block, see <a class="reference-link" href="Block%20references.md">Block references</a>. Hovering the drag handle shades the blocks that it moves: inside a table, this is the paragraph in the current cell, and with several cells selected, the whole table. The drag handle is not shown in the mobile layout.
<figure class="image"><img style="aspect-ratio:1440/60;" src="Formatting toolbar_image.png" width="1440" height="60"></figure>
diff --git a/packages/ckeditor5/src/plugins/block_drag_handle.spec.ts b/packages/ckeditor5/src/plugins/block_drag_handle.spec.ts
index f1966f2c0d..3e10d453c9 100644
--- a/packages/ckeditor5/src/plugins/block_drag_handle.spec.ts
+++ b/packages/ckeditor5/src/plugins/block_drag_handle.spec.ts
@@ -43,6 +43,11 @@ describe("BlockDragHandle", () => {
+ "<paragraph>cell</paragraph></tableCell></tableRow>"
+ "<caption>Cap[]tion</caption></table>");
expect(buttonView?.isVisible).toBe(false);
+ const captionStart = new DragEvent("dragstart", {
+ bubbles: true, cancelable: true, dataTransfer: new DataTransfer()
+ });
+ button.dispatchEvent(captionStart);
+ expect(captionStart.defaultPrevented).toBe(true);
getEditable(editor).blur();
await expect.poll(() => buttonView?.isVisible).toBe(false);
@@ -169,6 +174,96 @@ describe("BlockDragHandle", () => {
}
});
+ it("drags the whole table from a selection of several cells", async () => {
+ const cells = "<tableCell><paragraph>a</paragraph></tableCell>"
+ + "<tableCell><paragraph>b</paragraph></tableCell>";
+ const { editor, button } = await createEditor(
+ "<table><tableRow>[<tableCell><paragraph>a</paragraph></tableCell>]"
+ + "[<tableCell><paragraph>b</paragraph></tableCell>]</tableRow></table>"
+ + "<paragraph>after</paragraph>"
+ );
+
+ drop(button, startDrag(button), {
+ clientX: getEditable(editor).getBoundingClientRect().left - 50,
+ clientY: getBlock(editor, 1).getBoundingClientRect().bottom - 2
+ });
+ expect(getModelData(editor.model, { withoutSelection: true })).toBe(
+ `<paragraph>after</paragraph><table><tableRow>${cells}</tableRow></table>`
+ );
+ });
+
+ it("tints the blocks that it drags while the pointer is over it", async () => {
+ const note = (content: string) => `<aside admonitionType="note">${content}</aside>`;
+ const cell = (text: string) => `<tableCell><paragraph>${text}</paragraph></tableCell>`;
+ const cases = [ {
+ modelData: "<paragraph>one</paragraph><paragraph>tw[]o</paragraph>",
+ targets: [ "p:two" ]
+ }, {
+ modelData: `${note("<paragraph>on[e</paragraph>")}<paragraph>tw]o</paragraph>`,
+ targets: [ "aside:one", "p:two" ]
+ }, {
+ modelData: `<table><tableRow>${cell("a[]")}${cell("b")}</tableRow></table>`,
+ targets: [ "span:a" ]
+ }, {
+ modelData: `<table><tableRow>[${cell("a")}][${cell("b")}]</tableRow></table>`,
+ targets: [ "figure:ab" ]
+ }, {
+ modelData: `<paragraph>[a]</paragraph><table><tableRow>[${cell("b")}]</tableRow></table>`,
+ targets: [ "p:a", "figure:b" ]
+ }, {
+ modelData: `<table><tableRow>[${cell("a")}]</tableRow></table><paragraph>[b]</paragraph>`,
+ targets: [ "figure:a", "p:b" ]
+ } ];
+ for (const { modelData, targets } of cases) {
+ const { editor, button } = await createEditor(
+ `${modelData}<paragraph>after</paragraph>`
+ );
+ // The editors of the earlier cases stay on the page until the test ends.
+ editor.ui.view.element?.scrollIntoView();
+
+ button.dispatchEvent(new MouseEvent("mouseenter"));
+ expect(getTargets(editor)).toEqual(targets);
+ button.dispatchEvent(new MouseEvent("mouseleave"));
+ expect(getTargets(editor)).toEqual([]);
+ }
+ });
+
+ it("keeps the tint until the pointer leaves the handle or drags the blocks", async () => {
+ const { editor, button } = await createEditor(
+ "<paragraph>one</paragraph><paragraph>tw[]o</paragraph>"
+ );
+ button.dispatchEvent(new MouseEvent("mouseenter"));
+ expect(getComputedStyle(getBlock(editor, 1)).boxShadow).toContain("inset");
+ expect(editor.getData()).toBe("<p>one</p><p>two</p>");
+
+ setModelData(editor.model, "<paragraph>o[]ne</paragraph><paragraph>two</paragraph>");
+ expect(getTargets(editor)).toEqual([ "p:one" ]);
+
+ editor.enableReadOnlyMode("spec");
+ expect(getTargets(editor)).toEqual([]);
+ editor.disableReadOnlyMode("spec");
+ expect(getTargets(editor)).toEqual([ "p:one" ]);
+
+ endDrag(button, startDrag(button), "none");
+ expect(getTargets(editor)).toEqual([]);
+ expect(getComputedStyle(getBlock(editor, 0)).boxShadow).toBe("none");
+ });
+
+ it("tints the blocks when the editor gets focus while it renders", async () => {
+ const { editor, button } = await createEditor("<paragraph>on[]e</paragraph>");
+ const view = editor.editing.view;
+ getEditable(editor).blur();
+ await expect.poll(() => editor.ui.focusTracker.isFocused).toBe(false);
+ await expect.poll(() => view.document.isFocused).toBe(false);
+ button.dispatchEvent(new MouseEvent("mouseenter"));
+ expect(getTargets(editor)).toEqual([]);
+
+ // The renderer focuses the editable of a focused view document.
+ view.document.isFocused = true;
+ view.forceRender();
+ expect(getTargets(editor)).toEqual([ "p:one" ]);
+ });
+
it("takes drops beside a narrow editor or far out in a wide margin", async () => {
const layouts = [
{ width: "90px", margin: "0 100px", distance: 10 },
@@ -470,6 +565,14 @@ function endDrag(button: HTMLElement, dataTransfer: DataTransfer, dropEffect: "n
button.dispatchEvent(new DragEvent("dragend", { bubbles: true, dataTransfer }));
}
+/** The tag and text of each element tinted as a target of the handle. */
+function getTargets(editor: ClassicEditor) {
+ return Array.from(
+ getEditable(editor).querySelectorAll(".block-drag-handle-target"),
+ (element) => `${element.localName}:${element.textContent}`
+ );
+}
+
function getEditable(editor: ClassicEditor) {
const editable = editor.ui.getEditableElement();
if (!editable) {
diff --git a/packages/ckeditor5/src/plugins/block_drag_handle.ts b/packages/ckeditor5/src/plugins/block_drag_handle.ts
index 1e73a724f0..168e93167f 100644
--- a/packages/ckeditor5/src/plugins/block_drag_handle.ts
+++ b/packages/ckeditor5/src/plugins/block_drag_handle.ts
@@ -1,9 +1,14 @@
import {
BlockButtonView, ClipboardObserver, DomEmitterMixin, DragDrop, env,
findClosestScrollableAncestor, IconDragIndicator, type Model, type ModelElement,
- ModelLiveRange, type ModelRange, Plugin, Rect
+ ModelLiveRange, type ModelRange, type ModelSchema, Plugin, Rect, type ViewElement
} from "ckeditor5";
+import "../theme/block_drag_handle.css";
+
+/** The class of the blocks that a drag from the hovered handle moves. */
+const TARGET_CLASS = "block-drag-handle-target";
+
/**
* The drag handle of `BlockToolbar` without the toolbar, for the fixed-toolbar editor: a grip
* beside the block at the selection that drags the selected blocks to another place in the note.
@@ -13,7 +18,9 @@ export default class BlockDragHandle extends Plugin {
buttonView?: BlockButtonView;
private isDragging = false;
+ private isHovered = false;
private isUpdateScheduled = false;
+ private targets: ViewElement[] = [];
private readonly domEmitter = new (DomEmitterMixin())();
static get pluginName() {
@@ -43,6 +50,14 @@ export default class BlockDragHandle extends Plugin {
on: {
dragstart: buttonView.bindTemplate.to((domEvent) => {
this.startDrag(domEvent as DragEvent);
+ }),
+ mouseenter: buttonView.bindTemplate.to(() => {
+ this.isHovered = true;
+ this.updateTargets();
+ }),
+ mouseleave: buttonView.bindTemplate.to(() => {
+ this.isHovered = false;
+ this.updateTargets();
})
}
});
@@ -99,6 +114,7 @@ export default class BlockDragHandle extends Plugin {
const target = this.getTarget();
if (!target) {
buttonView.isVisible = false;
+ this.updateTargets();
return;
}
@@ -112,6 +128,45 @@ export default class BlockDragHandle extends Plugin {
buttonView.isVisible = !!visibleRect
&& buttonCenter >= visibleRect.top
&& buttonCenter <= visibleRect.bottom;
+ this.updateTargets();
+ }
+
+ /** Tints the blocks that a drag moves while the pointer is over the visible handle. */
+ private updateTargets() {
+ const view = this.editor.editing.view;
+ // `view.change()` throws during rendering, and the `layoutChanged` after it updates again.
+ if (view.isRenderingInProgress) {
+ return;
+ }
+
+ const isShown = this.isHovered && !this.isDragging && !!this.buttonView?.isVisible;
+ const range = isShown ? getDraggedRange(this.editor.model) : null;
+ const targets = range ? this.toViewElements(range) : [];
+ const previous = this.targets;
+ if (targets.length === previous.length
+ && targets.every((target, index) => target === previous[index])) {
+ return;
+ }
+
+ // Set before the change, whose rendering calls `update()` again.
+ this.targets = targets;
+ view.change((writer) => {
+ for (const target of previous) {
+ writer.removeClass(TARGET_CLASS, target);
+ }
+ for (const target of targets) {
+ writer.addClass(TARGET_CLASS, target);
+ }
+ });
+ }
+
+ /** The editing view elements of the outermost nodes in `range`. */
+ private toViewElements(range: ModelRange) {
+ const mapper = this.editor.editing.mapper;
+ return Array.from(range.getItems({ shallow: true }))
+ .filter((item) => item.is("element"))
+ .map((element) => mapper.toViewElement(element))
+ .filter((element) => element !== undefined);
}
private getTarget(): BlockTarget | null {
@@ -163,27 +218,20 @@ export default class BlockDragHandle extends Plugin {
return buttonRect;
}
- /** Selects the whole selected blocks and starts a drag of them in the editing view. */
+ /** Selects the dragged blocks and starts a drag of them in the editing view. */
private startDrag(domEvent: DragEvent) {
const editor = this.editor;
- const model = editor.model;
const dragDrop = editor.plugins.get(DragDrop);
- const blocks = Array.from(model.document.selection.getSelectedBlocks(), getDraggedBlock);
- const firstBlock = blocks.at(0);
- // The outermost block that holds the last one, so that a collapsible moves whole even when
- // the selection ends in its body.
- const lastAncestors = blocks.at(-1)?.getAncestors({ includeSelf: true });
- const lastBlock = blocks.find((block) => lastAncestors?.includes(block));
- if (!dragDrop.isEnabled || !firstBlock || !lastBlock) {
+ const range = getDraggedRange(editor.model);
+ if (!dragDrop.isEnabled || !range) {
domEvent.preventDefault();
return;
}
- const range = widenToWholeContainers(model, model.createRange(
- model.createPositionBefore(firstBlock),
- model.createPositionAfter(lastBlock)
- ));
- model.change((writer) => writer.setSelection(range));
+ // The drag takes the pointer off the handle.
+ this.isHovered = false;
+ this.updateTargets();
+ editor.model.change((writer) => writer.setSelection(range));
this.isDragging = true;
editor.editing.view.focus();
@@ -262,11 +310,67 @@ function clamp(value: number, min: number, max: number) {
return Math.min(Math.max(value, min), max);
}
+/**
+ * The range that the handle drags: the selected blocks, widened over the limit elements and the
+ * containers that they cover whole.
+ */
+function getDraggedRange(model: Model) {
+ const blocks = Array.from(model.document.selection.getSelectedBlocks(), getDraggedBlock);
+ const firstBlock = blocks.at(0);
+ // The outermost block that holds the last one, so that a collapsible moves whole even when
+ // the selection ends in its body.
+ const lastAncestors = blocks.at(-1)?.getAncestors({ includeSelf: true });
+ const lastBlock = blocks.find((block) => lastAncestors?.includes(block));
+ if (!firstBlock || !lastBlock) {
+ return null;
+ }
+
+ const range = model.createRange(
+ model.createPositionBefore(firstBlock),
+ model.createPositionAfter(lastBlock)
+ );
+ return widenToWholeContainers(model, widenToCommonLimit(model, range));
+}
+
/** The block that the handle drags for `block`: the whole collapsible for its title. */
function getDraggedBlock(block: ModelElement) {
return block.is("element", "summary") ? block.parent as ModelElement : block;
}
+/**
+ * Widens each end of `range` that is in a different limit element than the other end, such as
+ * another table cell, over its outermost limit element. The selection post-fixer does the same.
+ */
+function widenToCommonLimit(model: Model, range: ModelRange) {
+ const schema = model.schema;
+ const startLimit = schema.getLimitElement(range.start);
+ const endLimit = schema.getLimitElement(range.end);
+ if (startLimit === endLimit) {
+ return range;
+ }
+
+ return model.createRange(
+ startLimit.is("rootElement")
+ ? range.start
+ : model.createPositionBefore(getOutermostLimit(schema, startLimit)),
+ endLimit.is("rootElement")
+ ? range.end
+ : model.createPositionAfter(getOutermostLimit(schema, endLimit))
+ );
+}
+
+/** The outermost limit element below the root that contains `element`, such as its table. */
+function getOutermostLimit(schema: ModelSchema, element: ModelElement) {
+ let outermost = element;
+ let parent = element.parent;
+ while (parent?.is("element") && !parent.is("rootElement") && schema.isLimit(parent)) {
+ outermost = parent;
+ parent = parent.parent;
+ }
+
+ return outermost;
+}
+
/**
* Widens `range` over each container whose content it covers whole, such as an admonition or a
* block quote, so that the drag moves the container instead of leaving it empty. Stops at limit
diff --git a/packages/ckeditor5/src/theme/block_drag_handle.css b/packages/ckeditor5/src/theme/block_drag_handle.css
new file mode 100644
index 0000000000..e144829bca
--- /dev/null
+++ b/packages/ckeditor5/src/theme/block_drag_handle.css
@@ -0,0 +1,9 @@
+:where(:root) {
+ --block-drag-handle-target-background:
+ color-mix(in srgb, var(--main-text-color, var(--ck-color-text)) 6%, transparent);
+}
+
+.ck-editor__editable .block-drag-handle-target {
+ /* An inset shadow tints the block over its own background. */
+ box-shadow: inset 0 0 0 100vmax var(--block-drag-handle-target-background);
+}