Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
client/text editor/content embed: add support for markdown
Adorian Doran898e691218a1
diff --git a/apps/client/src/menus/link_context_menu.spec.ts b/apps/client/src/menus/link_context_menu.spec.tsindex 553c24e986..9f39dc41a1 100644--- a/apps/client/src/menus/link_context_menu.spec.ts+++ b/apps/client/src/menus/link_context_menu.spec.ts@@ -599,6 +599,33 @@ describe("openContextMenu", () => {.toMatchObject({ title: "link_context_menu.editable", checked: false });});+ it("offers the display modes above the size, for content that has them", async () => {+ state = { ...state, displayMode: "source" };+ const items = await openOn(editable.querySelector("a"));++ expect(items.slice(6, 12)).toMatchObject([+ { kind: "separator" },+ { title: "display_mode.source", uiIcon: "bx bx-code", checked: true },+ { title: "display_mode.split", uiIcon: "bx bxs-dock-left", checked: false },+ { title: "display_mode.preview", uiIcon: "bx bx-show", checked: false },+ { kind: "separator" },+ { title: "link_context_menu.include_size" }+ ]);+ expect(items).toHaveLength(17);+ expect(pick(items[9]))+ .toEqual([ [ "contentEmbedDisplayMode", { value: "preview" } ] ]);++ // After Editable, which comes first.+ state = { ...state, isEditableToggleable: true };+ expect((await openOn(editable.querySelector("a"))).slice(7, 12)).toMatchObject([+ { title: "link_context_menu.editable" },+ { title: "display_mode.source" },+ { title: "display_mode.split" },+ { title: "display_mode.preview" },+ { kind: "separator" }+ ]);+ });+it("appends the commands of an embedded note, its conversion in a group of its own", async () => {embed().removeAttribute("data-attachment-id");embed().setAttribute("data-note-id", "n1");diff --git a/apps/client/src/menus/link_context_menu.ts b/apps/client/src/menus/link_context_menu.tsindex 0cf9e4a6cf..b4e5ed8d2b 100644--- a/apps/client/src/menus/link_context_menu.ts+++ b/apps/client/src/menus/link_context_menu.ts@@ -9,6 +9,7 @@ import froca from "../services/froca.js";import { t } from "../services/i18n.js";import type { ViewScope } from "../services/link.js";import utils, { escapeHtml, isMobile, isShare } from "../services/utils.js";+import { DISPLAY_MODE_OPTIONS } from "../widgets/type_widgets/helpers/split_editor_mode.js";import { getClosestNtxId } from "../widgets/widget_utils.js";import contextMenu, { type ContextMenuOptions, type MenuItem } from "./context_menu.js";import { submenuItem } from "./context_menu_utils.js";@@ -290,9 +291,19 @@ function getEmbedItems(embed: MenuEmbed): MenuItem<CommandNames>[] {checked: state.isEditable,handler: () => runEmbedCommand(embed, "toggleContentEmbedEditable")} ] : [];+ const displayModeItems = state.displayMode+ ? DISPLAY_MODE_OPTIONS.map(({ value, icon, titleKey }): MenuItem<CommandNames> => ({+ title: t(titleKey),+ uiIcon: icon,+ checked: value === state.displayMode,+ handler: () => runEmbedCommand(embed, "contentEmbedDisplayMode", { value })+ }))+ : [];return [...editableItems,+ ...displayModeItems,+ ...(displayModeItems.length ? [ { kind: "separator" } as const ] : []),submenuItem({title: t("link_context_menu.include_size"),uiIcon: "bx bx-expand-vertical"diff --git a/apps/client/src/services/content_renderer.spec.ts b/apps/client/src/services/content_renderer.spec.tsindex c93deb2626..9da9c30f17 100644--- a/apps/client/src/services/content_renderer.spec.ts+++ b/apps/client/src/services/content_renderer.spec.ts@@ -116,6 +116,14 @@ const textEmbedComponent = vi.fn((_props: any): VNode<any> =>h("span", { class: "mock-text-embed-marker" }));vi.mock("../widgets/type_widgets/text/TextEmbed", () => ({ default: textEmbedComponent }));+const markdownEmbedComponent = vi.fn((_props: any): VNode<any> =>+ h("span", { class: "mock-markdown-embed-marker" }));+const renderMarkdownHtml = vi.fn((source: string) => (source ? `<p>${source}</p>` : ""));+vi.mock("../widgets/type_widgets/markdown/MarkdownEmbed", () => ({+ default: markdownEmbedComponent,+ renderMarkdownHtml: (source: string) => renderMarkdownHtml(source)+}));+// `addHook` is a no-op here: sanitize_content.ts registers a DOMPurify hook at// module load (pulled in transitively), which would otherwise throw against this mock.vi.mock("dompurify", () => ({ default: { sanitize: (s: string) => s, addHook: () => {} } }));@@ -226,8 +234,10 @@ describe("getEmbedBoxSize", () => {buildNote({ title: "Clip", type: "file", mime: "video/mp4" }),buildAttachment({ role: "file", mime: "application/pdf" }),buildAttachment({ role: "image", mime: "image/png" }),- buildAttachment({ role: "file", mime: "application/vnd.excalidraw+json" })- ].map(getEmbedBoxSize)).toEqual(Array(9).fill("medium"));+ buildAttachment({ role: "file", mime: "application/vnd.excalidraw+json" }),+ buildAttachment({ role: "file", mime: "text/markdown" }),+ buildAttachment({ role: "file", mime: "text/plain", title: "readme.md" })+ ].map(getEmbedBoxSize)).toEqual(Array(11).fill("medium"));});it("shows an upload too large to highlight as a file", () => {@@ -240,10 +250,10 @@ describe("getEmbedBoxSize", () => {expect(["application/zip", "", "audio/mpeg", "application/json", "application/pdf","image/png", "video/mp4", "application/vnd.excalidraw+json", "text/plain",- "application/x-sql", "text/rtf"+ "application/x-sql", "text/rtf", "text/markdown"].map(getUploadBoxSize)).toEqual(["tiny", "tiny", "small", "full", "medium", "medium", "medium", "medium", "full",- "full", "medium"+ "full", "medium", "medium"]);});});@@ -449,6 +459,55 @@ describe("getRenderedContent editable code", () => {expect(noteEditor.subscribeSaveState).toHaveBeenCalledWith(listener);});+ it("mounts MarkdownEmbed for a Markdown note in an embed, saved by `noteEditor`", async () => {+ const note = buildNote({+ title: "Readme", type: "code", mime: "text/x-markdown", content: "saved"+ });+ const noteEditor = buildEditor();+ noteEditor.getUnsavedContent.mockReturnValue("unsaved");++ const { type, $renderedContent } = await getRenderedContent(note, {+ interactive: true, hasDisplayModes: true, noteEditor+ });++ expect(type).toBe("markdown");+ expect($renderedContent.find(".markdown-embed[data-interactive-mount]")+ .find(".mock-markdown-embed-marker").length).toBe(1);+ const props = markdownEmbedComponent.mock.calls[0][0];+ expect([ props.entity, props.content ]).toEqual([ note, "unsaved" ]);+ expect(props.preview.outerHTML)+ .toBe("<div class=\"ck-content markdown-preview\"><p>unsaved</p></div>");+ expect(postProcessRichContent).toHaveBeenCalledWith(note, expect.anything(),+ expect.objectContaining({ hasDisplayModes: true }));+ expect(renderToHtml).not.toHaveBeenCalled();+ const getContent = () => "edited";+ props.editor.scheduleSave(getContent);+ expect(noteEditor.scheduleSave).toHaveBeenCalledWith(note, getContent, undefined);++ // Other Markdown renders the same way, and none shows the children of the note.+ expect((await props.renderPreview("edited")).innerHTML).toBe("<p>edited</p>");+ expect(renderChildrenList).not.toHaveBeenCalled();+ await props.renderPreview("");+ expect(renderChildrenList).toHaveBeenCalledWith(expect.anything(), note, false);+ });++ it("mounts MarkdownEmbed read-only for a Markdown file in an embed that cannot save", async () => {+ const att = buildAttachment({ role: "file", mime: "text/plain", title: "readme.md" });+ att.getBlob = (async () => ({ content: "# A" })) as any;++ const { type } = await getRenderedContent(att, { interactive: true, hasDisplayModes: true });+ expect(type).toBe("markdown");+ const props = markdownEmbedComponent.mock.calls[0][0];+ expect([ props.entity, props.editor, props.content ]).toEqual([ att, undefined, "# A" ]);+ await props.renderPreview("");+ expect(renderChildrenList).not.toHaveBeenCalled();++ // Elsewhere, the rendering shows alone.+ await getRenderedContent(att, { interactive: true });+ expect(renderToHtml).toHaveBeenCalledWith("# A", "readme.md", expect.anything());+ expect(markdownEmbedComponent).toHaveBeenCalledOnce();+ });+it("mounts CodeEmbed for an interactive code file, saved by `attachmentEditor`", async () => {const att = buildAttachment({ role: "file", mime: "application/json" });att.getBlob = (async () => ({ content: "{}" })) as any;diff --git a/apps/client/src/services/content_renderer.ts b/apps/client/src/services/content_renderer.tsindex 97cc2cd403..a4951eb08f 100644--- a/apps/client/src/services/content_renderer.ts+++ b/apps/client/src/services/content_renderer.ts@@ -8,6 +8,7 @@ import {getNoteContentType,isAcceptedImageMime,isImageAttachmentRole,+ isMarkdownMime,normalizeMimeTypeForCKEditor,type TextRepresentationResponse} from "@triliumnext/commons";@@ -77,6 +78,11 @@ export interface RenderOptions {* in place of the language of its name.*/codeLanguage?: string;+ /**+ * Lets content that has a source and a rendering, such as Markdown, show either or both, as+ * the box of an embed picks. Without it, the rendering shows alone.+ */+ hasDisplayModes?: boolean;showTextRepresentation?: boolean;/*** If enabled, note types that have a richer live representation (currently only web views) are@@ -304,7 +310,8 @@ export const CONTENT_RENDERERS = {webView: () => import("../widgets/type_widgets/WebView"),llmChat: () => import("../widgets/type_widgets/llm_chat/ChatPreview"),editableText: () => import("../widgets/type_widgets/text/TextEmbed"),- editableCode: () => import("../widgets/type_widgets/code/CodeEmbed")+ editableCode: () => import("../widgets/type_widgets/code/CodeEmbed"),+ editableMarkdown: () => import("../widgets/type_widgets/markdown/MarkdownEmbed")};/**@@ -358,6 +365,11 @@ function isEditableBlockRange(content: string, block: string) {* the user sees in the Markdown note type's preview pane.*/async function renderMarkdown(note: FNote | FAttachment, $renderedContent: JQuery<HTMLElement>, options: RenderOptions) {+ if (options.hasDisplayModes) {+ await renderMarkdownEmbed(note, $renderedContent, options);+ return;+ }+const blob = await note.getBlob();const source = blob?.content ?? "";@@ -377,6 +389,57 @@ async function renderMarkdown(note: FNote | FAttachment, $renderedContent: JQuerawait postProcessRichContent(note, $renderedContent, options);}+/**+ * Renders a Markdown note or file in the box of an embed, which `MarkdownEmbed` shows as the split+ * editor of a Markdown note does: the source, the rendering or both. An editor that can save the+ * changes lets the source be edited.+ */+async function renderMarkdownEmbed(+ entity: FNote | FAttachment,+ $renderedContent: JQuery<HTMLElement>,+ options: RenderOptions+) {+ const editor = getContentEditor(entity, options);+ const content = editor?.getUnsavedContent() ?? (await entity.getBlob())?.content ?? "";+ const { default: MarkdownEmbed, renderMarkdownHtml } =+ await CONTENT_RENDERERS.editableMarkdown();+ const renderPreview = (source: string) =>+ renderMarkdownPreview(entity, renderMarkdownHtml(source), options);+ const preview = await renderPreview(content);++ const $container = $('<div class="markdown-embed">');+ const container = $container.get(0);+ if (container) {+ await mountInteractiveWidget(+ h(MarkdownEmbed, { entity, editor, content, preview, renderPreview }),+ container+ );+ }+ $renderedContent.append($container);+}++/**+ * The rendering of `html`, the Markdown of `entity` as HTML, as the preview of a Markdown note+ * shows it. Empty Markdown shows the children of a note instead.+ */+async function renderMarkdownPreview(+ entity: FNote | FAttachment,+ html: string,+ options: RenderOptions+) {+ if (!html) {+ const $children = $("<div>");+ if (entity instanceof FNote && !options.noChildrenList) {+ await renderChildrenList($children, entity, options.includeArchivedNotes ?? false);+ }+ return $children[0];+ }++ const $preview = $('<div class="ck-content markdown-preview">').html(html);+ await postProcessRichContent(entity, $preview, options);+ return $preview[0];+}+/*** Renders an icon pack as its glyph grid (the same isolated-frame preview used by the editor),* mounted like the PDF viewer. Its own module keeps the editor stack (SplitEditor/CodeMirror) out@@ -1059,20 +1122,24 @@ function getContentType(entity: FNote | FAttachment) {return "image";}return entity.role === "file"- ? getAttachedFileContentType(entity.mime, entity.contentLength)+ ? getAttachedFileContentType(entity.mime, entity.contentLength, entity.title): getFileContentType(entity.role, entity.mime);}/*** The kind of file an attachment holds, which is code for text and the code media types up to- * `MAX_ATTACHED_CODE_SIZE`.+ * `MAX_ATTACHED_CODE_SIZE`, and Markdown for code that its name, or else its media type, marks+ * as Markdown.*/-function getAttachedFileContentType(mime: string, size = 0) {+function getAttachedFileContentType(mime: string, size = 0, fileName?: string) {const type = getFileContentType("file", mime);const isCode = type === "code"|| (type === "file" && (mime.startsWith("text/") || ATTACHED_CODE_MIME_TYPES.has(mime)));if (!isCode) return type;- return size <= MAX_ATTACHED_CODE_SIZE ? "code" : "file";+ if (size > MAX_ATTACHED_CODE_SIZE) return "file";++ const codeMime = (fileName && getMimeTypeFromFileName(fileName)) || mime;+ return isMarkdownMime(codeMime) ? "markdown" : "code";}export default {diff --git a/apps/client/src/stylesheets/style.css b/apps/client/src/stylesheets/style.cssindex a5ea9e24ea..c3c7ceb742 100644--- a/apps/client/src/stylesheets/style.css+++ b/apps/client/src/stylesheets/style.css@@ -1232,6 +1232,15 @@ body.mobile .modal-content-with-sidebar > .modal-main > .modal-header > .modal-tflex-shrink: 0;}+.include-note-title-row > .include-note-display-modes {+ flex-shrink: 0;+}++/* Outranks `:root div.btn-group .icon-action`, so the group is as tall as the other buttons. */+:root .include-note-title-row > .include-note-display-modes .icon-action {+ --icon-button-size: 24px;+}+/* Browsers drop a click on a disabled button, which then toggles no expandable embed. */.include-note-title-row > .icon-action.disabled {pointer-events: auto;diff --git a/apps/client/src/widgets/layout/NoteActionsCustom.tsx b/apps/client/src/widgets/layout/NoteActionsCustom.tsxindex 0665c595ad..3d591c18af 100644--- a/apps/client/src/widgets/layout/NoteActionsCustom.tsx+++ b/apps/client/src/widgets/layout/NoteActionsCustom.tsx@@ -23,7 +23,7 @@ import { FormFileUploadActionButton, FormFileUploadFormListItem, FormFileUploadPimport { FormListItem } from "../react/FormList";import { openHelpPageFor } from "../react/HelpButton";import { useEffectiveReadOnly, useNoteLabel, useNoteLabelBoolean, useNoteProperty, useTriliumEvent, useTriliumEvents, useTriliumOption } from "../react/hooks";-import { isSplitEditorForcedReadOnly, resolveDisplayMode } from "../type_widgets/helpers/split_editor_mode";+import { DISPLAY_MODE_OPTIONS, isSplitEditorForcedReadOnly, resolveDisplayMode } from "../type_widgets/helpers/split_editor_mode";import { ParentComponent } from "../react/react_utils";interface NoteActionsCustomProps {@@ -267,11 +267,9 @@ function DisplayModeSwitcher({ note, noteContext, isDefaultViewMode }: NoteActio// Mirror SplitEditor's mode resolution so the active button matches the actual pane.const mode = resolveDisplayMode(displayMode, readOnly || isSplitEditorForcedReadOnly(note));- const buttons: Array<{ value: "source" | "split" | "preview"; icon: string; text: string }> = [- { value: "source", icon: "bx bx-code", text: t("display_mode.source") },- { value: "split", icon: "bx bxs-dock-left", text: t("display_mode.split") },- { value: "preview", icon: "bx bx-show", text: t("display_mode.preview") }- ];+ const buttons = DISPLAY_MODE_OPTIONS.map(({ value, icon, titleKey }) => ({+ value, icon, text: t(titleKey)+ }));if (cachedIsMobile) {return (diff --git a/apps/client/src/widgets/type_widgets/code/CodeEmbed.tsx b/apps/client/src/widgets/type_widgets/code/CodeEmbed.tsxindex c2582d4094..d20c8827e6 100644--- a/apps/client/src/widgets/type_widgets/code/CodeEmbed.tsx+++ b/apps/client/src/widgets/type_widgets/code/CodeEmbed.tsx@@ -171,7 +171,7 @@ interface SaveStatusProps {* The save state of `editor` in the title row of the embed around `rootRef`, while `isShown`, for* content that saves on its own.*/-function SaveStatus({ rootRef, editor, isShown }: SaveStatusProps) {+export function SaveStatus({ rootRef, editor, isShown }: SaveStatusProps) {const slot = useEmbedBadgeSlot(rootRef, isShown);const state = useSyncExternalStore(editor.subscribeSaveState ?? subscribeToNothing,@@ -185,9 +185,9 @@ function SaveStatus({ rootRef, editor, isShown }: SaveStatusProps) {* Shows the content of `entity` each time it saves, also when another embed of it saved it.* Unsaved changes made in the embed are kept, and replace that content when they save.*/-function useSavedContent(+export function useSavedContent(entity: FNote | FAttachment,- editor: ContentEditor,+ editor: ContentEditor | undefined,setContent: (content: string) => void) {const noteBlob = useNoteBlob(entity instanceof FNote ? entity : null);@@ -209,7 +209,7 @@ function useSavedContent(});useEffect(() => {- if (content !== undefined && editor.getUnsavedContent() === undefined) {+ if (content !== undefined && editor?.getUnsavedContent() === undefined) {setContent(content);}}, [ content ]);diff --git a/apps/client/src/widgets/type_widgets/code/CodeEmbedEditor.tsx b/apps/client/src/widgets/type_widgets/code/CodeEmbedEditor.tsxindex 0b9150be91..54b7545f3f 100644--- a/apps/client/src/widgets/type_widgets/code/CodeEmbedEditor.tsx+++ b/apps/client/src/widgets/type_widgets/code/CodeEmbedEditor.tsx@@ -12,7 +12,8 @@ import { CodeEditor } from "./Code";export interface CodeEmbedEditorProps {note: FNote | null;- editor: ContentEditor;+ /** Saves the edits, or `undefined` to show the content read-only. */+ editor: ContentEditor | undefined;content: string;mime: string;/** The tab width, or `undefined` to follow the global option. */@@ -23,11 +24,18 @@ export interface CodeEmbedEditorProps {viewRef: RefObject<VanillaCodeMirror | null>;/** Receives the edited content when the editor goes away. */onClose: (content: string) => void;+ /** Receives the content as it is edited. */+ onChange?: (content: string) => void;+ /** Called with CodeMirror once it mounts, for extensions such as a linter. */+ onReady?: (view: VanillaCodeMirror) => void;}-/** CodeMirror over the content of a code embed, which `editor` saves as it changes. */+/**+ * CodeMirror over the content of a code embed, which `editor` saves as it changes. Without an+ * `editor`, the content is read-only.+ */export default function CodeEmbedEditor({- note, editor, content, mime, tabWidth, useTabs, viewRef, onClose+ note, editor, content, mime, tabWidth, useTabs, viewRef, onClose, onChange, onReady}: CodeEmbedEditorProps) {const isLoadingRef = useRef(false);const [ vimKeymapEnabled ] = useTriliumOptionBool("vimKeymapEnabled");@@ -39,6 +47,7 @@ export default function CodeEmbedEditor({const view = viewRef.current;if (!view) return;+ onReady?.(view);return registerEmbedFindTarget(view.dom, new CodeMirrorFindTarget(view));}, []);@@ -58,6 +67,8 @@ export default function CodeEmbedEditor({useLayoutEffect(() => () => {const text = viewRef.current?.getText();viewRef.current = null;+ if (!editor) return;+editor.release();if (text !== undefined) {onClose(text);@@ -71,9 +82,11 @@ export default function CodeEmbedEditor({className="code-embed-editor"mime={mime}vimKeybindings={vimKeymapEnabled}+ readOnly={!editor}onContentChanged={() => {- if (!isLoadingRef.current) {+ if (editor && !isLoadingRef.current) {editor.scheduleSave(() => viewRef.current?.getText() ?? "");+ onChange?.(viewRef.current?.getText() ?? "");}}}{...(tabWidth !== undefined && { indentSize: tabWidth })}diff --git a/apps/client/src/widgets/type_widgets/helpers/SplitEditor.tsx b/apps/client/src/widgets/type_widgets/helpers/SplitEditor.tsxindex 12fca12130..79bd64cbfc 100644--- a/apps/client/src/widgets/type_widgets/helpers/SplitEditor.tsx+++ b/apps/client/src/widgets/type_widgets/helpers/SplitEditor.tsx@@ -11,7 +11,7 @@ import { ExtendedAdmonition } from "../../react/Admonition";import { Badge } from "../../react/Badge";import { useEffectiveReadOnly, useNoteBlob, useNoteLabel, useTriliumOption } from "../../react/hooks";import { EditableCode, EditableCodeProps, ReadOnlyCode } from "../code/Code";-import { resolveDisplayMode } from "./split_editor_mode";+import { type DisplayMode, resolveDisplayMode } from "./split_editor_mode";export interface SplitEditorProps extends EditableCodeProps {className?: string;@@ -46,17 +46,11 @@ export interface SplitEditorProps extends EditableCodeProps {* - Horizontal or vertical orientation for the editor/preview split, adjustable via the switch split orientation button floating button.*/export default function SplitEditor({ note, noteContext, error, previewStale, splitOptions, previewContent, previewButtons, className, editorBefore, forceOrientation, forceReadOnly, editorContent, extraContent, ...editorProps }: SplitEditorProps) {- const containerRef = useRef<HTMLDivElement>(null);const splitEditorOrientation = useSplitOrientation(forceOrientation);const [ displayMode ] = useNoteLabel(note, "displayMode");const readOnly = useEffectiveReadOnly(note, noteContext) || Boolean(forceReadOnly);const mode = resolveDisplayMode(displayMode, readOnly);-- // Lazy-mount each pane on first need, then keep it mounted so subsequent switches stay instant.- const editorMounted = useRef(mode !== "preview");- const previewMounted = useRef(mode !== "source");- if (mode !== "preview") editorMounted.current = true;- if (mode !== "source") previewMounted.current = true;+ const { editorMounted, previewMounted } = useMountedPanes(mode);// The editor only feeds content to the preview when it's an `EditableCode`. `ReadOnlyCode`// doesn't expose `onContentChanged`, and in preview-only mode the editor isn't mounted at all —@@ -71,8 +65,8 @@ export default function SplitEditor({ note, noteContext, error, previewStale, sp}}, [ fallbackBlob, editorPropagatesContent ]);- const editor = editorMounted.current && (- <div className="note-detail-split-editor-col">+ const editor = (+ <>{editorBefore}<div className="note-detail-split-editor">{editorContent ?? (readOnly@@ -86,10 +80,55 @@ export default function SplitEditor({ note, noteContext, error, previewStale, sp/>)}</div>{extraContent}- </div>+ </>+ );++ return (+ <SplitLayout+ className={`note-detail-printable ${className ?? ""}`}+ mode={mode}+ orientation={splitEditorOrientation}+ splitOptions={splitOptions}+ editor={editor}+ isEditorMounted={editorMounted.current}+ isPreviewMounted={previewMounted.current}+ error={error}+ previewStale={previewStale}+ previewContent={previewContent}+ previewButtons={previewButtons}+ />+ );+}++export interface SplitLayoutProps {+ className?: string;+ mode: DisplayMode;+ orientation: "horizontal" | "vertical";+ splitOptions?: Split.Options;+ /** The content of the editor pane. */+ editor: ComponentChildren;+ /** Whether each pane is mounted, see {@link useMountedPanes}. */+ isEditorMounted: boolean;+ isPreviewMounted: boolean;+ error?: string | null;+ /** When the preview still shows a previous successful render despite the current {@link error}. */+ previewStale?: boolean;+ previewContent: ComponentChildren;+ previewButtons?: ComponentChildren;+}++/**+ * The editor and preview panes of a split editor, laid out for `mode`, and the render error over+ * the preview. The panes stay mounted across modes, which only toggle a CSS class.+ */+export function SplitLayout({ className, mode, orientation, splitOptions, editor, isEditorMounted, isPreviewMounted, error, previewStale, previewContent, previewButtons }: SplitLayoutProps) {+ const containerRef = useRef<HTMLDivElement>(null);++ const editorCol = isEditorMounted && (+ <div className="note-detail-split-editor-col">{editor}</div>);- const preview = previewMounted.current && <PreviewContainer+ const previewCol = isPreviewMounted && <PreviewContainererror={error}previewStale={previewStale}previewContent={previewContent}@@ -103,27 +142,39 @@ export default function SplitEditor({ note, noteContext, error, previewStale, spconst splitInstance = Split(elements, {rtl: glob.isRtl,sizes: [ 50, 50 ],- direction: splitEditorOrientation,+ direction: orientation,gutterSize: DEFAULT_GUTTER_SIZE,...splitOptions});return () => splitInstance.destroy();- }, [ splitEditorOrientation, mode ]);+ }, [ orientation, mode ]);const layoutClass = mode === "source" ? "split-source-only": mode === "preview" ? "split-read-only"- : `split-${splitEditorOrientation}`;+ : `split-${orientation}`;return (- <div ref={containerRef} className={`note-detail-split note-detail-printable ${layoutClass} ${className ?? ""}`}>- {splitEditorOrientation === "horizontal"- ? <>{editor}{preview}</>- : <>{preview}{editor}</>}+ <div ref={containerRef} className={`note-detail-split ${layoutClass} ${className ?? ""}`}>+ {orientation === "horizontal"+ ? <>{editorCol}{previewCol}</>+ : <>{previewCol}{editorCol}</>}</div>);}+/**+ * Which panes of a split editor are mounted: each from the first `mode` that shows it, so that+ * switching back stays instant.+ */+export function useMountedPanes(mode: DisplayMode) {+ const editorMounted = useRef(mode !== "preview");+ const previewMounted = useRef(mode !== "source");+ if (mode !== "preview") editorMounted.current = true;+ if (mode !== "source") previewMounted.current = true;+ return { editorMounted, previewMounted };+}+function PreviewContainer({ error, previewStale, previewContent, previewButtons }: {error?: string | null;previewStale?: boolean;diff --git a/apps/client/src/widgets/type_widgets/helpers/split_editor_mode.ts b/apps/client/src/widgets/type_widgets/helpers/split_editor_mode.tsindex 4a201c7d76..d67ea3fae4 100644--- a/apps/client/src/widgets/type_widgets/helpers/split_editor_mode.ts+++ b/apps/client/src/widgets/type_widgets/helpers/split_editor_mode.ts@@ -2,6 +2,13 @@ import type FNote from "../../../entities/fnote";export type DisplayMode = "source" | "split" | "preview";+/** The display modes, in the order their switchers show them, with the icon and label of each. */+export const DISPLAY_MODE_OPTIONS = [+ { value: "source", icon: "bx bx-code", titleKey: "display_mode.source" },+ { value: "split", icon: "bx bxs-dock-left", titleKey: "display_mode.split" },+ { value: "preview", icon: "bx bx-show", titleKey: "display_mode.preview" }+] as const satisfies readonly { value: DisplayMode; icon: string; titleKey: string }[];+/*** Resolves the active split-editor mode from the `#displayMode` label. When the label is unset it* falls back to the note's read-only state — read-only → `preview`, editable → `split`. Kept as adiff --git a/apps/client/src/widgets/type_widgets/markdown/Markdown.css b/apps/client/src/widgets/type_widgets/markdown/Markdown.cssindex 37b0a4e40c..ace5b8f8bd 100644--- a/apps/client/src/widgets/type_widgets/markdown/Markdown.css+++ b/apps/client/src/widgets/type_widgets/markdown/Markdown.css@@ -1,4 +1,4 @@-.note-detail-markdown {+:is(.note-detail-markdown, .markdown-embed-content) {.note-detail-code-editor {margin-top: 0 !important;diff --git a/apps/client/src/widgets/type_widgets/markdown/Markdown.tsx b/apps/client/src/widgets/type_widgets/markdown/Markdown.tsxindex 8f01f3574d..67d615b27b 100644--- a/apps/client/src/widgets/type_widgets/markdown/Markdown.tsx+++ b/apps/client/src/widgets/type_widgets/markdown/Markdown.tsx@@ -251,7 +251,7 @@ function usePublishHighlights(* preview so the block tagged with that line is at the top — interpolating to* the next block for smoothness.*/-function useSyncedScrolling(view: VanillaCodeMirror | null, preview: HTMLDivElement | null) {+export function useSyncedScrolling(view: VanillaCodeMirror | null, preview: HTMLDivElement | null) {useEffect(() => {if (!view || !preview) return;@@ -300,7 +300,7 @@ function useSyncedScrolling(view: VanillaCodeMirror | null, preview: HTMLDivElem* be measured here. Every block is observed for resize, since a block that grows after render —* a mermaid diagram, an image, an embedded note — shifts everything below it.*/-function useSyncedHighlight(view: VanillaCodeMirror | null, preview: HTMLDivElement | null, html: string) {+export function useSyncedHighlight(view: VanillaCodeMirror | null, preview: HTMLDivElement | null, html: string) {useEffect(() => {if (!view || !preview) return;@@ -475,7 +475,7 @@ function useTextCommands(parentComponent: TypeWidgetProps["parentComponent"], ed* Draws the `[[noteId]]` links as chips with the note's icon and title, as the search field draws* its note ids, showing a link's text while the selection touches it so it stays editable.*/-function useNoteLinkChips(editorView: VanillaCodeMirror | null) {+export function useNoteLinkChips(editorView: VanillaCodeMirror | null) {useEffect(() => {if (!editorView) return;@@ -487,7 +487,7 @@ function useNoteLinkChips(editorView: VanillaCodeMirror | null) {}, [editorView]);}-function useMarkdownKeymap(editorView: VanillaCodeMirror | null) {+export function useMarkdownKeymap(editorView: VanillaCodeMirror | null) {useEffect(() => {if (!editorView) return;diff --git a/apps/client/src/widgets/type_widgets/markdown/MarkdownCommons.css b/apps/client/src/widgets/type_widgets/markdown/MarkdownCommons.cssindex 738bad68d6..8c55e6dff8 100644--- a/apps/client/src/widgets/type_widgets/markdown/MarkdownCommons.css+++ b/apps/client/src/widgets/type_widgets/markdown/MarkdownCommons.css@@ -1,4 +1,4 @@-.note-detail-markdown .markdown-preview,+:is(.note-detail-markdown, .markdown-embed-content) .markdown-preview,.note-detail-readonly-text-content.llm-chat-markdown {table {diff --git a/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.css b/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.cssnew file mode 100644index 0000000000..10cfeb08a4--- /dev/null+++ b/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.css@@ -0,0 +1,60 @@+.include-note-content:has(+ > .rendered-content > .markdown-embed > .markdown-embed-content.with-source+) {+ padding: 0;+ box-sizing: content-box;+ max-height: none;+}++.markdown-embed-content {+ text-align: start;++ &.with-source {+ height: var(--include-note-height, 20em);+ }++ .editable-embed-preview {+ height: 100%;+ }++ &:not(.with-source) .markdown-preview {+ padding: 0;+ height: auto;+ overflow: visible;+ background-image: none;+ }+}++.include-note {+ &[data-box-size="small"] .markdown-embed-content.with-source {+ height: var(--include-note-height, 10em);+ }++ &[data-box-size="full"] .markdown-embed-content.with-source {+ height: 50em;+ }+}++.include-note-content:fullscreen :is(.markdown-embed, .markdown-embed-content.with-source) {+ height: 100%;+}++.include-note {+ /* The corners of the embed box that the split editor touches. */+ --_markdown-embed-top-radius: 0;+ --_markdown-embed-bottom-radius: var(--_include-note-bottom-border-radius, 8px);++ &[data-hide-title="true"]:not([data-box-size="tiny"], [data-box-size="expandable"]) {+ --_markdown-embed-top-radius: var(--_include-note-top-border-radius, 8px);+ }++ &:has(> figcaption) {+ --_markdown-embed-bottom-radius: 0;+ }+}++.include-note-content:not(:fullscreen) .markdown-embed-content.with-source {+ border-radius: var(--_markdown-embed-top-radius) var(--_markdown-embed-top-radius)+ var(--_markdown-embed-bottom-radius) var(--_markdown-embed-bottom-radius);+ overflow: hidden;+}diff --git a/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.spec.tsx b/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.spec.tsxnew file mode 100644index 0000000000..36ac508604--- /dev/null+++ b/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.spec.tsx@@ -0,0 +1,241 @@+import { render } from "preact";+import { act } from "preact/test-utils";+import { afterEach, describe, expect, it, vi } from "vitest";++import Component from "../../../components/component";+import type FNote from "../../../entities/fnote";+import type { ContentEditor } from "../../../services/content_renderer";+import options from "../../../services/options";+import { buildNote } from "../../../test/easy-froca";+import { CodeMirrorFindTarget } from "../../find_in_code";+import { ParentComponent } from "../../react/react_utils";+import {+ enterContentEmbed, getContentEmbedTools, getEmbedFindTarget+} from "../text/content_embed_tools";+import MarkdownEmbed from "./MarkdownEmbed";++vi.mock("../../../services/i18n", async (importOriginal) => ({+ ...(await importOriginal<object>()),+ t: (key: string) => key+}));++// `CodeEditor` reads the theme as a string.+options.set("codeNoteTheme", "");++const parent = new Component();+const figures: HTMLElement[] = [];++afterEach(() => {+ for (const figure of figures) {+ const box = figure.querySelector(".include-note-content");+ if (box) act(() => render(null, box));+ figure.remove();+ }+ figures.length = 0;+ vi.restoreAllMocks();+});++describe("MarkdownEmbed", () => {+ it("shows the preview, offers the display modes, and Editable where it can edit", async () => {+ const note = buildMarkdownNote("# Title");+ const preview = buildPreview("# Title");+ const { figure } = await mount(note, buildEditor(), { preview });+ expect(figure.querySelector(".editable-embed-preview")?.firstChild).toBe(preview);+ expect(figure.querySelector(".note-detail-split.split-read-only")).not.toBeNull();+ expect(figure.querySelector(".cm-editor")).toBeNull();+ expect(getContentEmbedTools(figure))+ .toMatchObject({ hasDisplayModes: true, hasEditableFlag: true });++ const readOnly = buildNote({+ title: "Fixed", type: "code", mime: "text/x-markdown", content: "", "#readOnly": ""+ });+ for (const [ entity, editor ] of [+ [ note, buildEditor({ canEdit: () => false }) ],+ [ note, undefined ],+ [ readOnly, buildEditor() ]+ ] as const) {+ const { figure: locked } = await mount(entity, editor);+ expect(getContentEmbedTools(locked))+ .toMatchObject({ hasDisplayModes: true, hasEditableFlag: false });+ }+ });++ it("shows the source read-only beside the preview, or alone, as the embed picks", async () => {+ const editor = buildEditor();+ const { figure } = await mount(buildMarkdownNote("a"), editor, {+ embedAttributes: { "data-display-mode": "split" }+ });+ const split = figure.querySelector(".note-detail-split");+ const view = await findView(figure);+ expect(view.state.doc.toString()).toBe("a");+ expect(view.state.readOnly).toBe(true);+ expect(split?.className).not.toMatch(/split-(read-only|source-only)/);+ expect(figure.querySelector(".editable-embed-preview")).not.toBeNull();++ await act(async () => {+ figure.dataset.displayMode = "source";+ await Promise.resolve();+ });+ expect(split?.classList.contains("split-source-only")).toBe(true);+ expect(figure.querySelector(".markdown-embed-content.with-source")).not.toBeNull();++ // Formatting shortcuts change only a source that is edited.+ pressCtrl(view, "b");+ expect(view.state.doc.toString()).toBe("a");+ expect(editor.scheduleSave).not.toHaveBeenCalled();+ });++ it("edits in split view while Editable is on, and previews the edits", async () => {+ const editor = buildEditor();+ const renderPreview = vi.fn(async (content: string) => buildPreview(content));+ const { figure } = await mount(buildMarkdownNote("a"), editor, {+ isEditable: true, renderPreview+ });+ const view = await findView(figure);+ expect(view.state.readOnly).toBe(false);+ expect(figure.querySelector(".editable-embed-preview")).not.toBeNull();++ act(() => view.dispatch({ changes: { from: 1, insert: "b" }, selection: { anchor: 2 } }));+ expect(editor.scheduleSave).toHaveBeenCalledOnce();+ expect(vi.mocked(editor.scheduleSave).mock.calls[0][0]()).toBe("ab");+ await vi.waitFor(() => {+ expect(figure.querySelector(".editable-embed-preview")?.textContent).toBe("ab");+ });+ expect(renderPreview).toHaveBeenLastCalledWith("ab");++ pressCtrl(view, "b");+ expect(view.state.doc.toString()).toBe("ab****");++ // Turning Editable off closes the editor, and shows the preview of the edits.+ await act(async () => {+ delete figure.dataset.editable;+ await Promise.resolve();+ });+ expect(editor.release).toHaveBeenCalledOnce();+ expect(figure.querySelector(".cm-editor")).toBeNull();+ expect(figure.querySelector(".note-detail-split.split-read-only")).not.toBeNull();+ });++ it("searches and takes the caret into the source only while it shows", async () => {+ const { figure } = await mount(buildMarkdownNote("a"), buildEditor(), {+ isEditable: true+ });+ const view = await findView(figure);+ expect(getEmbedFindTarget(figure)).toBeInstanceOf(CodeMirrorFindTarget);+ let isEntered = false;+ act(() => {+ isEntered = enterContentEmbed(figure, "end");+ });+ expect(isEntered).toBe(true);+ expect(view.hasFocus).toBe(true);++ await act(async () => {+ figure.dataset.displayMode = "preview";+ await Promise.resolve();+ });+ expect(figure.querySelector(".cm-editor")).toBeNull();+ expect(getEmbedFindTarget(figure)).toBeNull();+ expect(enterContentEmbed(figure, "start")).toBe(false);+ });+});++interface MountOptions {+ isEditable?: boolean;+ preview?: HTMLElement;+ renderPreview?: (content: string) => Promise<HTMLElement>;+ /** Attributes of the embed, such as `data-display-mode`. */+ embedAttributes?: Record<string, string>;+}++/** Renders `MarkdownEmbed` in the markup of an embed, as the host does. */+async function mount(+ entity: FNote,+ editor: ContentEditor | undefined,+ options: MountOptions = {}+) {+ const figure = document.createElement("figure");+ figure.className = "include-note";+ if (options.isEditable) {+ figure.dataset.editable = "true";+ }+ for (const [ name, value ] of Object.entries(options.embedAttributes ?? {})) {+ figure.setAttribute(name, value);+ }+ const wrapper = document.createElement("div");+ wrapper.className = "include-note-wrapper";+ const titleRow = document.createElement("div");+ titleRow.className = "include-note-title-row";+ const badges = document.createElement("div");+ badges.className = "include-note-badges";+ titleRow.append(badges);+ const box = document.createElement("div");+ box.className = "include-note-content";+ wrapper.append(titleRow, box);+ figure.append(wrapper);+ document.body.append(figure);+ figures.push(figure);++ const content = (await entity.getBlob())?.content ?? "";+ await act(async () => {+ render(+ <ParentComponent.Provider value={parent}>+ <MarkdownEmbed+ entity={entity}+ editor={editor}+ content={content}+ preview={options.preview ?? buildPreview(content)}+ renderPreview={options.renderPreview ?? (async (text) => buildPreview(text))}+ />+ </ParentComponent.Provider>,+ box+ );+ });+ return { figure };+}++function buildMarkdownNote(content: string) {+ return buildNote({ title: "Readme", type: "code", mime: "text/x-markdown", content });+}++/** An editor that holds the content of its last save as unsaved, as the host does until it saves. */+function buildEditor(overrides: Partial<ContentEditor> = {}): ContentEditor {+ let unsavedContent: string | undefined;+ return {+ canEdit: () => true,+ getUnsavedContent: () => unsavedContent,+ scheduleSave: vi.fn((getContent: () => string) => {+ unsavedContent = getContent();+ }),+ release: vi.fn(),+ ...overrides+ };+}++function buildPreview(content: string) {+ const preview = document.createElement("div");+ preview.className = "ck-content markdown-preview";+ preview.textContent = content;+ return preview;+}++/** Presses Ctrl and `key` in the content of `view`. */+function pressCtrl(view: { contentDOM: HTMLElement }, key: string) {+ act(() => {+ view.contentDOM.dispatchEvent(new KeyboardEvent("keydown", {+ key, ctrlKey: true, bubbles: true, cancelable: true+ }));+ });+}++/** The CodeMirror view in `figure`, once it has mounted. */+async function findView(figure: HTMLElement) {+ const { EditorView } = await import("@codemirror/view");+ let view: InstanceType<typeof EditorView> | null = null;+ await vi.waitFor(() => {+ const dom = figure.querySelector(".cm-editor");+ view = dom instanceof HTMLElement ? EditorView.findFromDOM(dom) : null;+ expect(view).not.toBeNull();+ }, { timeout: 5000 });+ if (!view) throw new Error("CodeMirror did not mount.");+ return view as InstanceType<typeof EditorView>;+}diff --git a/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.tsx b/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.tsxnew file mode 100644index 0000000000..85ce479333--- /dev/null+++ b/apps/client/src/widgets/type_widgets/markdown/MarkdownEmbed.tsx@@ -0,0 +1,142 @@+import "./MarkdownEmbed.css";++import type VanillaCodeMirror from "@triliumnext/codemirror";+import clsx from "clsx";+import type { RefObject } from "preact";+import { useEffect, useRef, useState } from "preact/hooks";++import type FAttachment from "../../../entities/fattachment";+import FNote from "../../../entities/fnote";+import type { ContentEditor } from "../../../services/content_renderer";+import { isDesktop } from "../../../services/utils";+import { useNoteCodeSettings } from "../../layout/code_menus";+import { useDebouncedValue } from "../../react/hooks";+import { SaveStatus, useSavedContent } from "../code/CodeEmbed";+import CodeEmbedEditor from "../code/CodeEmbedEditor";+import { resolveDisplayMode } from "../helpers/split_editor_mode";+import { SplitLayout, useMountedPanes } from "../helpers/SplitEditor";+import { registerContentEmbedTools, useContentEmbedDisplayMode } from "../text/content_embed_tools";+import {+ CaretNavigationContext, EmbedPreview, useEditableEmbed, useEmbedPreview+} from "../text/editable_embed";+import {+ renderWithSourceLines, useMarkdownKeymap, useNoteLinkChips, useSyncedHighlight,+ useSyncedScrolling+} from "./Markdown";++interface MarkdownEmbedProps {+ entity: FNote | FAttachment;+ /** Saves the changes to `entity`, or `undefined` where the content is read-only. */+ editor: ContentEditor | undefined;+ /** The Markdown shown first. */+ content: string;+ /** The rendering of `content`. */+ preview: HTMLElement;+ /** Renders Markdown as `preview` shows it. */+ renderPreview: (content: string) => Promise<HTMLElement>;+}++/**+ * A Markdown note or file in an embed, laid out as the split editor of a Markdown note: its source+ * in CodeMirror, its rendering, or both side by side, as the display mode of the embed picks. The+ * source can be edited while the Editable toggle of the embed is on.+ */+export default function MarkdownEmbed({+ entity, editor, content: initialContent, preview, renderPreview+}: MarkdownEmbedProps) {+ const rootRef = useRef<HTMLDivElement>(null);+ const viewRef = useRef<VanillaCodeMirror>(null);+ const [ view, setView ] = useState<VanillaCodeMirror | null>(null);+ const note = entity instanceof FNote ? entity : null;+ const { canEdit, isEditing } = useEditableEmbed(rootRef, {+ editor, note, tools: null, focusTarget: ".cm-content"+ });+ useDisplayModeTools(rootRef, canEdit);+ const mode = resolveDisplayMode(useContentEmbedDisplayMode(rootRef), !isEditing);+ const isSourceShown = mode !== "preview";+ const { editorMounted, previewMounted } = useMountedPanes(mode);+ const { tabWidth, useTabs } = useNoteCodeSettings(note);++ const [ content, setContent ] = useState(initialContent);+ useSavedContent(entity, editor, setContent);+ const renderedContent = useDebouncedValue(content, PREVIEW_DELAY);+ const shownPreview = useEmbedPreview(+ preview, renderedContent, () => renderPreview(renderedContent)+ );++ const shownView = isSourceShown ? view : null;+ const previewElement = shownPreview instanceof HTMLDivElement ? shownPreview : null;+ useSyncedScrolling(shownView, previewElement);+ useSyncedHighlight(shownView, previewElement, renderedContent);+ useNoteLinkChips(shownView);+ useMarkdownKeymap(isEditing ? shownView : null);++ return (+ <div+ ref={rootRef}+ className={clsx("markdown-embed-content", isSourceShown && "with-source")}+ >+ <SplitLayout+ mode={mode}+ orientation={isDesktop() ? "horizontal" : "vertical"}+ editor={(+ <div className="note-detail-split-editor">+ {/* Split.js sizes this column, so it stays mounted. CodeMirror is mounted+ only while the source shows, so that "Search in note" and the arrow+ keys never act on a hidden editor. */}+ {isSourceShown && (+ <CaretNavigationContext.Provider value={isEditing ? rootRef : null}>+ <CodeEmbedEditor+ key={isEditing ? "editing" : "read-only"}+ note={note}+ editor={isEditing ? editor : undefined}+ content={content}+ mime={MARKDOWN_MIME}+ tabWidth={tabWidth}+ useTabs={useTabs}+ viewRef={viewRef}+ onClose={setContent}+ onChange={setContent}+ onReady={setView}+ />+ </CaretNavigationContext.Provider>+ )}+ </div>+ )}+ isEditorMounted={editorMounted.current}+ isPreviewMounted={previewMounted.current}+ previewContent={<EmbedPreview element={shownPreview} />}+ />+ {editor && <SaveStatus rootRef={rootRef} editor={editor} isShown={isEditing} />}+ </div>+ );+}++/** The HTML of the Markdown `source`, as the preview of a Markdown note renders it. */+export function renderMarkdownHtml(source: string) {+ return renderWithSourceLines(source).html;+}++/**+ * Offers the display modes of the content in `rootRef` on its embed, and the Editable toggle while+ * `canEdit`.+ */+function useDisplayModeTools(rootRef: RefObject<HTMLElement | null>, canEdit: boolean) {+ useEffect(() => {+ const root = rootRef.current;+ if (!root) return;++ return registerContentEmbedTools(root, {+ hasEditableFlag: canEdit,+ hasDisplayModes: true,+ getTools: () => [],+ execute: () => {},+ subscribe: () => () => {}+ });+ }, [ rootRef, canEdit ]);+}++/** The language of the source pane. */+const MARKDOWN_MIME = "text/x-markdown";+/** How long the source has to stay unchanged before the preview renders again, in milliseconds. */+const PREVIEW_DELAY = 300;diff --git a/apps/client/src/widgets/type_widgets/text/ContentEmbed.spec.tsx b/apps/client/src/widgets/type_widgets/text/ContentEmbed.spec.tsxindex dd047ec9c3..5a1e6bfb3e 100644--- a/apps/client/src/widgets/type_widgets/text/ContentEmbed.spec.tsx+++ b/apps/client/src/widgets/type_widgets/text/ContentEmbed.spec.tsx@@ -197,6 +197,35 @@ function placeInHostEditor() {return { editor: { selectEmbedAt, execute, focus }, embed };}+/** Tools of content with display modes, which the title row of its embed switches. */+const DISPLAY_MODE_TOOLS = {+ hasDisplayModes: true,+ getTools: () => [],+ execute: () => {},+ subscribe: () => () => {}+};++/** Moves the box into an embed outside a text editor, as a read-only note shows it. */+function placeInEmbed() {+ const embed = document.createElement("figure");+ embed.className = "include-note";+ embed.append(container);+ document.body.append(embed);+ onTestFinished(() => embed.remove());+ return embed;+}++/** The display mode buttons of the title row: Source, Split and Preview. */+function displayModeButtons() {+ return [ ...container.querySelectorAll<HTMLButtonElement>(".include-note-display-modes button") ];+}++/** The display mode whose button is on, or `null`. */+function shownDisplayMode() {+ const index = displayModeButtons().findIndex((button) => button.classList.contains("active"));+ return index < 0 ? null : [ "source", "split", "preview" ][index];+}+/** Clicks `target` and tells whether the click was kept from what surrounds the box. */function click(target: HTMLElement) {const event = new MouseEvent("click", { bubbles: true, cancelable: true });@@ -432,6 +461,67 @@ describe("ContentEmbed", () => {expect(edit.classList.contains("active")).toBe(false);});+ it("switches the display mode of content that has them, from the title row", async () => {+ const embed = placeInEmbed();+ const { content } = renderBox({ boxSize: "medium", contentType: "markdown" });+ expect(container.querySelector(".include-note-display-modes")).toBeNull();++ let unregister = () => {};+ act(() => {+ unregister = registerContentEmbedTools(content, DISPLAY_MODE_TOOLS);+ });+ expect(titleRow()).toEqual([+ "title-label", "badges", "display-modes", "open", "fullscreen", "menu"+ ].map((name) => `include-note-${name}`));+ const buttons = displayModeButtons();+ expect(buttons.map((button) => /\bbxs?-[\w-]+/.exec(button.className)?.[0]))+ .toEqual([ "bx-code", "bxs-dock-left", "bx-show" ]);+ expect(buttons.map((button) => tooltipOf(button)))+ .toEqual([ "display_mode.source", "display_mode.split", "display_mode.preview" ]);+ expect(shownDisplayMode()).toBe("preview");+ expect(buttons.map((button) => button.getAttribute("aria-pressed")))+ .toEqual([ "false", "false", "true" ]);++ // Content that can be edited shows split while Editable is on, until a mode is picked.+ await act(async () => {+ embed.dataset.editable = "true";+ await Promise.resolve();+ });+ expect(shownDisplayMode()).toBe("preview");+ act(() => {+ unregister();+ unregister = registerContentEmbedTools(content, {+ ...DISPLAY_MODE_TOOLS, hasEditableFlag: true+ });+ });+ expect(shownDisplayMode()).toBe("split");++ // Outside a text editor, the mode lasts until the embed is drawn again.+ expect(click(displayModeButtons()[0]).isStopped).toBe(true);+ await act(async () => {+ await Promise.resolve();+ });+ expect(embed.dataset.displayMode).toBe("source");+ expect(shownDisplayMode()).toBe("source");++ act(() => unregister());+ expect(container.querySelector(".include-note-display-modes")).toBeNull();+ });++ it("picks the display mode through the text editor that holds the embed", () => {+ const { editor, embed } = placeInHostEditor();+ const { content } = renderBox({ boxSize: "medium", contentType: "markdown" });+ act(() => {+ onTestFinished(registerContentEmbedTools(content, DISPLAY_MODE_TOOLS));+ });++ click(displayModeButtons()[2]);+ expect(editor.selectEmbedAt).toHaveBeenCalledWith(contentBox());+ expect(editor.execute)+ .toHaveBeenCalledWith("contentEmbedDisplayMode", { value: "preview" });+ expect(embed.hasAttribute("data-display-mode")).toBe(false);+ });+it("keeps the edit button of an excerpt disabled without an editor around it", () => {const { content } = renderBox({ boxSize: "medium", isExcerpt: true });act(() => {diff --git a/apps/client/src/widgets/type_widgets/text/ContentEmbed.tsx b/apps/client/src/widgets/type_widgets/text/ContentEmbed.tsxindex 726279cbdf..65fb802756 100644--- a/apps/client/src/widgets/type_widgets/text/ContentEmbed.tsx+++ b/apps/client/src/widgets/type_widgets/text/ContentEmbed.tsx@@ -11,11 +11,15 @@ import type { ViewScope } from "../../../services/link";import { removeIndividualBinding } from "../../../services/shortcuts";import ActionButton from "../../react/ActionButton";import { Badge } from "../../react/Badge";+import { ButtonGroup } from "../../react/Button";import { useFocusWithin } from "../../react/hooks";import Icon from "../../react/Icon";import OverlayControlGroup, { OverlayControlButton } from "../../react/OverlayControlGroup";import { HtmlFindTarget } from "../../find_in_html";import ScrollableLabel from "../../react/ScrollableLabel";+import {+ DISPLAY_MODE_OPTIONS, type DisplayMode, resolveDisplayMode+} from "../helpers/split_editor_mode";import {type ContentEmbedEvent, getContentEmbedTools, registerEmbedFindTarget,showContentEmbedFullscreen, useContentEmbedFindReveal, useIsContentEmbedEditable,@@ -130,6 +134,7 @@ export default function ContentEmbed({<div className="note-badges include-note-badges">{isExcerpt && <ExcerptBadge />}</div>+ <DisplayModeButtons contentRef={contentRef} content={content} /><ContentEmbedActionButtonclassName="include-note-open"action={getOpenInNewTabAction(notePath, viewScope)}@@ -333,6 +338,87 @@ function useHasEditableMode(contentRef: RefObject<HTMLElement | null>, content:return hasEditableMode;}+/**+ * Switches what content with display modes shows, as the display mode buttons of a note do. In a+ * text editor, the mode is saved with the embed.+ */+function DisplayModeButtons({ contentRef, content }: {+ contentRef: RefObject<HTMLDivElement | null>;+ content: HTMLElement;+}) {+ const shownMode = useShownDisplayMode(contentRef, content);+ if (!shownMode) return null;++ return (+ <ButtonGroup size="sm" className="include-note-display-modes">+ {DISPLAY_MODE_OPTIONS.map(({ value, icon, titleKey }) => (+ <ActionButton+ key={value}+ icon={icon}+ text={t(titleKey)}+ active={value === shownMode}+ aria-pressed={value === shownMode}+ onClick={(e) => {+ e.stopPropagation();+ setEmbedDisplayMode(contentRef.current, value);+ }}+ />+ ))}+ </ButtonGroup>+ );+}++/**+ * The display mode that the content in `contentRef` shows, for content that has display modes,+ * otherwise `null`. Checked again for new `content`, which can declare them before it is in the+ * box.+ */+function useShownDisplayMode(contentRef: RefObject<HTMLElement | null>, content: HTMLElement) {+ const [ shownMode, setShownMode ] = useState<DisplayMode | null>(null);++ useEffect(() => {+ const box = contentRef.current;+ const embed = box?.closest<HTMLElement>(".include-note");+ if (!box || !embed) return;++ const update = () => {+ const tools = getContentEmbedTools(box);+ const isEditing = !!tools?.hasEditableFlag && embed.dataset.editable === "true";+ setShownMode(tools?.hasDisplayModes+ ? resolveDisplayMode(embed.dataset.displayMode, !isEditing)+ : null);+ };+ update();+ const observer = new MutationObserver(update);+ observer.observe(embed, {+ attributes: true, attributeFilter: [ "data-display-mode", "data-editable" ]+ });+ const stopWatching = watchContentEmbedTools(box, update);+ return () => {+ observer.disconnect();+ stopWatching();+ };+ }, [ contentRef, content ]);++ return shownMode;+}++/**+ * Shows `mode` in the content of the embed around `box`. A text editor that holds the embed saves+ * the mode; outside an editor, the mode lasts until the embed is drawn again.+ */+function setEmbedDisplayMode(box: HTMLElement | null, mode: DisplayMode) {+ const editor = findTextEditorAround(box);+ if (!editor) {+ box?.closest<HTMLElement>(".include-note")?.setAttribute("data-display-mode", mode);+ return;+ }++ if (box && editor.plugins.get("ContentEmbed").selectEmbedAt(box)) {+ editor.execute("contentEmbedDisplayMode", { value: mode });+ }+}+/*** Returns a function that focuses the element in `ref` once the render it schedules is committed,* so that a state change made with it, such as one that shows the element, applies first.diff --git a/apps/client/src/widgets/type_widgets/text/content_embed_tools.ts b/apps/client/src/widgets/type_widgets/text/content_embed_tools.tsindex ca580e85ae..350900fa26 100644--- a/apps/client/src/widgets/type_widgets/text/content_embed_tools.ts+++ b/apps/client/src/widgets/type_widgets/text/content_embed_tools.ts@@ -55,6 +55,11 @@ export interface ContentEmbedToolProvider {* turn on and off. The embed carries `data-editable="true"` while it is on.*/hasEditableFlag?: boolean;+ /**+ * Whether the content shows its source, its rendering or both, which the toolbar and the menu+ * of the embed then switch. The embed carries the mode as `data-display-mode`.+ */+ hasDisplayModes?: boolean;}/**@@ -289,6 +294,15 @@ export function useContentEmbedAttribute(return value;}+/**+ * The display mode picked for the embed that contains `ref`, for content whose provider sets+ * `hasDisplayModes`. `null` while none is picked, outside an embed, and until the content is in the+ * embed: `resolveDisplayMode()` then tells what to show.+ */+export function useContentEmbedDisplayMode(ref: RefObject<HTMLElement | null>) {+ return useContentEmbedAttribute(ref, "data-display-mode");+}+/*** Calls `callback` when the embed that contains `ref` dispatches `name`. Listens on the document,* as content can mount before its embed box takes it in.diff --git a/apps/client/src/widgets/type_widgets/text/editable_embed.tsx b/apps/client/src/widgets/type_widgets/text/editable_embed.tsxindex a93fd6702e..aae8543efa 100644--- a/apps/client/src/widgets/type_widgets/text/editable_embed.tsx+++ b/apps/client/src/widgets/type_widgets/text/editable_embed.tsx@@ -279,8 +279,12 @@ type EditorRootElement = HTMLElement & { ckeditorInstance?: CKTextEditor };const EDITOR_ROOT_SELECTOR = ".ck-editor__editable:not(.ck-editor__nested-editable)";-/** The content box of an embed whose editor has caret navigation, or `null`. */-const CaretNavigationContext = createContext<RefObject<HTMLElement | null> | null>(null);+/**+ * The root of the content of an embed whose editor has caret navigation, or `null`. Set by+ * `EditableEmbedContent` for `hasCaretNavigation`, and by content that lays out its own editor,+ * such as `MarkdownEmbed`.+ */+export const CaretNavigationContext = createContext<RefObject<HTMLElement | null> | null>(null);const EDITABLE_FLAG_TOOLS: ContentEmbedToolProvider = {hasEditableFlag: true,@@ -299,7 +303,8 @@ function leaveContentEmbed(element: HTMLElement, edge: EmbedEdge) {&& editor.plugins.get("ContentEmbedCaret").leaveEmbed(element, edge);}-function EmbedPreview({ element }: { element: HTMLElement }) {+/** Shows `element`, the rendered content of an embed. */+export function EmbedPreview({ element }: { element: HTMLElement }) {const containerRef = useRef<HTMLDivElement>(null);useLayoutEffect(() => {diff --git a/apps/client/src/widgets/type_widgets/text/utils.spec.ts b/apps/client/src/widgets/type_widgets/text/utils.spec.tsindex c7a8983610..52ecfb57e2 100644--- a/apps/client/src/widgets/type_widgets/text/utils.spec.ts+++ b/apps/client/src/widgets/type_widgets/text/utils.spec.ts@@ -124,7 +124,8 @@ describe("loadEmbeddedNote", () => {expect(content_renderer.getRenderedContent).toHaveBeenCalledWith(note, {interactive: true,embedsAsReferenceLinks: true,- mediaEnvironment: "embedded"+ mediaEnvironment: "embedded",+ hasDisplayModes: true});const mount = lastMount();expect(mount.type).toBe(ContentEmbed);@@ -224,8 +225,9 @@ describe("loadEmbeddedAttachment", () => {showNoteIcon: true,viewScope: ATTACHMENT_SCOPE});- expect(content_renderer.getRenderedContent)- .toHaveBeenCalledWith(attachment, { interactive: true, mediaEnvironment: "embedded" });+ expect(content_renderer.getRenderedContent).toHaveBeenCalledWith(attachment, {+ interactive: true, mediaEnvironment: "embedded", hasDisplayModes: true+ });const mount = lastMount();expect(mount.type).toBe(ContentEmbed);expect(mount.container).toBe(wrapper);@@ -250,6 +252,7 @@ describe("loadEmbeddedAttachment", () => {expect(content_renderer.getRenderedContent).toHaveBeenCalledWith(attachment, {interactive: true,mediaEnvironment: "embedded",+ hasDisplayModes: true,attachmentEditor});expect(lastMount().props).toMatchObject({ isFocusedOnMount: true });diff --git a/apps/client/src/widgets/type_widgets/text/utils.ts b/apps/client/src/widgets/type_widgets/text/utils.tsindex 1424c0c3c9..e80ec3e0df 100644--- a/apps/client/src/widgets/type_widgets/text/utils.ts+++ b/apps/client/src/widgets/type_widgets/text/utils.ts@@ -69,6 +69,7 @@ export async function loadEmbeddedNote(interactive: true,embedsAsReferenceLinks: true,mediaEnvironment: "embedded",+ hasDisplayModes: true,noteEditor,block,onBlockChange@@ -135,6 +136,7 @@ export async function loadEmbeddedAttachment(const { $renderedContent, type } = await content_renderer.getRenderedContent(attachment, {interactive: true,mediaEnvironment: "embedded",+ hasDisplayModes: true,attachmentEditor,codeLanguage: el.closest(".include-note")?.getAttribute("data-code-language") ?? undefined});diff --git a/apps/server/src/assets/help/help_content.json b/apps/server/src/assets/help/help_content.jsonindex d802fd37e4..41344b41b7 100644--- a/apps/server/src/assets/help/help_content.json+++ b/apps/server/src/assets/help/help_content.json@@ -56,7 +56,7 @@"_help_r5JGHN99bVKn": "<figure class=\"image image-style-align-center image_resized\" style=\"width:50%;\"><img style=\"aspect-ratio:988/572;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/UI%20Elements/Recent%20Changes_image.png\" width=\"988\" height=\"572\"></figure><h2>Accessing the recent changes</h2><ul><li>For an overview of the changes across all documents, press the <span class=\"tn-icon bx bx-history\"></span> button in the <a class=\"reference-link\" href=\"#root/_help_xYmIYSP6wE3F\">Launch Bar</a>.<ul><li>If there is a <a href=\"#root/_help_OR8WJ7Iz9K4U\">hoisted note</a> or a <a href=\"#root/_help_9sRHySam5fXb\">workspace</a>, the list of recent changes will be limited to the descendents of the hoisted note, or the workspace.</li></ul></li><li>To limit the list of recent changes to a note and its descendants, look for the corresponding option in the <a class=\"reference-link\" href=\"#root/_help_YtSN43OrfzaA\">Note tree contextual menu</a> → Advanced.</li></ul><h2>Interaction</h2><ul><li>Notes which were changed will appear in reverse chronological order (latest update first).</li><li>The title of the note is displayed, as well as the note path. Clicking on the note title will dismiss the dialog and navigate to that particular note.</li><li>Deleted notes will also be listed here, at their time of deletion. Press the <em>Undelete</em> link next to them in order to recover them.</li></ul>","_help_ny318J39E5Z0": "<p>Zoom applies to the entire UI, including text.</p><p>On the desktop application, use the <a class=\"reference-link\" href=\"#root/_help_x3i7MxGccDuM\">Global menu</a> to zoom in/out.</p><p>On both web browser and the desktop, the keyboard shortcuts <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>+</kbd> and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>-</kbd> can be used.</p><h2>Adjusting the text size instead</h2><p>As an alternative to the zoom, the text size can be individually adjusted by going to <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Appearance</em>.</p>","_help_lgKX7r3aL30x": "<figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:505/261;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/UI%20Elements/Note%20Tooltip_image.png\" width=\"505\" height=\"261\"></figure><p>The note tooltip is a convenience feature which displays a popup when hovering over an <a href=\"#root/_help_hrZ1D00cLbal\">internal link</a> to another note.</p><p>The following information is displayed:</p><ul><li>The note path, at the top of the popup.</li><li>The title of the note.<ul><li>Clicking on the title will open the note in the current tab.</li><li>Holding <kbd>Ctrl</kbd> pressed while clicking the title will open in a new tab instead of the current one.</li></ul></li><li>A snippet of the content will be displayed as well.</li><li>A button to <a href=\"#root/_help_ZjLYv08Rp3qC\">quickly edit</a> the note in a popup.</li></ul><p>For a link to an <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a>, the tooltip shows the attachment instead: its title after the path of the note that owns it, a line giving its size (for example <em>Attachment • 20.59 MiB</em>), a preview of its content where one is available, and the quick edit button opening the attachment.</p><p>The tooltip can be found in multiple places, including:</p><ul><li>In <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, when hovering over <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> .</li><li><a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a>: <ul><li><a class=\"reference-link\" href=\"#root/_help_81SGnPGMk7Xc\">Geo Map View</a>, when hovering over a marker.</li><li><a class=\"reference-link\" href=\"#root/_help_xWbu3jpNWapp\">Calendar View</a>, when hovering over an event.</li><li><a class=\"reference-link\" href=\"#root/_help_2FvYrpmOXm29\">Table View</a>, when hovering over a note title, or over a <a href=\"#root/_help_Cq5X6iKQop6R\">relation</a>.</li></ul></li></ul>",- "_help_SL5f1Auq7sVN": "<p>Split view is a feature of <a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> and <a class=\"reference-link\" href=\"#root/_help_6RM1Q7ppFVoj\">Markdown</a> notes which displays both the source code on one side and the preview of the content on the other.</p><p><a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> also allow changing between a horizontal or a vertical split, to accommodate for the various sizes of diagrams.</p><h2>Display modes and interaction</h2><p>The split comes with three different display modes which can be toggled from the <a class=\"reference-link\" href=\"#root/_help_1P8QXI5edXNd\">Note buttons</a> area:</p><ul><li><span class=\"tn-icon bx bxs-dock-left\"></span> <em>(Split view)</em>, in which both the source code is available on one side and can be edited, and the preview is available on the other side.<ul><li>In this mode, the size of either the source pane or the preview pane can be adjusted by dragging the small border between them.</li></ul></li><li><span class=\"tn-icon bx bx-code\"></span> (<em>Source view)</em> which shows the source code on the entire screen for a more focused editing experience.</li><li><span class=\"tn-icon bx bx-show\"></span> <em>(Preview)</em> which displays only the rendering of the diagram or text in full screen, especially useful for read-only notes.</li></ul><p>The display node is stored at note level.</p><h2>Relation to read-only notes</h2><p>If a note is marked as <a href=\"#root/_help_CoFPLs3dRlXc\">read-only</a>, the source view will not be editable. While in preview mode, marking a note as read-only has no effect since the preview itself is not editable.</p>",+ "_help_SL5f1Auq7sVN": "<p>Split view is a feature of <a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> and <a class=\"reference-link\" href=\"#root/_help_6RM1Q7ppFVoj\">Markdown</a> notes which displays both the source code on one side and the preview of the content on the other.</p><p><a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> also allow changing between a horizontal or a vertical split, to accommodate for the various sizes of diagrams.</p><h2>Display modes and interaction</h2><p>The split comes with three different display modes which can be toggled from the <a class=\"reference-link\" href=\"#root/_help_1P8QXI5edXNd\">Note buttons</a> area:</p><ul><li><span class=\"tn-icon bx bxs-dock-left\"></span> <em>(Split view)</em>, in which both the source code is available on one side and can be edited, and the preview is available on the other side.<ul><li>In this mode, the size of either the source pane or the preview pane can be adjusted by dragging the small border between them.</li></ul></li><li><span class=\"tn-icon bx bx-code\"></span> (<em>Source view)</em> which shows the source code on the entire screen for a more focused editing experience.</li><li><span class=\"tn-icon bx bx-show\"></span> <em>(Preview)</em> which displays only the rendering of the diagram or text in full screen, especially useful for read-only notes.</li></ul><p>The display node is stored at note level.</p><p>A Markdown note included in a text note, or a Markdown file embedded in one, has the same three display modes, switched from the title row and the toolbar of the include. See <em>Included Markdown</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>.</p><h2>Relation to read-only notes</h2><p>If a note is marked as <a href=\"#root/_help_CoFPLs3dRlXc\">read-only</a>, the source view will not be editable. While in preview mode, marking a note as read-only has no effect since the preview itself is not editable.</p>","_help_t596jLvPrqkS": "<p>Some note types (such as <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> and saved search) intentionally limit the width of the content.</p><p>This might appear surprising at first, but the idea is to make text fit well on wider screens without appearing distorted. This is especially the case if the document contains <a class=\"reference-link\" href=\"#root/_help_mT0HEkOsz6i1\">Images</a>, tables or other width-dependent elements.</p><h2>Configuring the content width and alignment</h2><p>The content width is expressed in pixels and can be changed from <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Appearance</em> → <em>Content Width</em> and adjusting the <em>Max content width</em> section.</p><p>To effectively disable the content width limitation, simply set the width to a value larger than your screen size (e.g. 9999).</p><p>By default, the content is aligned to the left, but it can be centered horizontally by checking <em>Keep content centered</em> from the same section as the content width.</p><h2>Adjusting at note level</h2><p>For notes with large elements such as <a class=\"reference-link\" href=\"#root/_help_NdowYOC1GFKS\">Tables</a>, it sometimes makes sense to avoid the content width without affecting other notes. To do so:</p><ul><li>Go to <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and toggle <em>Full width</em>.</li><li>Or manually apply the <code>fullContentWidth</code> <a href=\"#root/_help_HI6GBBIduIgv\">label</a> to the note.</li></ul><p>Since v0.107.0, a single table can also be made wider than the content width, in which case it scrolls sideways. See <a class=\"reference-link\" href=\"#root/_help_NdowYOC1GFKS\">Tables</a>.</p><aside class=\"admonition note\"><p>Some <a href=\"#root/_help_KSZ04uQ2D1St\">note types</a> are full width by default, such as the <a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a>. In that case the <em>Full width</em> toggle will not be displayed and the label will have no effect.</p></aside><h2>Shared notes</h2><p>On a <a href=\"#root/_help_R9pX4DGra2Vt\">shared page</a>, a text note is shown at a fixed reading width, whatever the width configured in Options, and the navigation tree, the content and the table of contents are kept together in a column centered on a wide screen. A note with <code>fullContentWidth</code>, or of a type that is full width in the application, uses the whole width of the window there, with the navigation tree and the table of contents at its edges.</p>","_help_jcQVxzYybYgz": "<figure class=\"image image-style-align-right image_resized\" style=\"width:44.65%;\"><img style=\"aspect-ratio:514/291;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/UI%20Elements/Note%20contextual%20menu_image.png\" width=\"514\" height=\"291\"></figure><p>Right-clicking the content of some note types such as <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> or <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> reveals a contextual menu.</p><h2>Features</h2><ul><li>On the <a class=\"reference-link\" href=\"#root/_help_poXkQfguuA0U\">Desktop Installation</a>, the <a class=\"reference-link\" href=\"#root/_help_oBo3iHIZnbG2\">Spell Check</a> suggestions are shown when right clicking on a misspelled word.</li><li>The selected text can be searched either with a search engine (configured from <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>) or <a href=\"#root/_help_eIg8jdvaoNNd\">inside Trilium</a>.</li><li>Basic clipboard functionality (cut, copy, paste).</li><li>Copying the selected text as <a class=\"reference-link\" href=\"#root/_help_Oau6X9rCuegd\">Markdown</a>.</li><li>Performing quick operations using the <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a>.</li></ul><h2>Differences between desktop and web</h2><p>The <a href=\"#root/_help_WOcw2SLH6tbX\">web version</a> behaves slightly different due to limitations imposed by web browsers:</p><ul><li>When no text is selected or a word is right-clicked, the browser's default contextual menu is displayed.<ul><li>This is intentional since it preserves the <a class=\"reference-link\" href=\"#root/_help_oBo3iHIZnbG2\">Spell Check</a> functionality.</li></ul></li><li>When a text is selected, a reduced menu is displayed instead which features only the functionality that is available within the browser version<ul><li><em>Paste</em> is not available since the browser doesn't expose it, use <kbd>Ctrl</kbd>+<kbd>V</kbd> instead.</li><li>The browser menu can be triggered anyway by pressing <kbd>Shift</kbd> + <kbd>Right click</kbd>.</li></ul></li></ul>","_help_AlJ73vBCjWDw": "<p>The status bar displays information about the current note and allows changing settings related to it such as configuring the language or attributes.</p><h2>Layout and interaction</h2><p>On the left side, the <a class=\"reference-link\" href=\"#root/_help_I6p2a06hdnL6\">Breadcrumb</a> is displayed which indicates the current note as well as its parent notes and allows for quick navigation throughout the hierarchy.</p><p>On the right side, specific sections will show depending on the type of the current note.</p><ol><li>For <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes, the language mode of the note is indicated (e.g. JavaScript, plain text), as well as allowing easy switching to another mode.</li><li>For <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, the content language is displayed and can be changed, thus configuring the spell-check and the right-to-left support.<ol><li>Note that this applies to the entire note and not the selection, unlike some text editors.</li></ol></li><li>If a note is placed in multiple places in the tree (cloned), the number of the note paths will be displayed.<ol><li>Clicking it opens a popup with the full list of note paths, from which the note can also be cloned to a new location. The same list is available in the sidebar's <a class=\"reference-link\" href=\"#root/_help_KRlZFoIH0j6p\">Connections tab</a>.</li></ol></li><li>If a note has attachments, their number will be displayed.<ol><li>Clicking on it will reveal the list of attachments in a new tab.</li></ol></li><li>If a note is linked from other text notes (backlinks), the number of backlinks will be displayed.<ol><li>Clicking on it opens a popup with the list of notes that link to this note, as well as an excerpt of where the note is referenced. The same list is available in the sidebar's <a class=\"reference-link\" href=\"#root/_help_KRlZFoIH0j6p\">Connections tab</a>.</li></ol></li></ol><p>Regardless of note type, the following items will always be displayed if there is a note:</p><ol><li>Note info, which displays:<ol><li>The creation/modification date of the note.</li><li>The type and MIME of the note.</li><li>The note ID.</li><li>An estimation of the note size of the note itself and its children.</li><li>A button to reveal the Similar notes in the sidebar's <a class=\"reference-link\" href=\"#root/_help_KRlZFoIH0j6p\">Connections tab</a>.</li></ol></li></ol><aside class=\"admonition note\"><p>When pressing a button which reveals the <a class=\"reference-link\" href=\"#root/_help_RnaPdbciOfeq\">Right Sidebar</a>, it has a specific behavior if the sidebar is hidden: the sidebar will be peeked instead of docked. Regardless the sidebar will be switched to the appropriate tab and the corresponding section will be highlighted.</p></aside>",@@ -64,7 +64,7 @@"_help_BFs8mudNFgCS": "<p>Note is a central entity in Trilium. Main attributes of note are <a href=\"#root/_help_l7pigIGu01K2\">title</a> and content.</p><h3>Note types</h3><p>The main note type is a rich-text note type called <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a>. For diagrams and drawing there is <a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a> and <a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a>.</p><p>There are also more complex note types such as <a class=\"reference-link\" href=\"#root/_help_m523cpzocqaD\">Saved Search</a>, <a class=\"reference-link\" href=\"#root/_help_HcABDtFCkbFN\">Render Note</a> that usually go hand-in-hand with <a class=\"reference-link\" href=\"#root/_help_CdNpE2pqjmI6\">Scripting</a>.</p><p>In Trilium there's no specific \"folder\" note type. Any note can have children and thus be a folder. To make a note that only shows its children, like a folder in other applications, use a <a class=\"reference-link\" href=\"#root/_help_8QqnMzx393bx\">Grid View</a> or <a class=\"reference-link\" href=\"#root/_help_mULW0Q3VojwY\">List View</a> collection. See also <a class=\"reference-link\" href=\"#root/_help_i6dbnitykE5D\">FAQ</a>.</p><h3>Root note</h3><p>There's one special note called \"root note\" which is root of the note tree. All other notes are placed below it in the structure.</p><h3>Tree structure</h3><p>Importantly, note itself doesn't carry information on its placement in note tree. See <a class=\"reference-link\" href=\"#root/_help_IakOLONlIfGI\">Cloning Notes</a> for details.</p><p>Tree structure of notes can resemble file system - but compared to that notes in Trilium can act as both file and directory - meaning that note can both have its own content and have children. \"Leaf note\" is a note which doesn't have any children.</p><h3>Deleting / undeleting notes</h3><p>When you delete a note in Trilium, it is actually only marked for deletion (soft-delete) - the actual content, title, attributes etc. are not deleted, only hidden.</p><p>Within (by default) 7 days, it is possible to undelete these soft-deleted notes - open the <a class=\"reference-link\" href=\"#root/_help_r5JGHN99bVKn\">Recent Changes</a> dialog, and you will see a list of all modified notes including the deleted ones. Notes available for undeletion have a link to do so. This is kind of \"trash can\" functionality known from e.g. Windows.</p><p>Clicking an undelete will recover the note, its content and attributes - note should be just as before being deleted. This action will also undelete note's children which have been deleted in the same action.</p><p>To be able to undelete a note, it is necessary that deleted note's parent must be undeleted (otherwise there's no place where we can undelete it to). This might become a problem when you delete more notes in succession - the solution is then undelete in the reverse order of your deletion.</p><p>After the 7 days (configurable) the notes will be \"erased\" - their title, content, revisions and attributes will be erased, and it will not be possible anymore to recover them (unless you restore a <a class=\"reference-link\" href=\"#root/_help_ODY7qQn5m2FT\">Backup</a>).</p><h2>See also</h2><ul><li><a class=\"reference-link\" href=\"#root/_help_CoFPLs3dRlXc\">Read-Only Notes</a></li></ul>","_help_l7pigIGu01K2": "<p>Alongside its content, the <strong>title</strong> is one of the two main attributes of a <a href=\"#root/_help_BFs8mudNFgCS\">note</a>. It's the short, human-readable name shown in the editable field at the top of every note, and it's what identifies the note throughout the interface (in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, in tabs, in the <a class=\"reference-link\" href=\"#root/_help_I6p2a06hdnL6\">Breadcrumb</a> and win <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>.</p><p>Internally, notes are identified by a unique <a class=\"reference-link\" href=\"#root/_help_m1lbrzyKDaRB\">Note ID</a> rather than by their title, so the title is purely for your benefit. This has a few consequences:</p><ul><li><strong>Titles don't have to be unique.</strong> You can have any number of notes that share the same title without conflict.</li><li><strong>Renaming a note never breaks links to it.</strong> Links between notes point at the underlying note, so changing a title leaves existing links intact (they'll simply display the new title).</li><li><strong>The title can be left empty.</strong> Notes with no title display a placeholder (<em>type note's title here…</em>) but are otherwise perfectly valid.</li></ul><p>In addition:</p><ul><li>There is no limitation on the length of the title, however in exports the title might get trimmed.</li><li>There are no forbidden symbols, unsupported characters will get trimmed when exporting.</li><li>When exporting to a ZIP file, a meta file will contain the full title which will be recognized by Trilium when importing again.</li></ul><h2>Inline title</h2><p><a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes have a special title bar behavior in which the <a href=\"#root/_help_l7pigIGu01K2\">note title</a> is initially displayed in a larger font, while also displaying additional information such as the creation and the modification date.</p><p>Whenever the title is scrolled past, the fixed title is shown instead.</p><p>Note types that take the entirety of the screen, such as <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> and <a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a>, will always have only the fixed title bar.</p><p>Under the note title, the <a class=\"reference-link\" href=\"#root/_help_m3VlURMSeOrd\">New note type switcher</a> appears if the note is empty.</p><figure class=\"image\"><img style=\"aspect-ratio:899/122;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Title_image.png\" width=\"899\" height=\"122\"><figcaption>The <em>Inline title</em>, which is displayed at the top of the note and can be scrolled past.</figcaption></figure><figure class=\"image\"><img style=\"aspect-ratio:910/104;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/1_Title_image.png\" width=\"910\" height=\"104\"><figcaption>The fixed title bar. The title only appears after scrolling past the <em>Inline title</em>.</figcaption></figure><h3>Editing the title</h3><p>To rename a note, simply click into the title field and type. Changes are saved automatically as you type.</p><p>You can also begin editing the title directly from the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> by selecting a note and pressing <kbd>Enter</kbd> (see <em>Edit note title</em> in <a class=\"reference-link\" href=\"#root/_help_A9Oc6YKKc65v\">Keyboard Shortcuts</a>), which focuses the title field for the active note.</p><aside class=\"admonition note\"><p>Titles may contain any characters, including Unicode and emoji. For security, any HTML in the title is stripped automatically, so the title is always treated as plain text.</p></aside><h3>Easily navigating between the title and the content</h3><p>When the cursor is in the title field, pressing <kbd>Enter</kbd> moves focus into the note's content. For <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes this also inserts a fresh empty paragraph at the very top of the document, so you can start writing immediately — much like other note-taking apps.</p><p>This makes it possible to create a note, type its title, press <kbd>Enter</kbd>, and continue straight into the body without reaching for the mouse.</p><h3>Working with new notes</h3><p>When you create a new note it's given a default title (<em>new note</em>) which is pre-selected, so you can type a name right away to replace it. The default title for new notes can be customized per-section — see <a class=\"reference-link\" href=\"#root/_help_47ZrP6FNuoG8\">Default Note Title</a>.</p><p>If you decide you don't want the note after all, pressing <kbd>Escape</kbd> while the title of a freshly created note is still focused will discard it.</p><h3>Automatically generated titles</h3><p>Some notes get their titles assigned automatically rather than typed:</p><ul><li><strong>Day, week, month and year notes</strong> in the <a class=\"reference-link\" href=\"#root/_help_l0tKav7yLHGF\">Day Notes</a> are named from a configurable date pattern.</li><li><a class=\"reference-link\" href=\"#root/_help_m523cpzocqaD\">Saved Search</a> notes are named after the search they perform.</li><li>When a note is duplicated, a suffix is appended to the copy's title to tell it apart from the original.</li></ul><h3>Protected notes</h3><p>For <a class=\"reference-link\" href=\"#root/_help_bwg0e8ewQMak\">Protected Notes</a>, the title is <em>not</em> encrypted — only the content is. The title therefore remains visible in the tree and tabs even when no protected session is active. While locked, however, the title field is read-only and cannot be edited until you enter your password.</p><p>The titles of <a class=\"reference-link\" href=\"#root/_help_bwg0e8ewQMak\">Protected Notes</a> are encrypted along with their content. Before entering your password, Trilium cannot decrypt the title, so it is shown as <code>[protected]</code> in instead and the title cannot be modified.</p><p>Once you enter your password and a protected session is active, the real title is decrypted and displayed, and becomes editable again.</p>","_help_p9kXRFAkwN4o": "<h2>Icons</h2><figure class=\"image image-style-align-right image_resized\" style=\"width:48.4%;\"><img style=\"aspect-ratio:1089/995;\" src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Note%20Icons%20%26%20Colors_image.png\" width=\"1089\" height=\"995\"></figure><p>Icons are useful for distinguishing notes and are displayed near the note title, as well as in various places such as the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> or the <a class=\"reference-link\" href=\"#root/_help_F1r9QtzQLZqm\">Jump to & command palette</a>.</p><p>While editing a note, click on the icon next to the title to bring up a chooser gallery.</p><p>Icons can be inherited through the use of <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a>, or <a class=\"reference-link\" href=\"#root/_help_bwZpz2ajCEwO\">Attribute Inheritance</a>.</p><aside class=\"admonition note\"><p>At the technical level, they are set by the <code>iconClass</code> attribute which adds a CSS class to the note. For example <code>#iconClass=\"bx bx-calendar\"</code> will show a calendar instead of the default page or folder icon. Looking up and remembering the CSS class names is not necessary.</p></aside><h2>Colors</h2><p>Notes can also carry a custom color. Similar to the note icon, this color will be shown in various places such as the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>.</p><p>To set a custom color, right click on the note in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and select a predefined color from there or use the color picker (last option).</p><p>Alternatively, a custom color can be set manually through the <code>#color</code> <a href=\"#root/_help_HI6GBBIduIgv\">label</a>, whose value must be a valid hex color including the leading <code>#</code> (e.g. <code>#ff0000</code> for red). This color can be carried over across multiple notes via <a class=\"reference-link\" href=\"#root/_help_bwZpz2ajCEwO\">Attribute Inheritance</a>.</p>",- "_help_0vhv7lsOLy82": "<p>A <a href=\"#root/_help_BFs8mudNFgCS\">note</a> in Trilium can <em>own</em> one or more attachments, which can be either images or files. These attachments can be displayed or linked within the note that owns them.</p><p>This can be especially useful to include dependencies for your <a href=\"#root/_help_CdNpE2pqjmI6\">scripts</a>. The <a class=\"reference-link\" href=\"#root/_help_R7abl2fc6Mxi\">Weight Tracker</a> shows how to use <a href=\"https://chartjs.org/\">chartjs</a> which is attached to the script note.</p><p>Each note exclusively owns its attachments, meaning attachments cannot be shared or linked from one note to another. If an attachment link is copied to a different note, the attachment itself is duplicated, and the copies are managed independently thereafter.</p><p>Attachments, especially image files, are the recommended method for embedding visuals in notes. It is important to link image attachments within the text of the owning note; otherwise, they will be automatically deleted after a configurable timeout period if not referenced.</p><h2>Types of attachments</h2><p>There are two different types of attachment:</p><ul><li><em>User content</em>, representing files or images that are uploaded and part of the content of the note.</li><li><em>System attachments</em> which are used internally by Trilium and can be of multiple types, including:<ul><li><a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> to store information about views such as the column information for the <a class=\"reference-link\" href=\"#root/_help_CtBQqbwXDx1w\">Kanban Board</a>.</li><li>Icons and cover images for <a class=\"reference-link\" href=\"#root/_help_UmgZAfcltxkS\">Link Previews</a>.</li><li>Debug information for some importers such as <a class=\"reference-link\" href=\"#root/_help_GnhlmrATVqcH\">Microsoft OneNote</a> (only if the debug flag was enabled at import time).</li></ul></li></ul><p>The system attachments are displayed at the end of the attachments list, in a dedicated section (<em>Generated by Trilium</em>).</p><h2>Attaching files from a text note</h2><p>To attach files to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note and embed them in its content, press the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button in the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>, next to the <span class=\"tn-icon cke cke-image-upload\"></span>image upload button, and select one or more files (see <em>Embedding an attachment</em> below). The arrow beside the button lists the same action as <em>Attach and embed file</em>, followed by <em>Attach file as a link</em>, which links the files instead. Both actions are also available as <em>Attach file as a link</em> and <em>Attach and embed file</em> in the <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>.</p><p>When files are attached as links:</p><ul><li>Each file becomes an attachment of the note, and a link to it is inserted at the cursor. Several files produce several links, separated by a space.</li><li>While a file uploads, its link shows the file name and a toast shows the progress.</li><li>Pictures appear as links rather than images, and are attached exactly as they are, without being compressed. To display a picture in the text, use the image upload button instead (see <a class=\"reference-link\" href=\"#root/_help_mT0HEkOsz6i1\">Images</a>).</li></ul><p>Dragging a file that is not a picture from the file explorer onto the text also attaches it and inserts a link to it.</p><h2>Acting on an attachment link</h2><p>Right-clicking a link to an attachment shows the ways to open it, followed by actions on the attachment: opening it externally, downloading it, uploading a new revision, renaming or deleting it, and converting it into a note.</p><p>Links follow changes to their attachment: renaming it updates the title they show, and deleting it removes them from the text notes open for editing at that moment. Converting it into a note turns its links into links to the new note.</p><h2>Embedding an attachment</h2><p>An attachment can be shown in the text instead of linked, the way <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a> shows a note: a picture is displayed, a PDF, a video or a document is previewed, and a code or text file is shown with syntax highlighting. An embedded code file can also be edited in place (see <em>Editing an include in place</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>).</p><ul><li>To attach files and embed them straight away, press the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button. Each file gets an embed of its own, which shows the file name while the file uploads.</li><li>To embed an attachment that is already linked, right-click a link to it in a text note being edited and select <em>Convert link to an embed</em>, at the end of the menu.</li><li>A drawing canvas, inserted with <span class=\"tn-icon bx bx-pen\"></span><em>Drawing canvas</em> in the <span class=\"tn-icon cke cke-plus\"></span><em>Insert</em> menu, is an embed of a <code>Canvas.excalidraw</code> attachment that can be drawn on in place. An attached Excalidraw file (<code>.excalidraw</code>) is embedded as a drawing canvas too (see <em>Drawing canvases</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>).</li><li>An embed gets the box size that suits the attachment, as a new included note does (see <em>Box sizes</em> there). To change its size, select the embed and use the box size menu in its toolbar, or the <em>Size</em> submenu of its <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span><em>More actions</em> menu. A <em>Small</em>, <em>Medium</em> or <em>Expandable</em> embed can also be resized by dragging its handles (see <em>Resizing</em> there).</li><li>An embed can have a caption, as an included note can (see <em>Caption</em> there).</li><li>To show only the attachment, select the embed and press the <span class=\"tn-icon bx bx-window-alt\"></span> (<em>Show title)</em> button in its toolbar, as for an included note (see <em>Title</em> there).</li><li>To open the attachment in a new tab, press the <span class=\"tn-icon bx bx-link-external\"></span> (<em>Open in new tab)</em> button at the end of the embed's title.</li><li>An embed of size <em>Tiny</em> shows only the title of the attachment and its size, in a single row. Its buttons are <span class=\"tn-icon bx bx-file-find\"></span><em>Open externally</em> and <span class=\"tn-icon bx bx-download\"></span><em>Download</em>.</li><li>To show an embed of size <em>Medium</em> or <em>Full</em> on the whole screen, press the <span class=\"tn-icon bx bx-fullscreen\"></span> (<em>Fullscreen)</em> button at the end of its title. To return, press <span class=\"tn-icon bx bx-exit\"></span> (<em>Exit fullscreen)</em> in the top-right corner, or <kbd>Esc</kbd>.</li><li>To turn the embed back into a link, select it and press the <span class=\"tn-icon cke cke-link\"></span><em>Convert to link</em> button in its toolbar. <em>Convert to link</em> also ends the menu that right-clicking the title row of the embed or pressing its <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span><em>More actions</em> button opens.</li></ul><p>An embed follows its attachment like a link does. Converting the attachment into a note turns the embed into an included note. In a <a href=\"#root/_help_R9pX4DGra2Vt\">shared note</a>, an embedded picture is displayed with its caption, a drawing canvas as a picture of the drawing, and any other attachment, or a picture in a <em>Tiny</em> embed, appears as a link to download it.</p><h2>Converting notes to attachments</h2><p><a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a> notes can be easily converted to attachments of the parent note.</p><p>To do so:</p><ul><li>For a single note, press the context menu from the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and select <em>Convert into attachment</em>.</li><li>For multiple notes, select the given notes in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, right click → Advanced → <em>Convert to attachment…</em>.</li></ul><h2>Attachment previews</h2><p>Attachments share the same content preview for images, videos, PDFs, etc. as the <a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a> note type.</p>",+ "_help_0vhv7lsOLy82": "<p>A <a href=\"#root/_help_BFs8mudNFgCS\">note</a> in Trilium can <em>own</em> one or more attachments, which can be either images or files. These attachments can be displayed or linked within the note that owns them.</p><p>This can be especially useful to include dependencies for your <a href=\"#root/_help_CdNpE2pqjmI6\">scripts</a>. The <a class=\"reference-link\" href=\"#root/_help_R7abl2fc6Mxi\">Weight Tracker</a> shows how to use <a href=\"https://chartjs.org/\">chartjs</a> which is attached to the script note.</p><p>Each note exclusively owns its attachments, meaning attachments cannot be shared or linked from one note to another. If an attachment link is copied to a different note, the attachment itself is duplicated, and the copies are managed independently thereafter.</p><p>Attachments, especially image files, are the recommended method for embedding visuals in notes. It is important to link image attachments within the text of the owning note; otherwise, they will be automatically deleted after a configurable timeout period if not referenced.</p><h2>Types of attachments</h2><p>There are two different types of attachment:</p><ul><li><em>User content</em>, representing files or images that are uploaded and part of the content of the note.</li><li><em>System attachments</em> which are used internally by Trilium and can be of multiple types, including:<ul><li><a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> to store information about views such as the column information for the <a class=\"reference-link\" href=\"#root/_help_CtBQqbwXDx1w\">Kanban Board</a>.</li><li>Icons and cover images for <a class=\"reference-link\" href=\"#root/_help_UmgZAfcltxkS\">Link Previews</a>.</li><li>Debug information for some importers such as <a class=\"reference-link\" href=\"#root/_help_GnhlmrATVqcH\">Microsoft OneNote</a> (only if the debug flag was enabled at import time).</li></ul></li></ul><p>The system attachments are displayed at the end of the attachments list, in a dedicated section (<em>Generated by Trilium</em>).</p><h2>Attaching files from a text note</h2><p>To attach files to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note and embed them in its content, press the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button in the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>, next to the <span class=\"tn-icon cke cke-image-upload\"></span>image upload button, and select one or more files (see <em>Embedding an attachment</em> below). The arrow beside the button lists the same action as <em>Attach and embed file</em>, followed by <em>Attach file as a link</em>, which links the files instead. Both actions are also available as <em>Attach file as a link</em> and <em>Attach and embed file</em> in the <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>.</p><p>When files are attached as links:</p><ul><li>Each file becomes an attachment of the note, and a link to it is inserted at the cursor. Several files produce several links, separated by a space.</li><li>While a file uploads, its link shows the file name and a toast shows the progress.</li><li>Pictures appear as links rather than images, and are attached exactly as they are, without being compressed. To display a picture in the text, use the image upload button instead (see <a class=\"reference-link\" href=\"#root/_help_mT0HEkOsz6i1\">Images</a>).</li></ul><p>Dragging a file that is not a picture from the file explorer onto the text also attaches it and inserts a link to it.</p><h2>Acting on an attachment link</h2><p>Right-clicking a link to an attachment shows the ways to open it, followed by actions on the attachment: opening it externally, downloading it, uploading a new revision, renaming or deleting it, and converting it into a note.</p><p>Links follow changes to their attachment: renaming it updates the title they show, and deleting it removes them from the text notes open for editing at that moment. Converting it into a note turns its links into links to the new note.</p><h2>Embedding an attachment</h2><p>An attachment can be shown in the text instead of linked, the way <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a> shows a note: a picture is displayed, a PDF, a video or a document is previewed, a code or text file is shown with syntax highlighting, and a Markdown file such as a <code>.md</code> file is shown rendered. An embedded code file can also be edited in place (see <em>Editing an include in place</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>), and an embedded Markdown file shows its source, its rendering or both, as an included Markdown note does (see <em>Included Markdown</em> there).</p><ul><li>To attach files and embed them straight away, press the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button. Each file gets an embed of its own, which shows the file name while the file uploads.</li><li>To embed an attachment that is already linked, right-click a link to it in a text note being edited and select <em>Convert link to an embed</em>, at the end of the menu.</li><li>A drawing canvas, inserted with <span class=\"tn-icon bx bx-pen\"></span><em>Drawing canvas</em> in the <span class=\"tn-icon cke cke-plus\"></span><em>Insert</em> menu, is an embed of a <code>Canvas.excalidraw</code> attachment that can be drawn on in place. An attached Excalidraw file (<code>.excalidraw</code>) is embedded as a drawing canvas too (see <em>Drawing canvases</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>).</li><li>An embed gets the box size that suits the attachment, as a new included note does (see <em>Box sizes</em> there). To change its size, select the embed and use the box size menu in its toolbar, or the <em>Size</em> submenu of its <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span><em>More actions</em> menu. A <em>Small</em>, <em>Medium</em> or <em>Expandable</em> embed can also be resized by dragging its handles (see <em>Resizing</em> there).</li><li>An embed can have a caption, as an included note can (see <em>Caption</em> there).</li><li>To show only the attachment, select the embed and press the <span class=\"tn-icon bx bx-window-alt\"></span> (<em>Show title)</em> button in its toolbar, as for an included note (see <em>Title</em> there).</li><li>To open the attachment in a new tab, press the <span class=\"tn-icon bx bx-link-external\"></span> (<em>Open in new tab)</em> button at the end of the embed's title.</li><li>An embed of size <em>Tiny</em> shows only the title of the attachment and its size, in a single row. Its buttons are <span class=\"tn-icon bx bx-file-find\"></span><em>Open externally</em> and <span class=\"tn-icon bx bx-download\"></span><em>Download</em>.</li><li>To show an embed of size <em>Medium</em> or <em>Full</em> on the whole screen, press the <span class=\"tn-icon bx bx-fullscreen\"></span> (<em>Fullscreen)</em> button at the end of its title. To return, press <span class=\"tn-icon bx bx-exit\"></span> (<em>Exit fullscreen)</em> in the top-right corner, or <kbd>Esc</kbd>.</li><li>To turn the embed back into a link, select it and press the <span class=\"tn-icon cke cke-link\"></span><em>Convert to link</em> button in its toolbar. <em>Convert to link</em> also ends the menu that right-clicking the title row of the embed or pressing its <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span><em>More actions</em> button opens.</li></ul><p>An embed follows its attachment like a link does. Converting the attachment into a note turns the embed into an included note. In a <a href=\"#root/_help_R9pX4DGra2Vt\">shared note</a>, an embedded picture is displayed with its caption, a drawing canvas as a picture of the drawing, and any other attachment, or a picture in a <em>Tiny</em> embed, appears as a link to download it.</p><h2>Converting notes to attachments</h2><p><a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a> notes can be easily converted to attachments of the parent note.</p><p>To do so:</p><ul><li>For a single note, press the context menu from the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> and select <em>Convert into attachment</em>.</li><li>For multiple notes, select the given notes in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, right click → Advanced → <em>Convert to attachment…</em>.</li></ul><h2>Attachment previews</h2><p>Attachments share the same content preview for images, videos, PDFs, etc. as the <a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a> note type. A Markdown attachment is previewed rendered, as a <a class=\"reference-link\" href=\"#root/_help_6RM1Q7ppFVoj\">Markdown</a> note is.</p>","_help_IakOLONlIfGI": "<h2>Motivation</h2><p>Trilium's core feature is the ability to structure your notes into hierarchical tree-like structure.</p><p>It is expected then that you'll have an elaborate and deep note hierarchy - each subtree will represent a more refined and specialized view of your knowledge base.</p><p>This is a pretty powerful approach, but it also carries a hidden assumption that each \"subtopic\" is \"owned\" by one parent. I'll illustrate this with an example - let's say my basic structure is this:</p><ul><li>Technology<ul><li>Programming<ul><li>Kotlin</li><li>JavaScript</li></ul></li><li>Operating systems<ul><li>Linux</li><li>Windows</li></ul></li></ul></li></ul><p>Now, I'm starting to learn about <a href=\"https://en.wikipedia.org/wiki/Bash_(Unix_shell)\">Bash</a> and would like to create notes related to this topic. But now I'm facing a problem of where to categorize this. The issue here is that Bash is both a programming language and a tool (shell) very much tied into Linux. It seems it belongs to both of these, I can't (and don't want to) choose one over the other.</p><h2>Solution</h2><p>The solution to the problem shown above is to allow notes to have multiple parents.</p><p>I call these \"clones\", but that is a bit misleading - there's no original and cloned note - the notes in both of the parents categories are identical.</p><p>Another misleading thing about \"cloning\" is that it suggests that a copy of the note has been made. That's not really true, the note itself stays in just one original, it is just referenced in multiple places in the tree hierarchy. So changing it in one category changes it in all the others, because they're all the same note.</p><p>Here's the final structure with cloning:</p><ul><li>Technology<ul><li>Programming<ul><li>Kotlin</li><li>JavaScript</li><li>Bash<ul><li>some sub-notes ...</li></ul></li></ul></li><li>Operating systems<ul><li>Linux<ul><li>Bash<ul><li>some sub-notes ...</li></ul></li></ul></li><li>Windows</li></ul></li></ul></li></ul><p>So now the \"Bash\" subtree appears on multiple locations in the hierarchy. Both the Bash subtrees are the same and contain the same sub-categories and notes.</p><h3>Demo</h3><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Cloning%20Notes_create-clone.gif\"></p><p>In the demo, you can see how a clone can be created using the context menu. It's possible to do this also using the Add Link dialog or with <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> <a href=\"#root/_help_A9Oc6YKKc65v\">keyboard shortcuts</a>.</p><p>You can view the list of all available clones:</p><ul><li>In the <a class=\"reference-link\" href=\"#root/_help_AlJ73vBCjWDw\">Status bar</a>, by looking for the <span class=\"tn-icon bx bx-directions\"></span> icon.</li><li>In the <a class=\"reference-link\" href=\"#root/_help_KRlZFoIH0j6p\">Connections tab</a> of the <a class=\"reference-link\" href=\"#root/_help_RnaPdbciOfeq\">Right Sidebar</a>, by looking at the <em>Note paths</em> section.</li></ul><p>Titles of cloned notes in the tree view have an asterisk to the right to easily see that the note is also placed into some other location.</p><h2>Deleting notes/clones</h2><p>With clones, it might not be immediately obvious how deleting works.</p><p>If you try to delete a note, it works like this:</p><ol><li>if the note has multiple clones, delete just this clone and leave the actual note (and its other clones) as it is.</li><li>if this note doesn't have any other clones, delete the note<ul><li>Run the whole process starting with 1. on all note's children notes</li></ul></li></ol>","_help_TBwsyfadTA18": "<p>Since a single note can appear into multiple places in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> via a process called <a class=\"reference-link\" href=\"#root/_help_IakOLONlIfGI\">Cloning Notes</a>, it's recommended to choose a generalized name that fits into all locations instead of something more specific to avoid confusion.</p><p>In some cases this isn't possible so Trilium provides \"branch prefixes\", which is shown before the note name in the tree and as such provides a specific kind of context.</p><p>The prefix is location-specific, so it's displayed only in the note tree.</p>","_help_bwg0e8ewQMak": "<p>Trilium is designed to store a wide variety of data, including sensitive information such as personal journals, credentials, or confidential documents. To safeguard this type of content, Trilium offers the option to protect notes, which involves the following measures:</p><ul><li><strong>Encryption:</strong> Protected notes are encrypted using a key derived from your password. This ensures that without the correct password, protected notes remain indecipherable. Even if someone gains access to your Trilium <a href=\"#root/_help_wX4HbRucYSDD\">database</a>, they won't be able to read your encrypted notes.</li><li><strong>Time-limited access:</strong> To access protected notes, you must first enter your password, which decrypts the note for reading and writing. However, after a specified period of inactivity (10 minutes by default), the note is unloaded from memory, requiring you to re-enter your password to access it again.<ul><li>The session timeout is extended automatically while you're interacting with the protected note, so if you're actively editing, the session remains open. However, if you switch to an unprotected note, the session timer starts, and the session expires after 10 minutes of inactivity unless you return to the protected notes.</li></ul></li><li><strong>Protection scope:</strong> Protected notes ensure the confidentiality of their content and partially their integrity. While unauthorized users cannot read or edit protected notes, they can still delete or move them outside of the protected session.</li></ul><h2>Using Protected Notes</h2><p>By default, notes are unprotected. To protect a note, simply click on the shield icon next to the note's title, as shown here:</p><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Notes/Protected%20Notes_protecting-note.gif\" alt=\"example animation of unlocking protected notes\"></p><h2>What is Encrypted?</h2><p>Trilium encrypts the data within protected notes but not their metadata. Specifically:</p><p><strong>Encrypted:</strong></p><ul><li>Note title</li><li>Note content</li><li>Images</li><li>File attachments</li></ul><p><strong>Not encrypted:</strong></p><ul><li>Note structure (i.e., it remains visible that there are protected notes)</li><li>Metadata, such as the last modified date</li><li><a href=\"#root/_help_zEY4DaJG4YT5\">Attributes</a></li></ul><h2>Encryption Details</h2><p>The following steps outline how encryption and decryption work in Trilium:</p><ol><li>The user enters a password.</li><li>The password is passed through the <a href=\"https://en.wikipedia.org/wiki/Scrypt\">scrypt</a> algorithm along with a \"password verification\" <a href=\"https://en.wikipedia.org/wiki/Salt_(cryptography)\">salt</a> to confirm that the password is correct.</li><li>The password is then processed again through scrypt with an \"encryption\" salt, which generates a hash.<ul><li>Scrypt is used for <a href=\"https://en.wikipedia.org/wiki/Key_stretching\">key stretching</a> to make the password harder to guess.</li></ul></li><li>The generated hash is used to decrypt the actual <em>data encryption key</em>.<ul><li>The data encryption key is encrypted using <a href=\"https://en.wikipedia.org/wiki/Advanced_Encryption_Standard\">AES-128</a> with a random <a href=\"https://en.wikipedia.org/wiki/Initialization_vector\">IV</a>.</li><li>The data encryption key is randomly generated during the <a href=\"#root/_help_wX4HbRucYSDD\">database</a> initialization and remains constant throughout the document’s lifetime. When the password is changed, only this key is re-encrypted.</li></ul></li><li>The data encryption key is then used to decrypt the actual content of the note, including its title and body.<ul><li>The encryption algorithm used is AES-128 with <a href=\"https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation\">CBC mode</a>, where a unique IV is generated for each encryption operation and stored with the cipher text.</li></ul></li></ol><h2>Sharing Protected Notes</h2><p>Protected notes cannot be shared in the same way as regular notes. Their encryption ensures that only authorized users with the correct password can access them.</p>",@@ -134,7 +134,7 @@"_help_0Ofbk1aSuVRu": "<figure class=\"image image-style-align-right image_resized\" style=\"width:50.47%;\"><img style=\"aspect-ratio:880/553;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Images/Image%20references_image.png\" width=\"880\" height=\"553\"></figure><p>Image references are an easy way to embed the preview of another note type into a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note.</p><h2>Supported note types</h2><ul><li><a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a></li><li><a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a></li><li><a class=\"reference-link\" href=\"#root/_help_gBbsAeiuUxI5\">Mind Map</a></li></ul><h2>Steps</h2><ol><li>Go to one of the supported notes (listed above) and look for the <span class=\"tn-icon bx bx-copy\"></span> button in the <a class=\"reference-link\" href=\"#root/_help_1P8QXI5edXNd\">Note buttons</a> area.</li><li>Go to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note and use the Paste function to insert the reference to that note.</li></ol><h2>Interaction</h2><ul><li>Double-clicking an image reference from a text note will automatically open the target note.</li><li>Clicking an image reference while <kbd>Ctrl</kbd> is pressed will open the target note in a new tab.</li><li>Modifying the target note should also update the image reference. If that doesn't happen, consider <a class=\"reference-link\" href=\"#root/_help_s8alTXmpFR61\">Refreshing the application</a>.</li></ul>","_help_VRoP0g1uHHc2": "<figure class=\"image image-style-align-center image_resized\" style=\"width:76.29%;\"><img style=\"aspect-ratio:1479/865;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/In-editor%20AI%20assistant_image.png\" width=\"1479\" height=\"865\"></figure><p>The AI assistant works on the text you are already writing: select a passage and have it rewritten, translated or turned into a table, or ask for new content at the cursor. Unlike the <a href=\"#root/_help_LrKznOtw9cQD\">AI chat</a>, it does not open a conversation window, the result is previewed in place and only enters the note when you accept it.</p><h2>Requirements</h2><p>The assistant is only available once at least one provider is configured in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em>, with at least one model selected for it. Until then the toolbar entry is not shown at all.</p><h2>Accessing the AI assistant</h2><p>To access the AI assistant:</p><ul><li>Look for the <span class=\"tn-icon cke cke-trilium-ai\"></span> button in the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>. Press the button itself to enter the <em>Ask AI</em> mode or press the arrow key next to it to access the quick commands and the model selection.</li><li>Look for <em>AI assistant</em> or any of the <em>AI</em>-prefixed quick commands in <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>.</li><li>Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>K</kbd>.</li><li>Select a text and choose the <em>AI assistant</em> option in the <a class=\"reference-link\" href=\"#root/_help_jcQVxzYybYgz\">Note contextual menu</a>.</li></ul><h2>What the assistant works on</h2><figure class=\"table\"><table><thead><tr><th>Situation</th><th>What is sent</th></tr></thead><tbody><tr><td>Text is selected</td><td>The selection.</td></tr><tr><td>Nothing is selected, and you pick a quick action</td><td>The paragraph the cursor is in.</td></tr><tr><td>Nothing is selected, and you type your own prompt</td><td>Nothing, the response is new content written at the cursor.</td></tr></tbody></table></figure><p>In all cases the assistant also sends the text before and after the target, so that the model can tell what it is writing into: asked to <em>Continue writing</em> or to summarize, a model that can only see the selected words is guessing at the document around them. This surrounding text is context only, it is never rewritten.</p><aside class=\"admonition important\"><p>That means a single run sends more than the passage you highlighted. See <a class=\"reference-link\" href=\"#root/_help_cRRrdZjgyhNc\">Privacy</a> for exactly what leaves your machine.</p></aside><h2>Quick actions</h2><p>The arrow beside the toolbar button opens a menu of ready-made instructions, grouped by what they do.</p><ul><li>The <em>Reformat</em> actions produce real Trilium content rather than plain text: <em>Diagram</em> inserts a Mermaid diagram, <em>Callout</em> an admonition, and <em>Collapsible</em> a collapsible block.</li><li>The <em>Translate</em> group lists the <a href=\"#root/_help_veGu4faJErEM\">content languages</a> you have enabled, or a predefined list if no content languages are set. It can be filled from within the editor, the last entry of the submenu opens the language configuration directly.</li></ul><p>Actions that need something to work on are greyed out when there is nothing to work on (for example an empty paragraph with no selection).</p><h2>Asking for something specific</h2><p>Choosing <em>Ask AI…</em> (<span class=\"tn-icon bx bx-message-square-dots\"></span>) opens a prompt where you can describe the change in your own words, for example: \"make this less formal\", \"add a row for 2024\", \"write an intro paragraph for this section\". Press <kbd>Enter</kbd> or the <span class=\"tn-icon cke cke-arrow-up\"></span> send button to run it.</p><p>Once a response arrives you can keep going in the same prompt, and the assistant treats it as a conversation rather than as a fresh request: after <em>Translate this to German</em>, asking for <em>make it shorter</em> shortens the German, not the original.</p><h2>Reviewing the result</h2><p>The response streams in as it is generated, and can be interrupted at any point by pressing the <em>Stop</em> (<span class=\"tn-icon cke cke-stop\"></span>) button; whatever arrived before that stays usable.</p><p>Nothing is written into the note until you say so. The review offers:</p><ul><li><em>Result</em>, which displays the response as it will be inserted.</li><li><em>Changes</em>, which displays an inline diff against the original, with insertions and deletions marked. When the model rewrote the passage rather than editing it, the review opens on <em>Result</em> instead: a diff of two texts with little in common is harder to read than the answer itself.</li><li><em>Try again</em> (<span class=\"tn-icon cke cke-refresh\"></span>), to re-run the same instruction.</li><li><em>Replace</em>, which substitutes the original passage</li><li><em>Insert below</em>, which keeps the original and adds the response after it.</li></ul><p>Trilium also reports the model that produced it, the tokens consumed and, for providers that report it, the price.</p><p>If you ask for a correction and there is nothing to correct, the assistant will indicate it instead of showing a blank diff.</p><h2>Choosing the model</h2><p>The bottom of the quick actions menu shows which model the assistant runs on, and lets you pick another from the models you selected in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>AI / LLM</em>, grouped by provider.</p><p>The model can also be changed while asking for something specific, or after the assistant has generated its response (i.e. if the response needs a better model).</p><p>This choice is separate from the model used by the chat, and is remembered across notes and devices. Left unset, the assistant follows the first configured provider.</p>","_help_mVEYwt20exhO": "<p><em>Quick actions</em> are a feature of the <a class=\"reference-link\" href=\"#root/_help_VRoP0g1uHHc2\">In-editor AI assistant</a> for <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes which automatically triggers an LLM suggestion based on a defined prompt. The built-in quick actions come with a predefined prompt, but it is also possible to define your own quick actions.</p><h2>Creating a custom quick action</h2><p>In the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>: </p><ol><li>Right-click the note where you want to place the quick action.</li><li>Select <em>Insert child note</em>.</li><li>Select <em>More</em> → <em>AI Quick Action</em>. The entry appears only when AI is enabled.</li></ol><p>Afterwards, simply type in the content of the note the desired prompt. The text can be formatted in the same manner as a normal text note and it will be passed to the LLM as Markdown.</p><p>The title of the note will become the title of the quick action.</p><p>Of note:</p><ul><li><a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes work too.</li><li>An empty note is ignored.</li><li><a class=\"reference-link\" href=\"#root/_help_MKmLg5x6xkor\">Archived Notes</a> are also excluded.</li></ul><h2>Using a quick action</h2><p>Once a quick action is defined, the action will appear under the <em>Quick Actions</em> dropdown in a group called <em>Custom</em>.</p>",- "_help_nBAXQFj20hS1": "<p>Text notes can \"include\" another note as a read-only widget or an interactive widget, depending on the type of note.</p><p>This can be useful for e.g. including a dynamically generated chart (from scripts & \"render HTML\" note) or other more advanced use cases.</p><h2>Including a note</h2><p>In the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>, look for the <span class=\"tn-icon cke cke-trilium-note\"></span> button. There is also a keyboard shortcut defined for it but it is not allocated by default.</p><p>To include a note that is already linked, right-click a reference link to it in a text note being edited and select <em>Convert link to an included note</em>, at the end of the menu. The include gets the box size that suits the note, as one added from the button does.</p><p>An <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> can be included the same way, from the context menu of a link to it (see <em>Embedding an attachment</em> there).</p><p>A link to blocks of a text note is converted the same way, with <em>Convert link to note excerpt</em>, and the include then shows only those blocks. See <a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>.</p><h2>Box sizes</h2><p>The box size sets how much of the included note is shown.</p><ul><li><em>Tiny</em> shows a single row instead of the content: the note's icon, its title with the path to the note above it, and buttons to act on the note. The included note is never rendered, so wherever the note is shown outside the editor, such as in print, in a tooltip or on a shared page, a <em>Tiny</em> include appears as a link to the included note.</li><li><em>Small</em> and <em>Medium</em> show the content in a box of limited height. Text scrolls inside the box, while a picture, a diagram or a video is scaled down to fit it.</li><li><em>Full</em> shows the whole content.</li><li><em>Expandable</em> shows only the title until its <span class=\"tn-icon bx bx-chevron-right\"></span> arrow is pressed. In a read-only note, a click anywhere on the title row other than its buttons and link expands or collapses it as well.</li></ul><p>A new include gets the size that suits what it shows:</p><ul><li><em>Tiny</em> for a note or an attachment that has no preview, such as a relation map or an archive.</li><li><em>Small</em> for audio.</li><li><em>Full</em> for a code note or a code file, such as a <code>.js</code>, <code>.py</code> or <code>.txt</code> attachment, and for an excerpt of the blocks of a text note.</li><li><em>Medium</em> for anything else.</li></ul><p>The dialog that includes a note selects that size once the note is picked, and you can choose another one there. To change the size later, select the include and use the <em>Box size</em> menu in its toolbar, or the <em>Size</em> submenu of its <em>More actions</em> menu.</p><h2>Resizing</h2><p>A <em>Small</em>, <em>Medium</em> or <em>Expandable</em> include can be resized to any width and height. A <em>Tiny</em> or <em>Full</em> include always fits its content.</p><ul><li>To resize an include, select it and drag the handle in its bottom-right corner. To change only the width or only the height, drag the middle of its right or bottom edge instead, where a touch screen shows a handle too. In right-to-left text, the handle is in the bottom-left corner and the width changes from the left edge.</li><li>Resizing works with a mouse, a pen or a finger.</li><li>While the height changes, moving the handle near the top or the bottom of the note scrolls the note.</li><li>An include narrower than the note is centered, so changing its width moves both of its sides. Making it as wide as the note returns it to the full width.</li><li>To cancel a resize, press <kbd>Esc</kbd> before releasing the handle.</li><li>To reset the size, double-click the corner handle, or double-tap it on a touch screen. Double-clicking the right or bottom edge resets only the width or the height.</li><li>Choosing a box size resets the height. Choosing <em>Tiny</em> or <em>Full</em> resets the width too.</li><li>While an <em>Expandable</em> include is collapsed, only its width can be changed.</li></ul><h2>Caption</h2><p>An include can have a caption, shown centered at the bottom of its box. The caption is part of the text note, so it can be formatted like the rest of the text, for example in bold or with a link.</p><ul><li>To add a caption, select the include, press the <span class=\"tn-icon cke cke-caption\"></span> <em>Toggle caption on</em> button in its toolbar and type the caption.</li><li>To remove the caption, press the same button again. Pressing it once more brings back the text it had, as long as the note stays open.</li><li>A <em>Tiny</em> include has no caption. Switching an include to <em>Tiny</em> removes its caption, and switching it back to a larger size restores the caption, as long as the note stays open.</li><li>An <em>Expandable</em> include shows its caption under the title while the content is collapsed, and under the content once it is expanded.</li></ul><h2>Title</h2><p>The title row of an include links to the included note and holds its buttons. To show only the content, select the include and press the <span class=\"tn-icon bx bx-window-alt\"></span> <em>Show title</em> button in its toolbar. Pressing it again shows the title.</p><ul><li>While the title is hidden, the <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> button in the toolbar of the include opens the menu of the included note.</li><li>A <em>Tiny</em> or <em>Expandable</em> include always shows its title, and its toolbar has no <em>Show title</em> button.</li></ul><h2>Opening an included note</h2><p>To open an included note in a new tab, press the <span class=\"tn-icon bx bx-link-external\"></span> <em>Open in new tab</em> button at the end of its title. An embedded attachment has the same button.</p><p>The <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span> <em>More actions</em> button at the end of the title row opens the same menu as right-clicking anywhere on the title row: the other places to open the note in and, for an embedded attachment, the actions on the attachment.</p><p>In a note being edited, the menu also has the commands of the include's toolbar: the <em>Size</em> submenu, <em>Show title</em> and <em>Show caption</em>, each checked while it is in effect, and <em>Convert to link</em> at the end. A drawing canvas, an included text or code note and an embedded code file also have <em>Editable</em>, above <em>Size</em>. For an embedded attachment they follow its first group of actions; for an included note they end the menu.</p><p>To show an include of size <em>Medium</em> or <em>Full</em> on the whole screen, press the <span class=\"tn-icon bx bx-fullscreen\"></span> <em>Fullscreen</em> button at the end of its title. An excerpt of the blocks of a note has an <span class=\"tn-icon bx bx-pencil\"></span> <em>Edit excerpt</em> button there instead; see <a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>. To return, press <span class=\"tn-icon bx bx-exit\"></span> <em>Exit fullscreen</em> in the top-right corner, or <kbd>Esc</kbd>.</p><p>A <em>Tiny</em> include has these buttons instead, followed by the same <em>More actions</em> button:</p><ul><li>For a note, <span class=\"tn-icon bx bx-edit\"></span> <em>Quick edit</em> opens the note in <a class=\"reference-link\" href=\"#root/_help_ZjLYv08Rp3qC\">Quick edit</a>, and <span class=\"tn-icon bx bx-link-external\"></span> <em>Open in new tab</em> opens it in a new tab.</li><li>For an embedded attachment, <span class=\"tn-icon bx bx-file-find\"></span> <em>Open externally</em> opens the file in another application, and <span class=\"tn-icon bx bx-download\"></span> <em>Download</em> downloads it. The size of the file is shown under its title.</li></ul><h2>Converting an include to a link</h2><p>To replace an include with a link to the included note, select it and press the <span class=\"tn-icon cke cke-link\"></span> <em>Convert to link</em> button in its toolbar, or choose <em>Convert to link</em> at the end of its <em>More actions</em> menu. An embedded attachment turns into a link to the attachment the same way.</p><h2>Included notes in the share functionality</h2><p>If a <a href=\"#root/_help_R9pX4DGra2Vt\">shared note</a> contains one or more included notes, they will be displayed in the content of the note as if they were part of the note itself. The caption of an include is shown under the included content. A <em>Tiny</em> include is shown as a link to the included note instead, and so is an include that would show a note already shown around it, such as a note that includes itself. The same goes for a printed or exported note.</p><p>For this to work, the included notes must also be shared, otherwise they will not be shown. However, the included notes can still be hidden from the note tree via <code>#shareHiddenFromTree</code>.</p><h2>Interactive notes</h2><p>Since v0.104.0, included notes might become interactive depending on their note type:</p><ul><li><a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> (e.g. <a class=\"reference-link\" href=\"#root/_help_81SGnPGMk7Xc\">Geo Map</a>) will render fully interactive, including creating new notes.</li><li><a class=\"reference-link\" href=\"#root/_help_m523cpzocqaD\">Saved Search</a> will also display the results.</li><li><a class=\"reference-link\" href=\"#root/_help_1vHRoWCEjj0L\">Web View</a> provides an interactive preview of the website.</li></ul><h2>Included images</h2><p>An included image, whether an image note or an image attachment, is shown in the image viewer, which zooms and pans it:</p><ul><li>To zoom, press the <span class=\"tn-icon bx bx-plus-circle\"></span> <em>Zoom in</em> and <span class=\"tn-icon bx bx-minus-circle\"></span> <em>Zoom out</em> buttons in the bottom-right corner of the image, or pinch on a touch screen. The percentage between them resets the zoom.</li><li>To zoom with the mouse wheel, click the image first. Until then, the mouse wheel scrolls the note.</li><li>To pan an image that is zoomed in, drag it. At its fitted size, dragging the image on a touch screen scrolls the note.</li><li>To return to the fitted size, double-click the image.</li></ul><p>In a <em>Small</em> or <em>Medium</em> box, the image is scaled down to fit the height of the box. In fullscreen, it fits the screen.</p><h2>Editing an include in place</h2><p>An included text note, an included code note and an embedded code file such as a <code>.js</code>, <code>.py</code> or <code>.txt</code> attachment can be edited without leaving the note that includes them. A code note or file is shown with syntax highlighting until then.</p><ul><li>To edit, select the include and turn on the <span class=\"tn-icon bx bx-edit-alt\"></span> <em>Editable</em> button at the start of its toolbar, or check <em>Editable</em> in its <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> menu. Turn <em>Editable</em> off to return to the preview.</li><li>While <em>Editable</em> is on, the arrow keys move the caret into the include and back out, as through the rest of the text. Entering from above or from the left puts the caret at the start of the include, and entering from below or from the right puts it at the end. A collapsed <em>Expandable</em> include is skipped.</li><li>While an included text note has the focus, the formatting toolbar applies to it. The notes it includes in turn stay read-only.</li><li>Code is edited in the same code editor as a <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> note, with its theme, indentation and line wrapping settings.</li><li>The toolbar of an included code note or an embedded code file also has the language and indentation menus of the <a class=\"reference-link\" href=\"#root/_help_AlJ73vBCjWDw\">Status bar</a>, between <em>Editable</em> and the <em>Box size</em> menu: <em>Change language mode</em>, which shows the current language, and <em>Change tab width</em>, which shows the current indentation. <em>Re-indent content to</em> converts the code shown in the include, whether <em>Editable</em> is on or off.<ul><li>For an included note, the menus change the note, as they do in its own tab.</li><li>For an embedded code file, the menus change only how this include shows the file, and are saved with the note that includes it. The language replaces the one that the file name gives, and the <em>Use default</em> entries return to the indentation set in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Code Notes</em>. The file itself does not change, and other includes of it keep their own settings.</li></ul></li><li>The changes are saved as you type, to the included note or to the attachment, as they would be in its own tab.</li><li>An include of <a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a> edits only the referenced blocks.</li><li>Editing is not available in a <a href=\"#root/_help_CoFPLs3dRlXc\">read-only note</a>, for an included note marked <code>#readOnly</code>, or for an attachment of another note.</li><li><a class=\"reference-link\" href=\"#root/_help_McngOG2jbUWX\">Search in note</a> finds the text of included text and code notes among the results of the note around them, and replaces it while <em>Editable</em> is on.</li></ul><h2>Drawing canvases</h2><p>A drawing canvas is an Excalidraw canvas, like the one of a <a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a> note, drawn directly in the text note. It is not a note of its own: the drawing is kept in a <code>Canvas.excalidraw</code> <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> of the text note and is saved together with the text.</p><ul><li>To insert a drawing canvas, open the <span class=\"tn-icon cke cke-plus\"></span> <em>Insert</em> menu of the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a> and choose <span class=\"tn-icon bx bx-pen\"></span> <em>Drawing canvas</em>, above <em>Mermaid diagram</em>. It is also available as <em>Drawing canvas</em> in the <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>. The canvas is added empty and editable, in a <em>Medium</em> box with its title hidden, and takes the focus, ready for drawing.</li><li>To draw or write over an image, select the image and press the <span class=\"tn-icon bx bxs-pen\"></span> <em>Convert image to a drawing canvas</em> button of its toolbar. The image is replaced by an editable drawing canvas in a <em>Medium</em> box, with its title hidden and the focus in it. The image sits at its original size in the middle of the canvas, zoomed so that all of it shows, and is locked so that it cannot be selected or moved by accident. While it is locked, the canvas can be zoomed in on the image but not zoomed out past it or scrolled beyond its edges. To move or resize the image anyway, right-click it and choose <em>Unlock</em>. The caption of the image is kept, but not its alignment or link. Only an image on its own line can be converted, not one inside a paragraph. Undo brings the image back.</li><li>An Excalidraw file (<code>.excalidraw</code>) attached with the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button becomes a drawing canvas too, in a <em>Medium</em> box titled with the file name. It starts with <em>Editable</em> off, so the drawing shows but cannot be changed until <em>Editable</em> is turned on (see below).</li><li>To draw on a canvas that does not have the focus, click it first. Until then, touch gestures scroll the note. The canvas then has the tools, menus and keyboard shortcuts of a Canvas note. The toolbars, the menus and the properties of the selected shapes show only while the canvas has the focus, so elsewhere the drawing reads like a picture in the text.</li><li>The mouse wheel and the touchpad scroll the note over a canvas too, as over the text. To zoom, use the zoom buttons of the canvas toolbar; to move around the drawing, use the <span class=\"tn-icon bx bxs-hand\"></span> <em>Hand</em> tool. In fullscreen, the mouse wheel moves and zooms the drawing instead.</li><li>The canvas toolbar replaces the Excalidraw menu: <em>Export image</em>, <em>Find on canvas</em>, <em>Library</em> and <em>Help</em> are at the end of its <span class=\"tn-icon bx bx-category\"></span> <em>More tools</em> menu. In fullscreen, the Excalidraw menu shows again.</li><li>A new drawing has the background color of the note. A background chosen from the Excalidraw menu replaces it.</li><li>To protect a finished drawing from accidental changes, select it and turn off the <span class=\"tn-icon bx bx-edit-alt\"></span> <em>Editable</em> button at the start of its toolbar, or uncheck <em>Editable</em> in its <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> menu. The drawing then shows as a still picture, at the zoom and position it had, and can no longer be changed, zoomed or moved. To draw again, turn <em>Editable</em> back on.</li><li>The box sizes, resizing, the caption and the title work as for an included note, but the toolbar of a drawing leaves the box size, <em>Show title</em> and <em>Convert to link</em> to its <em>More actions</em> menu.</li><li>In the desktop layout, Excalidraw keeps its desktop interface however small the box is. In the mobile layout, a narrow or short box switches it to a compact interface. For more room, choose <em>Full</em>, or show the title and press <span class=\"tn-icon bx bx-fullscreen\"></span> <em>Fullscreen</em>.</li><li>Pictures added to the drawing are stored in the same attachment. A converted image is kept as an image attachment of the note instead, named with a generated code.</li><li>In a <a href=\"#root/_help_CoFPLs3dRlXc\">read-only note</a>, the drawing shows as a still picture too.</li><li>On a <a href=\"#root/_help_R9pX4DGra2Vt\">shared page</a>, the drawing is shown as a picture at its own size, whatever the size of its box, in light or dark colors to match the page. Each change to the drawing saves this picture as an SVG image attachment of the note, also named with a generated code.</li></ul><h3>Limitations</h3><ul><li>The Excalidraw shape library is not saved for a drawing canvas.</li><li>Outside the editor, for example in a tooltip, when printing or in the list of attachments, the drawing is shown as a picture.</li><li>A drawing has no picture for shared pages until its first change, except one converted from an image. Until then, for example for an attached <code>.excalidraw</code> file, a shared page shows a link to download the drawing instead.</li><li>In Safari, the picture of a drawing on a shared page follows the light or dark appearance of the system rather than the theme chosen on the page.</li><li>A copy of a drawing canvas pasted in the same note shares the drawing with the original, so a change to one shows in the other only after the note is opened again. A copy pasted in another note gets a drawing of its own.</li></ul>",+ "_help_nBAXQFj20hS1": "<p>Text notes can \"include\" another note as a read-only widget or an interactive widget, depending on the type of note.</p><p>This can be useful for e.g. including a dynamically generated chart (from scripts & \"render HTML\" note) or other more advanced use cases.</p><h2>Including a note</h2><p>In the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>, look for the <span class=\"tn-icon cke cke-trilium-note\"></span> button. There is also a keyboard shortcut defined for it but it is not allocated by default.</p><p>To include a note that is already linked, right-click a reference link to it in a text note being edited and select <em>Convert link to an included note</em>, at the end of the menu. The include gets the box size that suits the note, as one added from the button does.</p><p>An <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> can be included the same way, from the context menu of a link to it (see <em>Embedding an attachment</em> there).</p><p>A link to blocks of a text note is converted the same way, with <em>Convert link to note excerpt</em>, and the include then shows only those blocks. See <a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>.</p><h2>Box sizes</h2><p>The box size sets how much of the included note is shown.</p><ul><li><em>Tiny</em> shows a single row instead of the content: the note's icon, its title with the path to the note above it, and buttons to act on the note. The included note is never rendered, so wherever the note is shown outside the editor, such as in print, in a tooltip or on a shared page, a <em>Tiny</em> include appears as a link to the included note.</li><li><em>Small</em> and <em>Medium</em> show the content in a box of limited height. Text scrolls inside the box, while a picture, a diagram or a video is scaled down to fit it.</li><li><em>Full</em> shows the whole content.</li><li><em>Expandable</em> shows only the title until its <span class=\"tn-icon bx bx-chevron-right\"></span> arrow is pressed. In a read-only note, a click anywhere on the title row other than its buttons and link expands or collapses it as well.</li></ul><p>A new include gets the size that suits what it shows:</p><ul><li><em>Tiny</em> for a note or an attachment that has no preview, such as a relation map or an archive.</li><li><em>Small</em> for audio.</li><li><em>Full</em> for a code note or a code file, such as a <code>.js</code>, <code>.py</code> or <code>.txt</code> attachment, and for an excerpt of the blocks of a text note.</li><li><em>Medium</em> for anything else.</li></ul><p>The dialog that includes a note selects that size once the note is picked, and you can choose another one there. To change the size later, select the include and use the <em>Box size</em> menu in its toolbar, or the <em>Size</em> submenu of its <em>More actions</em> menu.</p><h2>Resizing</h2><p>A <em>Small</em>, <em>Medium</em> or <em>Expandable</em> include can be resized to any width and height. A <em>Tiny</em> or <em>Full</em> include always fits its content.</p><ul><li>To resize an include, select it and drag the handle in its bottom-right corner. To change only the width or only the height, drag the middle of its right or bottom edge instead, where a touch screen shows a handle too. In right-to-left text, the handle is in the bottom-left corner and the width changes from the left edge.</li><li>Resizing works with a mouse, a pen or a finger.</li><li>While the height changes, moving the handle near the top or the bottom of the note scrolls the note.</li><li>An include narrower than the note is centered, so changing its width moves both of its sides. Making it as wide as the note returns it to the full width.</li><li>To cancel a resize, press <kbd>Esc</kbd> before releasing the handle.</li><li>To reset the size, double-click the corner handle, or double-tap it on a touch screen. Double-clicking the right or bottom edge resets only the width or the height.</li><li>Choosing a box size resets the height. Choosing <em>Tiny</em> or <em>Full</em> resets the width too.</li><li>While an <em>Expandable</em> include is collapsed, only its width can be changed.</li></ul><h2>Caption</h2><p>An include can have a caption, shown centered at the bottom of its box. The caption is part of the text note, so it can be formatted like the rest of the text, for example in bold or with a link.</p><ul><li>To add a caption, select the include, press the <span class=\"tn-icon cke cke-caption\"></span> <em>Toggle caption on</em> button in its toolbar and type the caption.</li><li>To remove the caption, press the same button again. Pressing it once more brings back the text it had, as long as the note stays open.</li><li>A <em>Tiny</em> include has no caption. Switching an include to <em>Tiny</em> removes its caption, and switching it back to a larger size restores the caption, as long as the note stays open.</li><li>An <em>Expandable</em> include shows its caption under the title while the content is collapsed, and under the content once it is expanded.</li></ul><h2>Title</h2><p>The title row of an include links to the included note and holds its buttons. To show only the content, select the include and press the <span class=\"tn-icon bx bx-window-alt\"></span> <em>Show title</em> button in its toolbar. Pressing it again shows the title.</p><ul><li>While the title is hidden, the <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> button in the toolbar of the include opens the menu of the included note.</li><li>A <em>Tiny</em> or <em>Expandable</em> include always shows its title, and its toolbar has no <em>Show title</em> button.</li></ul><h2>Opening an included note</h2><p>To open an included note in a new tab, press the <span class=\"tn-icon bx bx-link-external\"></span> <em>Open in new tab</em> button at the end of its title. An embedded attachment has the same button.</p><p>The <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span> <em>More actions</em> button at the end of the title row opens the same menu as right-clicking anywhere on the title row: the other places to open the note in and, for an embedded attachment, the actions on the attachment.</p><p>In a note being edited, the menu also has the commands of the include's toolbar: the <em>Size</em> submenu, <em>Show title</em> and <em>Show caption</em>, each checked while it is in effect, and <em>Convert to link</em> at the end. A drawing canvas, an included text, code or Markdown note and an embedded code or Markdown file also have <em>Editable</em>, above <em>Size</em>. An included Markdown note and an embedded Markdown file also have <em>Source view</em>, <em>Split view</em> and <em>Preview</em> after <em>Editable</em>. For an embedded attachment they follow its first group of actions; for an included note they end the menu.</p><p>To show an include of size <em>Medium</em> or <em>Full</em> on the whole screen, press the <span class=\"tn-icon bx bx-fullscreen\"></span> <em>Fullscreen</em> button at the end of its title. An excerpt of the blocks of a note has an <span class=\"tn-icon bx bx-pencil\"></span> <em>Edit excerpt</em> button there instead; see <a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a>. To return, press <span class=\"tn-icon bx bx-exit\"></span> <em>Exit fullscreen</em> in the top-right corner, or <kbd>Esc</kbd>.</p><p>A <em>Tiny</em> include has these buttons instead, followed by the same <em>More actions</em> button:</p><ul><li>For a note, <span class=\"tn-icon bx bx-edit\"></span> <em>Quick edit</em> opens the note in <a class=\"reference-link\" href=\"#root/_help_ZjLYv08Rp3qC\">Quick edit</a>, and <span class=\"tn-icon bx bx-link-external\"></span> <em>Open in new tab</em> opens it in a new tab.</li><li>For an embedded attachment, <span class=\"tn-icon bx bx-file-find\"></span> <em>Open externally</em> opens the file in another application, and <span class=\"tn-icon bx bx-download\"></span> <em>Download</em> downloads it. The size of the file is shown under its title.</li></ul><h2>Converting an include to a link</h2><p>To replace an include with a link to the included note, select it and press the <span class=\"tn-icon cke cke-link\"></span> <em>Convert to link</em> button in its toolbar, or choose <em>Convert to link</em> at the end of its <em>More actions</em> menu. An embedded attachment turns into a link to the attachment the same way.</p><h2>Included notes in the share functionality</h2><p>If a <a href=\"#root/_help_R9pX4DGra2Vt\">shared note</a> contains one or more included notes, they will be displayed in the content of the note as if they were part of the note itself. The caption of an include is shown under the included content. A <em>Tiny</em> include is shown as a link to the included note instead, and so is an include that would show a note already shown around it, such as a note that includes itself. The same goes for a printed or exported note.</p><p>For this to work, the included notes must also be shared, otherwise they will not be shown. However, the included notes can still be hidden from the note tree via <code>#shareHiddenFromTree</code>.</p><h2>Interactive notes</h2><p>Since v0.104.0, included notes might become interactive depending on their note type:</p><ul><li><a class=\"reference-link\" href=\"#root/_help_GTwFsgaA0lCt\">Collections</a> (e.g. <a class=\"reference-link\" href=\"#root/_help_81SGnPGMk7Xc\">Geo Map</a>) will render fully interactive, including creating new notes.</li><li><a class=\"reference-link\" href=\"#root/_help_m523cpzocqaD\">Saved Search</a> will also display the results.</li><li><a class=\"reference-link\" href=\"#root/_help_1vHRoWCEjj0L\">Web View</a> provides an interactive preview of the website.</li></ul><h2>Included images</h2><p>An included image, whether an image note or an image attachment, is shown in the image viewer, which zooms and pans it:</p><ul><li>To zoom, press the <span class=\"tn-icon bx bx-plus-circle\"></span> <em>Zoom in</em> and <span class=\"tn-icon bx bx-minus-circle\"></span> <em>Zoom out</em> buttons in the bottom-right corner of the image, or pinch on a touch screen. The percentage between them resets the zoom.</li><li>To zoom with the mouse wheel, click the image first. Until then, the mouse wheel scrolls the note.</li><li>To pan an image that is zoomed in, drag it. At its fitted size, dragging the image on a touch screen scrolls the note.</li><li>To return to the fitted size, double-click the image.</li></ul><p>In a <em>Small</em> or <em>Medium</em> box, the image is scaled down to fit the height of the box. In fullscreen, it fits the screen.</p><h2>Editing an include in place</h2><p>An included text note, an included code note and an embedded code file such as a <code>.js</code>, <code>.py</code> or <code>.txt</code> attachment can be edited without leaving the note that includes them. A code note or file is shown with syntax highlighting until then. Included Markdown can be edited too, see <em>Included Markdown</em> below.</p><ul><li>To edit, select the include and turn on the <span class=\"tn-icon bx bx-edit-alt\"></span> <em>Editable</em> button at the start of its toolbar, or check <em>Editable</em> in its <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> menu. Turn <em>Editable</em> off to return to the preview.</li><li>While <em>Editable</em> is on, the arrow keys move the caret into the include and back out, as through the rest of the text. Entering from above or from the left puts the caret at the start of the include, and entering from below or from the right puts it at the end. A collapsed <em>Expandable</em> include is skipped.</li><li>While an included text note has the focus, the formatting toolbar applies to it. The notes it includes in turn stay read-only.</li><li>Code is edited in the same code editor as a <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> note, with its theme, indentation and line wrapping settings.</li><li>The toolbar of an included code note or an embedded code file also has the language and indentation menus of the <a class=\"reference-link\" href=\"#root/_help_AlJ73vBCjWDw\">Status bar</a>, between <em>Editable</em> and the <em>Box size</em> menu: <em>Change language mode</em>, which shows the current language, and <em>Change tab width</em>, which shows the current indentation. <em>Re-indent content to</em> converts the code shown in the include, whether <em>Editable</em> is on or off.<ul><li>For an included note, the menus change the note, as they do in its own tab.</li><li>For an embedded code file, the menus change only how this include shows the file, and are saved with the note that includes it. The language replaces the one that the file name gives, and the <em>Use default</em> entries return to the indentation set in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Code Notes</em>. The file itself does not change, and other includes of it keep their own settings.</li></ul></li><li>The changes are saved as you type, to the included note or to the attachment, as they would be in its own tab.</li><li>An include of <a class=\"reference-link\" href=\"#root/_help_klC3ilXa9kUE\">Block references</a> edits only the referenced blocks.</li><li>Editing is not available in a <a href=\"#root/_help_CoFPLs3dRlXc\">read-only note</a>, for an included note marked <code>#readOnly</code>, or for an attachment of another note.</li><li><a class=\"reference-link\" href=\"#root/_help_McngOG2jbUWX\">Search in note</a> finds the text of included text and code notes among the results of the note around them, and replaces it while <em>Editable</em> is on.</li></ul><h2>Included Markdown</h2><p>An included <a class=\"reference-link\" href=\"#root/_help_6RM1Q7ppFVoj\">Markdown</a> note and an embedded Markdown file, such as a <code>.md</code> attachment, are shown with the same three views as a Markdown note in its own tab (see <a class=\"reference-link\" href=\"#root/_help_SL5f1Auq7sVN\">Note types with split view</a>): <span class=\"tn-icon bx bx-code\"></span> <em>Source view</em>, <span class=\"tn-icon bx bxs-dock-left\"></span> <em>Split view</em> and <span class=\"tn-icon bx bx-show\"></span> <em>Preview</em>.</p><ul><li>To switch the view, press one of the three buttons in the title row of the include. In a note being edited, the toolbar of the include has the same buttons after <em>Editable</em>, and its <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> menu has them as <em>Source view</em>, <em>Split view</em> and <em>Preview</em>.</li><li>Until a view is chosen, the include shows the <em>Preview</em>, and the <em>Split view</em> while <em>Editable</em> is on.</li><li>To edit the Markdown, turn on <em>Editable</em> (see <em>Editing an include in place</em> above). The source is edited in the code editor of a Markdown note, and the preview follows the changes as you type. While <em>Editable</em> is off, the source can be read and copied but not changed.</li><li>As in a Markdown note, the preview scrolls along with the source and highlights the block where the cursor is, and <kbd>Ctrl</kbd>+<kbd>B</kbd>, <kbd>Ctrl</kbd>+<kbd>I</kbd>, <kbd>Ctrl</kbd>+<kbd>M</kbd> and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd> format the selection.</li><li>In a note being edited, the view is saved with the include, so two includes of the same note can show different views. In a <a href=\"#root/_help_CoFPLs3dRlXc\">read-only note</a>, the view can be changed too, until the note is opened again.</li><li>While the source shows, the include has the height of its box size, or the height it was resized to. A <em>Full</em> include gets a fixed height too, instead of fitting its content.</li><li><a class=\"reference-link\" href=\"#root/_help_McngOG2jbUWX\">Search in note</a> searches the source while it shows, and the preview otherwise.</li></ul><h2>Drawing canvases</h2><p>A drawing canvas is an Excalidraw canvas, like the one of a <a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a> note, drawn directly in the text note. It is not a note of its own: the drawing is kept in a <code>Canvas.excalidraw</code> <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> of the text note and is saved together with the text.</p><ul><li>To insert a drawing canvas, open the <span class=\"tn-icon cke cke-plus\"></span> <em>Insert</em> menu of the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a> and choose <span class=\"tn-icon bx bx-pen\"></span> <em>Drawing canvas</em>, above <em>Mermaid diagram</em>. It is also available as <em>Drawing canvas</em> in the <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>. The canvas is added empty and editable, in a <em>Medium</em> box with its title hidden, and takes the focus, ready for drawing.</li><li>To draw or write over an image, select the image and press the <span class=\"tn-icon bx bxs-pen\"></span> <em>Convert image to a drawing canvas</em> button of its toolbar. The image is replaced by an editable drawing canvas in a <em>Medium</em> box, with its title hidden and the focus in it. The image sits at its original size in the middle of the canvas, zoomed so that all of it shows, and is locked so that it cannot be selected or moved by accident. While it is locked, the canvas can be zoomed in on the image but not zoomed out past it or scrolled beyond its edges. To move or resize the image anyway, right-click it and choose <em>Unlock</em>. The caption of the image is kept, but not its alignment or link. Only an image on its own line can be converted, not one inside a paragraph. Undo brings the image back.</li><li>An Excalidraw file (<code>.excalidraw</code>) attached with the <span class=\"tn-icon cke cke-paper-clip\"></span><em>Attach file</em> button becomes a drawing canvas too, in a <em>Medium</em> box titled with the file name. It starts with <em>Editable</em> off, so the drawing shows but cannot be changed until <em>Editable</em> is turned on (see below).</li><li>To draw on a canvas that does not have the focus, click it first. Until then, touch gestures scroll the note. The canvas then has the tools, menus and keyboard shortcuts of a Canvas note. The toolbars, the menus and the properties of the selected shapes show only while the canvas has the focus, so elsewhere the drawing reads like a picture in the text.</li><li>The mouse wheel and the touchpad scroll the note over a canvas too, as over the text. To zoom, use the zoom buttons of the canvas toolbar; to move around the drawing, use the <span class=\"tn-icon bx bxs-hand\"></span> <em>Hand</em> tool. In fullscreen, the mouse wheel moves and zooms the drawing instead.</li><li>The canvas toolbar replaces the Excalidraw menu: <em>Export image</em>, <em>Find on canvas</em>, <em>Library</em> and <em>Help</em> are at the end of its <span class=\"tn-icon bx bx-category\"></span> <em>More tools</em> menu. In fullscreen, the Excalidraw menu shows again.</li><li>A new drawing has the background color of the note. A background chosen from the Excalidraw menu replaces it.</li><li>To protect a finished drawing from accidental changes, select it and turn off the <span class=\"tn-icon bx bx-edit-alt\"></span> <em>Editable</em> button at the start of its toolbar, or uncheck <em>Editable</em> in its <span class=\"tn-icon cke cke-three-vertical-dots\"></span> <em>More actions</em> menu. The drawing then shows as a still picture, at the zoom and position it had, and can no longer be changed, zoomed or moved. To draw again, turn <em>Editable</em> back on.</li><li>The box sizes, resizing, the caption and the title work as for an included note, but the toolbar of a drawing leaves the box size, <em>Show title</em> and <em>Convert to link</em> to its <em>More actions</em> menu.</li><li>In the desktop layout, Excalidraw keeps its desktop interface however small the box is. In the mobile layout, a narrow or short box switches it to a compact interface. For more room, choose <em>Full</em>, or show the title and press <span class=\"tn-icon bx bx-fullscreen\"></span> <em>Fullscreen</em>.</li><li>Pictures added to the drawing are stored in the same attachment. A converted image is kept as an image attachment of the note instead, named with a generated code.</li><li>In a <a href=\"#root/_help_CoFPLs3dRlXc\">read-only note</a>, the drawing shows as a still picture too.</li><li>On a <a href=\"#root/_help_R9pX4DGra2Vt\">shared page</a>, the drawing is shown as a picture at its own size, whatever the size of its box, in light or dark colors to match the page. Each change to the drawing saves this picture as an SVG image attachment of the note, also named with a generated code.</li></ul><h3>Limitations</h3><ul><li>The Excalidraw shape library is not saved for a drawing canvas.</li><li>Outside the editor, for example in a tooltip, when printing or in the list of attachments, the drawing is shown as a picture.</li><li>A drawing has no picture for shared pages until its first change, except one converted from an image. Until then, for example for an attached <code>.excalidraw</code> file, a shared page shows a link to download the drawing instead.</li><li>In Safari, the picture of a drawing on a shared page follows the light or dark appearance of the system rather than the theme chosen on the page.</li><li>A copy of a drawing canvas pasted in the same note shares the drawing with the original, so a change to one shows in the other only after the note is opened again. A copy pasted in another note gets a drawing of its own.</li></ul>","_help_CohkqWQC1iBv": "<p>Press the <span class=\"tn-icon cke cke-plus\"></span> button in the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a> to reveal special inserable items and blocks such as symbols, Math expressions and separators.</p><h2>Bookmarks</h2><p>See the dedicated <a class=\"reference-link\" href=\"#root/_help_oSuaNgyyKnhu\">Anchors</a> section.</p><h2>Emoji</h2><figure class=\"image image-style-align-right image_resized\" style=\"width:42.4%;\"><img style=\"aspect-ratio:366/410;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Insert%20buttons_plus.png\" width=\"366\" height=\"410\"></figure><p>This feature allows inserting Unicode emoji characters. Simply select a category and a desired emoji to insert it.</p><p>Emojis can also be searched by their English name and the skin tone can be selected via a combo box to the right.</p><p>There is also the possibility of inserting emojis directly by typing <code>:</code> followed by a name of an emoji, triggering the display of a list of emojis. Simply use the arrow keys to select one and press <kbd>Enter</kbd> or <kbd>Tab</kbd> to insert it.</p><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/1_Insert%20buttons_plus.png\" width=\"272\" height=\"187\"><h2>Symbols</h2><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:346/322;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/Insert%20buttons_image.png\" width=\"346\" height=\"322\"></figure><p>Pressing the <span class=\"tn-icon cke cke-special-characters\"></span> button will reveal a popup window displaying a list of characters that are generally more difficult to insert directly from the keyboard, such as a subset of emojis, quotation characters, etc.</p><p>Interaction:</p><ul><li>Click on a character to insert it at the current cursor position.</li><li>The window can be dragged around by the top bar where the title is, to avoid it getting in the way of the text.</li><li>Click on the <em>Category</em> selector to filter the characters.</li></ul><h2>Multicolumn layout</h2><p>See the dedicated <a class=\"reference-link\" href=\"#root/_help_wYDzQ1fBFgfT\">Multicolumn layout</a> page.</p><h2>Math equations</h2><p>See the dedicated <a class=\"reference-link\" href=\"#root/_help_YfYAtQBcfo5V\">Math Equations</a> page.</p><h2>Drawing canvas</h2><p>Choose <span class=\"tn-icon bx bx-pen\"></span> <em>Drawing canvas</em> to draw on an Excalidraw canvas inside the text. See <em>Drawing canvases</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>.</p><h2>Mermaid diagram</h2><p>Press the <span class=\"tn-icon cke cke-trilium-mermaid-insert\"></span> button to create an inline Mermaid diagram.</p><p>This feature is quite similar to the <a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> note types and is meant as an alternative to it for simple diagrams. For more complex diagrams, use the <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a> feature for a dedicated Mermaid note.</p><figure class=\"image\"><img style=\"aspect-ratio:1174/358;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/2_Insert%20buttons_image.png\" width=\"1174\" height=\"358\"></figure><h2>Horizontal ruler</h2><p>This feature will display a horizontal line, generally useful to separate different sections of the text. To do so, press the <span class=\"tn-icon cke cke-horizontal-line\"></span> button in the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>.</p><img src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/1_Insert%20buttons_image.png\" width=\"502\" height=\"95\"><p>Alternatively, it's possible to insert a horizontal ruler by typing <code>---</code>.</p><h2>Page break</h2><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:371/79;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Text/3_Insert%20buttons_image.png\" width=\"371\" height=\"79\"></figure><p>Page breaks provide a way to force the next paragraph or block (table, image, etc.) to be displayed onto the next page when printing (either to a real printer to <a href=\"#root/_help_NRnIZmSMc5sj\">when exporting to PDF</a>).</p><p>Page breaks are marked in the editor with the words <em>Page break</em>, but they will not actually be shown when printed.</p><ul><li>To insert a page break, press the <span class=\"tn-icon cke cke-page-break\"></span> in the formatting toolbar.</li><li>To insert many page breaks at once, insert a page break first, click on it and press <kbd>Ctrl</kbd>+<kbd>C</kbd>. Then use <kbd>Ctrl</kbd>+<kbd>V</kbd>, to paste as many times as needed.</li></ul><h2>Date and time</h2><p>The <span class=\"tn-icon cke cke-trilium-date-time\"></span> button inserts the current date and time at the cursor, replacing the selected text if there is any. The inserted text takes the formatting of the text around it, so a date inserted inside bold text is bold too.</p><ul><li>To insert the date in the default format, press the button itself or press <kbd>Alt</kbd>+<kbd>T</kbd>.</li><li>To insert it in another format, press the arrow next to the button and pick a format from the list. Each entry shows the current date and time in that format: the default one, the date or the time alone, the date written out, and ISO 8601.</li><li>The same formats are offered by the <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>: type <code>/date</code>, <code>/time</code>, <code>/now</code> or <code>/today</code>. The <em>Insert date/time</em> entry uses the default format, and shows what it inserts underneath; the other entries show their output in the title.</li></ul><p>The default format can be changed in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a> → <em>Text Notes</em> → <em>Editor</em> → <em>Date/time format</em>, using <a href=\"https://day.js.org/docs/en/display/format\">Day.js format tokens</a> (for example <code>DD.MM.YYYY HH:mm</code>).</p><h2>Icons</h2><p>Icons just like the ones for the <a href=\"#root/_help_p9kXRFAkwN4o\">note icon</a> can be inserted in text. For more information see <a class=\"reference-link\" href=\"#root/_help_hD8GawVuazff\">Icons</a>.</p>","_help_hD8GawVuazff": "<p>Icons just like the <a href=\"#root/_help_hD8GawVuazff\">note icons</a> can be inserted in the content of a note, including from any other <a href=\"#root/_help_gOKqSJgXLcIj\">custom icon packs</a>.</p><h2>Features</h2><ul><li>The icon can be formatted through the<a class=\"reference-link\" href=\"#root/_help_Gr6xFaF6ioJ5\">General formatting</a> tools of the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a>:<ul><li>Foreground/icon color</li><li>Background color/highlight</li><li>Font size</li></ul></li><li>Custom <a class=\"reference-link\" href=\"#root/_help_gOKqSJgXLcIj\">Icon Packs</a> are also supported.<ul><li>For emojis, prefer the Emoji functionality from <a class=\"reference-link\" href=\"#root/_help_CohkqWQC1iBv\">Insert buttons</a>.</li></ul></li><li>When an icon is clicked a floating toolbar appears with the following functions:<ul><li><span class=\"tn-icon bx bx-sticker\"></span> which changes the icon.</li><li><span class=\"tn-icon bx bx-reflect-horizontal\"></span> which applies transforms: rotate (90 / 180 / 270) and flip horizontal/vertical. Only one transform can be used per icon.</li></ul></li></ul><h2>Usage</h2><ul><li>The in-app help/user guide makes use of these icons in order to illustrate buttons in the UI.</li><li>The <a class=\"reference-link\" href=\"#root/_help_GnhlmrATVqcH\">Microsoft OneNote</a> importer also makes use of them for the <a class=\"reference-link\" href=\"#root/_help_LpvyEIBIAAj7\">Tags</a>.</li></ul><h2>Inserting an icon</h2><p>There are two ways to insert an icon:</p><ul><li>Via the <a class=\"reference-link\" href=\"#root/_help_nRhnJkTT8cPs\">Formatting toolbar</a> look for the <span class=\"tn-icon bx bx-plus\"></span> icon and then the <span class=\"tn-icon bx bx-sticker\"></span> icon.</li><li>Via <a class=\"reference-link\" href=\"#root/_help_ZlN4nump6EbW\">Slash Commands</a>, type <code>/icon</code>.</li></ul><p>An icon picker will appear, search for an icon and click it to insert it in the document.</p><h2>Finding notes by their icons</h2><p>An icon can be <a href=\"#root/_help_eIg8jdvaoNNd\">searched</a>. A note containing a <span class=\"tn-icon bx bx-star\"></span> icon can be found by searching for <code>star</code>, or its <code>iconClass</code> (<code>bx-star</code>).</p><p>To find the name of the icon, hover the mouse over an icon while in the icon picker.</p><h2>Markdown rendering</h2><p>When exporting to <a class=\"reference-link\" href=\"#root/_help_Oau6X9rCuegd\">Markdown</a>, the item will render as raw HTML representation of the icon as is used by Trilium:</p><pre><code class=\"language-text-html\"><span class=\"tn-icon bx bx-star\"></span></code></pre>","_help_oiVPnW8QfnvS": "<h2>Trilium-specific shortcuts</h2><figure class=\"table\"><table><thead><tr><th>Action</th><th>PC</th><th>Mac</th></tr></thead><tbody><tr><td>Bring up inline formatting toolbar (arrow keys ←,→ to navigate, Enter to apply)</td><td>Alt+F10</td><td>⌥+F10</td></tr><tr><td>Bring up block formatting toolbar</td><td>Alt+F10</td><td>⌥+F10</td></tr><tr><td>Create <a href=\"#root/_help_QEAPj01N5f7w\">external link</a></td><td>Ctrl+K</td><td>⌘+K</td></tr><tr><td>Create <a href=\"#root/_help_QEAPj01N5f7w\">internal (note) link</a></td><td>Ctrl+L</td><td>⌘+L</td></tr><tr><td>Inserts current date and time at caret position</td><td>Alt+T</td><td>⌥+T</td></tr><tr><td>Increase paragraph indentation</td><td>Tab</td><td>⇥</td></tr><tr><td>Decrease paragraph indentation</td><td>Shift + Tab</td><td>⇧ + ⇥</td></tr><tr><td>Mark selected text as <a href=\"#root/_help_UYuUB1ZekNQU\">keyboard shortcut</a></td><td>Ctrl + Alt + K</td><td>⌘+ ⌥+ K</td></tr><tr><td>Insert <a class=\"reference-link\" href=\"#root/_help_YfYAtQBcfo5V\">Math Equations</a></td><td>Ctrl + M</td><td>⌘+ M</td></tr><tr><td>Move blocks (lists, paragraphs, etc.) up</td><td>Ctrl+↑</td><td>⌘+↑</td></tr><tr><td>Alt+↑</td><td>⌥+↑</td><td></td></tr><tr><td>Move blocks (lists, paragraphs, etc.) down</td><td>Ctrl+↑</td><td>⌘+↑</td></tr><tr><td>Alt+↓</td><td>⌥+↓</td><td></td></tr><tr><td>Move the selected content to another column of a <a class=\"reference-link\" href=\"#root/_help_wYDzQ1fBFgfT\">Multicolumn layout</a></td><td>Ctrl+←, Ctrl+→, Ctrl+Shift+Home, Ctrl+Shift+End</td><td>⌘+←, ⌘+→, ⌘+⇧+Home, ⌘+⇧+End</td></tr><tr><td>Move the current column of a multicolumn layout</td><td>Ctrl+Alt+←, Ctrl+Alt+→, Ctrl+Alt+Home, Ctrl+Alt+End</td><td>⌘+⌥+←, ⌘+⌥+→, ⌘+⌥+Home, ⌘+⌥+End</td></tr><tr><td>Add a column after or before the current one in a multicolumn layout</td><td>Ctrl+Enter, Ctrl+Shift+Enter</td><td>⌘+Enter, ⌘+⇧+Enter</td></tr><tr><td>Move the selected content to another tab in <a class=\"reference-link\" href=\"#root/_help_EK2ckIZ74tbT\">Content tabs</a></td><td>Ctrl+←, Ctrl+→, Ctrl+Shift+Home, Ctrl+Shift+End</td><td>⌘+←, ⌘+→, ⌘+⇧+Home, ⌘+⇧+End</td></tr><tr><td>Move the current tab of a tabs block</td><td>Ctrl+Alt+←, Ctrl+Alt+→, Ctrl+Alt+Home, Ctrl+Alt+End</td><td>⌘+⌥+←, ⌘+⌥+→, ⌘+⌥+Home, ⌘+⌥+End</td></tr><tr><td>Add a tab after or before the current one in a tabs block</td><td>Ctrl+Enter, Ctrl+Shift+Enter</td><td>⌘+Enter, ⌘+⇧+Enter</td></tr></tbody></table></figure><h2>Common shortcuts</h2><aside class=\"admonition tip\"><p>This section of keyboard shortcuts presents a subset of the keyboard shortcuts as supported by the editor technology we are using, <a class=\"reference-link\" href=\"#root/_help_MI26XDLSAlCD\">CKEditor</a>. The shortcuts were taken from the <a href=\"https://ckeditor.com/docs/ckeditor5/latest/features/accessibility.html#keyboard-shortcuts\">official documentation</a>. Note that not all the shortcuts in the original documentation are applicable (due to using a different configuration).</p></aside><h3>Content editing</h3><figure class=\"table\"><table><thead><tr><th>Action</th><th>PC</th><th>Mac</th></tr></thead><tbody><tr><td>Insert a hard break (a new paragraph)</td><td>Enter</td><td></td></tr><tr><td>Insert a soft break (a <code><br></code> element)</td><td>Shift+Enter</td><td>⇧Enter</td></tr><tr><td>Copy selected content</td><td>Ctrl+C</td><td>⌘C</td></tr><tr><td>Paste content</td><td>Ctrl+V</td><td>⌘V</td></tr><tr><td>Paste content as plain text</td><td>Ctrl+Shift+V</td><td>⌘⇧V</td></tr><tr><td>Undo</td><td>Ctrl+Z</td><td>⌘Z</td></tr><tr><td>Redo</td><td>Ctrl+Y, Ctrl+Shift+Z</td><td>⌘Y, ⌘⇧Z</td></tr><tr><td>Bold text</td><td>Ctrl+B</td><td>⌘B</td></tr><tr><td>Change text case</td><td>Shift+F3</td><td>⇧F3 (may require Fn)</td></tr><tr><td>Create link</td><td>Ctrl+K</td><td>⌘K</td></tr><tr><td>Move out of a link</td><td>←←, →→</td><td></td></tr><tr><td>Move out of an inline code style</td><td>←←, →→</td><td></td></tr><tr><td>Select all</td><td>Ctrl+A</td><td>⌘A</td></tr><tr><td>Find in the document</td><td>Ctrl+F</td><td>⌘F</td></tr><tr><td>Copy text formatting</td><td>Ctrl+Shift+C</td><td>⌘⇧C</td></tr><tr><td>Paste text formatting</td><td>Ctrl+Shift+V</td><td>⌘⇧V</td></tr><tr><td>Italic text</td><td>Ctrl+I</td><td>⌘I</td></tr><tr><td>Strikethrough text</td><td>Ctrl+Shift+X</td><td>⌘⇧X</td></tr><tr><td>Underline text</td><td>Ctrl+U</td><td>⌘U</td></tr><tr><td>Revert autoformatting action</td><td>Backspace</td><td></td></tr></tbody></table></figure><h3>Interacting with blocks</h3><p>Blocks are images, tables, blockquotes, annotations.</p><figure class=\"table\"><table><thead><tr><th>Action</th><th>PC</th><th>Mac</th></tr></thead><tbody><tr><td>Insert a new paragraph directly after a widget</td><td>Enter</td><td></td></tr><tr><td>Insert a new paragraph directly before a widget</td><td>Shift+Enter</td><td>⇧Enter</td></tr><tr><td>Move the caret to allow typing directly before a widget</td><td>↑, ←</td><td></td></tr><tr><td>Move the caret to allow typing directly after a widget</td><td>↓, →</td><td></td></tr><tr><td>After entering a nested editable, move the selection to the closest ancestor widget. For example: move from an image caption to the whole image widget.</td><td>Tab then Esc</td><td></td></tr></tbody></table></figure><p>Specifically for lists:</p><figure class=\"table\"><table><thead><tr><th>Action</th><th>PC</th><th>Mac</th></tr></thead><tbody><tr><td>Increase list item indent</td><td>⇥</td><td></td></tr><tr><td>Decrease list item indent</td><td>Shift+⇥</td><td>⇧⇥</td></tr></tbody></table></figure><p>In tables:</p><figure class=\"table\"><table><thead><tr><th>Action</th><th>PC</th><th>Mac</th></tr></thead><tbody><tr><td>Move the selection to the next cell</td><td>⇥</td><td></td></tr><tr><td>Move the selection to the previous cell</td><td>Shift+⇥</td><td>⇧⇥</td></tr><tr><td>Insert a new table row (when in the last cell of a table)</td><td>⇥</td><td></td></tr><tr><td>Navigate through the table</td><td>↑, →, ↓, ←</td><td></td></tr></tbody></table></figure><h3>General UI shortcuts</h3><figure class=\"table\"><table><thead><tr><th>Action</th><th>PC</th><th>Mac</th></tr></thead><tbody><tr><td>Close contextual balloons, dropdowns, and dialogs</td><td>Esc</td><td></td></tr><tr><td>Open the accessibility help dialog</td><td>Alt+0</td><td>⌥0</td></tr><tr><td>Move focus between form fields (inputs, buttons, etc.)</td><td>⇥, Shift+⇥</td><td>⇥, ⇧⇥</td></tr><tr><td>Move focus to the toolbar, navigate between toolbars</td><td>Alt+F10</td><td>⌥F10 (may require Fn)</td></tr><tr><td>Navigate through the toolbar or menu bar</td><td>↑, →, ↓, ←</td><td></td></tr><tr><td>Navigate to the next focusable field or an element outside the editor</td><td>Tab, Shift+Tab</td><td></td></tr><tr><td>Execute the currently focused button. Executing buttons that interact with the editor content moves the focus back to the content.</td><td>Enter, Space</td><td></td></tr><tr><td>Move focus in and out of an active dialog window</td><td>Ctrl+F6</td><td>⌘F6 (may require Fn)</td></tr></tbody></table></figure>",@@ -170,7 +170,7 @@"_help_AjqEeiDUOzj4": "<figure class=\"image image-style-align-right image_resized\" style=\"width:61.8%;\"><img style=\"aspect-ratio:953/587;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/File/Audio%20%26%20Video_image.png\" width=\"953\" height=\"587\"></figure><p>Starting with v0.103.0, Trilium has a custom media player for both video and audio files, which offers more features than the built-in player.</p><p>Versions prior to v0.103.0 also support media, but using the built-in player.</p><p>The file is streamed directly, so when accessing the note from a server it doesn't have to download the entire file to start playing it.</p><h2>Note on large media files</h2><p>Although Trilium offers support for media files, it is generally not meant to be used with very large files. Uploading large media will cause the <a class=\"reference-link\" href=\"#root/_help_wX4HbRucYSDD\">Database</a> to balloon, as well as any <a class=\"reference-link\" href=\"#root/_help_ODY7qQn5m2FT\">Backup</a> of it. In addition, there might be slowdowns when first uploading the files. Otherwise, a large database should not impact the general performance of Trilium significantly.</p><h2>Supported formats</h2><p>Trilium uses the built-in media decoding mechanism of the browser (or Electron/Chromium when running on the desktop). Starting with v0.103.0, a message will be displayed instead when a media format is not supported.</p><h2>Interactions</h2><p>To play/pause, simply click anywhere on the media. For video files, the controls at the bottom will hide automatically after playing, simply move the mouse to show them again.</p><p>The bottom bar has the following features:</p><ul><li>A track bar to seek across the media. Audio files up to 60 MB will display a waveform seekbar, to give a visual overview of the track's structure: silences, pauses, and louder segments.</li><li>On the left of the track bar, the current time is indicated.</li><li>On the right of the track bar, the remaining time is indicated.</li><li>On the left side there are buttons to:<ul><li>Adjust the playback speed (e.g. 0.5x, 1x).</li><li>Play mode (applies to all media from the parent note):<ul><li>Play once — play the media until it ends, then stop.</li><li>Loop — replay the media automatically once it ends.</li><li>Play next — when the current item ends, continue with the next one in the same parent note until the last item finishes.</li></ul></li><li>Rotate the video by 90 degrees (video only).</li></ul></li><li>In the center:<ul><li>Previous media — jumps to the previous media: the nearest media note above the current one in the tree (within the same parent note) in the case of media notes, or the previous media attachment.</li><li>Go back by 10s</li><li>Play/pause</li><li>Go forward by 10s</li><li>Next media — jumps to the next media: the nearest media note below the current one in the tree (within the same parent note) in the case of media notes, or the next media attachment.</li></ul></li><li>On the right side:<ul><li>Mute button</li><li>Volume adjustment</li><li>Full screen (video only)</li><li>Zoom to fill, which will crop the video so that it fills the entire window (video only).</li><li>Picture-in-picture, if the browser supports it (video only).</li></ul></li></ul><h2>Including media in notes</h2><figure class=\"image\"><img style=\"aspect-ratio:1395/145;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/File/1_Audio%20%26%20Video_image.png\" width=\"1395\" height=\"145\"><figcaption>An audio note include (configured to the \"Small\" size).</figcaption></figure><p><a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> and <a class=\"reference-link\" href=\"#root/_help_6RM1Q7ppFVoj\">Markdown</a> notes can embed an interactive media player directly in the note content. To do so, include the audio or video file:</p><ul><li><strong>Text notes:</strong> in the formatting toolbar, click <em>Insert</em> → <em>Include</em>.</li><li><strong>Markdown notes:</strong> type <code>/include</code> press <kbd>Enter</kbd>.</li></ul><p>Then select the audio/video file note to be included.</p><h2>Keyboard shortcuts</h2><p>The following keyboard shortcuts are supported by the media player:</p><figure class=\"table\"><table><tbody><tr><td><kbd>Space</kbd></td><td>Play/pause</td></tr><tr><td><kbd>Left arrow key</kbd></td><td>Go back by 10s</td></tr><tr><td><kbd>Right arrow key</kbd></td><td>Go forward by 10s</td></tr><tr><td><kbd>Ctrl</kbd> + <kbd>Left arrow key</kbd></td><td>Go back by 1 min</td></tr><tr><td><kbd>Ctrl</kbd> + <kbd>Right arrow key</kbd></td><td>Go right by 1 min</td></tr><tr><td><kbd>Page Up</kbd></td><td>Navigate to the previous media</td></tr><tr><td><kbd>Page Down</kbd></td><td>Navigate to the next media</td></tr><tr><td><kbd>F</kbd></td><td>Toggle full-screen</td></tr><tr><td><kbd>M</kbd></td><td>Mute/unmute</td></tr><tr><td><kbd>Home</kbd></td><td>Go to the beginning of the media</td></tr><tr><td><kbd>End</kbd></td><td>Go to the end of the media</td></tr><tr><td><kbd>Up</kbd></td><td>Increase volume by 5%</td></tr><tr><td><kbd>Down</kbd></td><td>Decrease volume by 5%</td></tr><tr><td><kbd>Alt+F1</kbd> (customizable)</td><td>Show this list of keyboard shortcuts on screen.</td></tr></tbody></table></figure>","_help_KG48zgNY31NW": "<p>Since v0.105.0, office documents stored in Trilium display an inline preview of their content, without the need to download them or open them in an external application.</p><h2>Supported formats</h2><ul><li>Microsoft Office formats: Word (<code>.docx</code>), Excel (<code>.xlsx</code>) and PowerPoint (<code>.pptx</code>).</li><li>The OpenDocument alternatives to the previous formats (Text, Spreadsheet, Presentation), created by editors such as LibreOffice and OpenOffice.</li><li><a href=\"https://en.wikipedia.org/wiki/Rich_Text_Format\">Rich Text Format (RTF)</a>.</li><li><a href=\"https://en.wikipedia.org/wiki/EPUB\">EPUB</a> e-books.</li></ul><aside class=\"admonition note\"><p>Older Microsoft Office formats (<code>.doc</code>, <code>.xls</code>, <code>.ppt</code>) are not supported.</p></aside><h2>How it works</h2><p>The document is converted to a simplified representation on the server and rendered as read-only content, similar to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note.</p><p>The preview generally preserves:</p><ul><li>Headings, paragraphs and text alignment.</li><li>Text formatting: bold, italic, underline, strikethrough, subscript/superscript, text and highlight colors, fonts and font sizes.</li><li>Bulleted and numbered lists.</li><li>Tables, including merged cells and cell background colors.</li><li>Embedded images.</li><li>Links and footnotes.</li></ul><p>To keep links readable regardless of the theme, the default hyperlink color applied automatically by word processors is ignored; links that were deliberately given a custom color by the author keep it.</p><h2>Limitations</h2><ul><li>The preview is read-only. To edit the document, download it or open it in an external application; the content of the note is not affected by the preview. Alternatively copy and paste it into a text note.</li><li>The preview is a simplified rendering: complex layouts (columns, text boxes, headers and footers), charts and the precise styling of table borders are not reproduced.</li><li>Documents larger than 20 MB are not previewed, to keep the server responsive. The usual download and open actions remain available.</li><li>If the document cannot be converted, a notice is displayed instead and the file can still be downloaded or opened externally.</li></ul><h2>Relation with other features</h2><ul><li>The same preview is used when an office document is displayed in the <a class=\"reference-link\" href=\"#root/_help_0ESUbbAxVnoK\">Note List</a> or embedded in a text note via <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>, as well as for office documents stored as <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>.</li><li>Independently of the preview, the text content of office documents is also extracted in the background so that it can be found with <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a> via <a class=\"reference-link\" href=\"#root/_help_TiQbQDgP8L5t\">Text Extraction (OCR)</a>.</li><li><code>.csv</code> and <code>.xlsx</code> files can be converted to <a class=\"reference-link\" href=\"#root/_help_GWHEkY4I4OE3\">Spreadsheets</a> via the <a href=\"#root/_help_mHbBMPDPkVV5\">import</a> function.</li></ul>","_help_GWHEkY4I4OE3": "<figure class=\"image\"><img style=\"aspect-ratio:1102/573;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Spreadsheets_image.png\" width=\"1102\" height=\"573\"></figure><aside class=\"admonition important\"><p>Spreadsheets are a new type of note introduced in v0.103.0 and are currently considered experimental/beta. As such, expect major changes to occur to this note type.</p></aside><p>Spreadsheets provide a familiar experience to Microsoft Excel or LibreOffice Calc, with support for formulas, data validation and text formatting.</p><h2>Spreadsheets vs. collections</h2><p>There is a slight overlap between spreadsheets and the <a class=\"reference-link\" href=\"#root/_help_2FvYrpmOXm29\">Table</a> collection. In general the table collection is useful to track meta-information about notes (for example a collection of people and their birthdays), whereas spreadsheets are quite useful for calculations since they support formulas.</p><p>Spreadsheets also benefit from a wider range of features such as data validation, formatting and can work on a relatively large dataset.</p><h2>Data intercompatibility (import/export)</h2><p>Starting with v0.104.0, Trilium provides a level of data intercompatibility between the internal format (Univer) and the following formats:</p><ul><li>Microsoft Excel (.xlsx)<ul><li>Preserves basic formatting (fonts, sizes, borders, backgrounds).</li><li>Formulas are preserved, but note that not all Excel functions are supported and vice-versa with Univer.</li><li>Images (cell-bound or floating), without preserving rotation.</li><li>Supports multi-sheets natively.</li></ul></li><li>Comma-Separated Values (.csv)<ul><li>Since it's a text-based format, any formatting is lost.</li><li>Formulas are evaluated and turned into their final value instead.</li><li>Multi-sheets spreadsheets are exported as a single ZIP containing a CSV file per sheet.</li></ul></li></ul><p>Both <a href=\"#root/_help_mHbBMPDPkVV5\">import and export</a> are supported, as follows:</p><ul><li>To import a file, simply drag it into the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and it will be converted into a spreadsheet note.<ul><li>To avoid this behavior (e.g. to import a .xlsx file as an actual <a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a>), uncheck the corresponding option in the <a href=\"#root/_help_mHbBMPDPkVV5\">Import dialog</a>.</li><li>Multiple files can be imported at the same time, including a mixture of .csv and .xlsx files. Folder structure can be preserved by using a .zip file.</li></ul></li><li>Unlike importing, exporting is on a per-note basis:<ul><li>In the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>, choose the <em>Export to Excel</em> or <em>Export to CSV</em> options.</li><li>If exported as a single file via <a class=\"reference-link\" href=\"#root/_help_mHbBMPDPkVV5\">Import & Export</a>, the resulting file will be a custom <code>.triliumsheet</code> file that preserves the spreadsheet as-is.<ul><li>The export is intentionally a different process than the normal <a class=\"reference-link\" href=\"#root/_help_mHbBMPDPkVV5\">Import & Export</a> functionality because it does conversion to multiple formats with varying degrees of compatibility.</li></ul></li></ul></li></ul><p>Cells pasted from Excel or another application keep their formatting except for the font, so they use the spreadsheet's font like the rest of the cells.</p><aside class=\"admonition important\"><p>Import & export for both .xlsx and .csv files are supported on a best-effort basis. It does not support advanced features (data validation, scripting, etc.). If you notice a particular issue, it can be <a href=\"#root/_help_wy8So3yZZlH9\">reported</a>, however all bug reports must contain a sample file in order to be taken into consideration.</p></aside><h2>Supported features</h2><p>The spreadsheet has support for the following features:</p><ul><li>Since v0.104.0, images that can be either inside a cell or floating above.<ul><li>The images are saved as <a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a> for performance reasons.</li><li>The image upload respects the same compression settings as text <a class=\"reference-link\" href=\"#root/_help_mT0HEkOsz6i1\">Images</a>.</li></ul></li><li>Filtering</li><li>Sorting</li><li>Data validation</li><li>Conditional formatting</li><li>Notes / annotations</li><li>Find / replace</li></ul><p>We might consider adding <a href=\"https://docs.univer.ai/guides/sheets/features/filter\">other features</a> from Univer at some point. If there is a particular feature that can be added easily, it can be discussed over <a href=\"#root/_help_wy8So3yZZlH9\">GitHub Issues</a>.</p><h3>Share functionality</h3><p>Spreadsheets can be <a href=\"#root/_help_R9pX4DGra2Vt\">shared</a>, case in which a best-effort HTML rendering of the spreadsheet is done:</p><ul><li>Preserves basic formatting.</li><li>Cells with formulas display the precalculated value instead of the formula.</li></ul><p>Since v0.104.0:</p><ul><li>Numbers and dates are properly formatted.</li><li>Images are shown inside a cell or floating above, including rotation.</li></ul><p>For more advanced use cases, this will most likely not work as intended. Feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report issues</a>, but keep in mind that we might not be able to have a complete feature parity with all the features of Univer.</p><h2>Features not supported yet</h2><h3>Regarding Pro features</h3><p>Univer spreadsheets also feature a <a href=\"https://univer.ai/pro\">Pro plan</a> which adds quite a lot of functionality such as charts, printing, pivot tables, export, etc.</p><p>As the Pro plan needs a license, Trilium does not support any of the premium features. Theoretically, pro features can be used in trial mode with some limitations, we might explore this direction at some point.</p><h3>Planned features</h3><p>There are a few features that are already planned but are not supported yet:</p><ul><li>Trilium-specific formulas (e.g. to obtain the title of a note).</li><li>User-defined formulas</li><li>Cross-workbook calculation</li></ul><p>If you would like us to work on these features, consider <a href=\"https://triliumnotes.org/en/support-us\">supporting us</a>.</p><h3>Mobile support</h3><p>Versions prior to v0.104.0 have no dedicated mobile support, which means that the interaction is difficult without a mouse and keyboard. Starting with v0.104.0 we integrate Univer's mobile plugin, which introduces feature such as drag to pan which makes the interface more usable on mobile.</p>",- "_help_6RM1Q7ppFVoj": "<p>Trilium has always supported Markdown through its <a href=\"#root/_help_Oau6X9rCuegd\">import feature</a>, however the file was either transformed to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note (converted to Trilium's internal HTML format) or saved as a <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> note with only syntax highlight.</p><p>This note type is a split view, meaning that both the source code and a preview of the document are displayed side-by-side. See <a class=\"reference-link\" href=\"#root/_help_SL5f1Auq7sVN\">Note types with split view</a> for more information.</p><h2>Rationale</h2><p>The goal of this note type is to fill a gap: rendering Markdown but not altering its structure or its whitespace which would inevitably change otherwise through import/export.</p><p>Even if Markdown is now specially treated by having a preview mechanism, Trilium remains at its core a WYSWYG editor so Markdown will not replace text notes.</p><aside class=\"admonition note\"><p>Feature requests regarding the Markdown implementation will be considered, but if they are outside the realm of Trilium, they will not be implemented. One of the core aspects of the Markdown integration is that it reuses components that are already available through other features of the application.</p></aside><h2>Features</h2><h3>Source view pane</h3><ul><li>Syntax highlighting for the Markdown syntax.</li><li>Nested syntax highlighting for code inside code blocks.</li><li>When editing larger documents, the preview scrolls along with the source editor.</li></ul><h3>Preview pane</h3><p>The following features are supported by Trilium's Markdown format and will show up in the preview pane:</p><ul><li><p>All standard and GitHub-flavored syntax (basic formatting, tables, blockquotes).</p></li><li><p>Basic HTML is also supported (e.g. collapsible blocks using <code><details></code> and <code><summary></code>).</p></li><li><p>Code blocks with syntax highlight.</p><ul><li>The language must be specified for syntax highlight to be applied (e.g. <code>```js</code>).</li><li>Code blocks will respect the text wrapping from the <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> section in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>.</li></ul></li><li><p><a class=\"reference-link\" href=\"#root/_help_NwBbFdNZ9h7O\">Block quotes & admonitions</a></p></li><li><p><a class=\"reference-link\" href=\"#root/_help_YfYAtQBcfo5V\">Math Equations</a> (both inline and block)</p></li><li><p><a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> using <code>```mermaid</code></p></li><li><p><a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a> (no built-in Markdown syntax, but HTML syntax works just fine):</p><pre><code class=\"language-text-html\"><figure class=\"include-note\" data-note-id=\"vJDjQm0VK8Na\" data-box-size=\"expandable\">\n <figcaption>An optional caption, with <strong>HTML</strong> formatting</figcaption>\n</figure></code></pre><ul><li>The caption is optional. Markdown is not processed inside the HTML block, so format the caption with HTML tags.</li><li>Includes written as <code><section class=\"include-note\"></code>, the syntax of earlier versions, still work.</li><li>These can also be quickly created via the <code>/include</code> command or via a dedicated keyboard shortcut (not assigned by default).</li></ul></li><li><p><a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> via its HTML syntax, or through a <em>Wikilinks</em>-like format (only <a class=\"reference-link\" href=\"#root/_help_m1lbrzyKDaRB\">Note ID</a>):</p><pre><code class=\"language-text-x-trilium-auto\">[[Hg8TS5ZOxti6]]</code></pre></li><li><p>To-do lists with extended task states:</p><figure class=\"table\"><table class=\"ck-table-resized\" style=\"border-style:none;\"><colgroup><col style=\"width:80.6%;\"><col style=\"width:19.4%;\"></colgroup><tbody><tr><td><pre><code class=\"language-text-x-markdown\">- [ ] None\n- [/] Doing\n- [X] Done\n- [?] Maybe\n- [-] Cancelled</code></pre></td><td><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:218/221;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Markdown_image.png\" width=\"218\" height=\"221\"></figure></td></tr></tbody></table></figure><p>Task states are customizable: you can reorder them, create new ones with different colors and symbols, or delete the ones you don't need. See <a class=\"reference-link\" href=\"#root/_help_i16PM6A7GXdU\">Customizing to-do task states</a> for more details.</p><p>Note that to-do items with task states other than \"None\" and \"Done\" are Trilium-specific and may not work well with other Markdown software.</p></li><li><p><a class=\"reference-link\" href=\"#root/_help_AgjCISero73a\">Footnotes</a> are also supported via the corresponding Markdown syntax:</p><pre><code class=\"language-text-x-trilium-auto\">This is [^1], while this is [^2].\n\n[^1]: the first footnote\n[^2]: the second footnote</code></pre><ul><li>These can also be quickly created using the <code>/footnote</code> command.</li></ul></li><li><p>Page breaks for <a class=\"reference-link\" href=\"#root/_help_NRnIZmSMc5sj\">Printing & Exporting as PDF</a>:</p><pre><code class=\"language-text-x-trilium-auto\"><div class=\"page-break\"></div></code></pre></li><li><p>Highlights (background color) are supported both via the <code>==</code> Markdown syntax, as well as the canonical HTML representation in Trilium:</p><pre><code class=\"language-text-x-trilium-auto\">==highlighted==\n<span style=\"background-color:#e5e64d;--tn-background:#e5e64d;\">Highlighted</span></code></pre></li></ul><h3>Links</h3><p>Multiple types of links are supported:</p><ul><li><p>Web URLs can be written with the standard Markdown syntax:</p><pre><code class=\"language-text-x-trilium-auto\">[Wikipedia](https://www.wikipedia.org)</code></pre></li><li><p><a href=\"#root/_help_hrZ1D00cLbal\">Reference link</a> to other notes with dynamic title, either by manually entering the note ID or via the <em>Add link</em> dialog:</p><pre><code class=\"language-text-x-trilium-auto\">[[B9oMG6rFvvfq]]</code></pre></li><li><p><a href=\"#root/_help_hrZ1D00cLbal\">Reference link</a> to other notes with a custom text:</p><pre><code class=\"language-text-x-trilium-auto\">[This is a link](#root/LhtnZxtVsUMp)</code></pre></li></ul><p>To create a link, either:</p><ul><li>Type it manually using the syntax described above.</li><li>Use the <em>Add link</em> dialog by pressing <kbd>Ctrl</kbd>+<kbd>L</kbd> or typing the <code>/link</code> command.</li></ul><p><a class=\"reference-link\" href=\"#root/_help_UmgZAfcltxkS\">Link Previews</a> are also rendered, but there is no mechanism to insert them automatically as of now, they have to be copied from a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note instead.</p><h3>Keyboard shortcuts</h3><p>The Markdown notes share some of the keyboard shortcuts from <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes:</p><ul><li><em>Cut to note</em> (<kbd>Ctrl</kbd>+<kbd>X</kbd>) which cuts the selection into a new child note.</li><li><em>Add link</em> (<kbd>Ctrl</kbd>+<kbd>L</kbd>) which shows the dialog to create external or reference links.</li><li><em>Date/time</em> (<kbd>Alt</kbd>+<kbd>T</kbd>) which respects the same formatting as text notes.</li><li><em>Include note</em> (not assigned by default), which triggers the same dialog to insert notes as the one for text notes.</li></ul><p>In addition, the following formatting keyboard shortcuts are available:</p><ul><li><kbd>Ctrl</kbd>+<kbd>B</kbd> to toggle <strong>bold</strong>.</li><li><kbd>Ctrl</kbd>+<kbd>I</kbd> to toggle <em>italic</em>.</li><li><kbd>Ctrl</kbd>+<kbd>M</kbd> to wrap the current selection in an inline math (<code>$</code>).</li><li><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd> to toggle <del>strikethrough</del>.</li></ul><h3>Images & attachments</h3><p>Images can be inserted into the document in four different methods:</p><ul><li>Drag & drop directly into the editor area.</li><li>Pasting an image from clipboard.</li><li>Pasting a reference to another <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> (e.g. <em>Copy reference to clipboard</em> button).</li><li>Use the <code>/image</code> slash command.</li></ul><p>An image reference to an attachment looks like this:</p><pre><code class=\"language-text-x-trilium-auto\"></code></pre><h3>Auto-completion</h3><h4>Slash commands</h4><p>Just like <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, Markdown notes support a selection of slash commands:</p><ul><li>Inserting the current date & time (<code>/date</code>).</li><li><a href=\"#root/_help_nBAXQFj20hS1\">Including</a> another note (<code>/include</code>).</li><li>Uploading and inserting an image (<code>/image</code>).</li><li>Inserting a note link (<code>/link</code>).</li><li>Inserting a math equation block (<code>/math</code>).</li><li>Inserting a <a href=\"#root/_help_AgjCISero73a\">footnote</a> (<code>/footnote</code>).</li><li>Inserting a <a href=\"#root/_help_s1aBHPd79XYj\">Mermaid</a> diagram (<code>/mermaid</code>), with one variant per sample template (e.g. <code>/mermaid:flowchart</code>).</li><li>Inserting a collapsible block (<code>/collapsible</code>).</li><li>Inserting <a href=\"#root/_help_rJ9grSgoExl9\">tabs</a> (<code>/tabs</code>).</li><li>Inserting a page break for printing (<code>/page-break</code>).</li><li>Inserting a table (<code>/table</code>).</li><li>Creating admonitions (e.g. <code>/tip</code>, <code>/note</code>, <code>/important</code>, <code>/caution</code>, <code>/warning</code>).</li><li>Inserting task items (<code>/todo:<state></code>, e.g. <code>/todo:done</code>), one per configured task state.</li><li>Inserting code snippets (<code>/snippet:<name></code>) from your Markdown/plain-text snippet notes.</li></ul><p>The list shows each command by its title, as in Text notes. Typing a command's title, its keyword (as listed above) or a related word such as <code>latex</code> or <code>grid</code> finds it.</p><p>Note that slash commands only work outside of code blocks and inline code.</p><h4>Linking notes with <code>@</code> or <code>[[</code></h4><p>As in <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, typing <code>@</code> at the start of a line or after a space opens the note search. Picking a note replaces what was typed with a link to it in the Wikilinks-like format (<code>[[noteId]]</code>), which the preview shows as an <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> with the note's title.</p><p>The search runs on everything typed after the <code>@</code>, spaces included, so a title such as <code>@My meeting notes</code> can be typed out; press <kbd>Esc</kbd> to close the list and go on writing. If no note fits, the list offers to create one, as a child of the Markdown note or in the inbox; the link is inserted once the note is created.</p><p>You can also start typing the link directly: <code>[[</code> opens the same list, and closing the brackets yourself dismisses it. To change where an existing link points, place the cursor inside it and pick another note.</p><p>Like slash commands, <code>@</code> and <code>[[</code> do nothing inside code blocks and inline code.</p><p>In the editor, a <code>[[noteId]]</code> link shows as the note's icon and title, so you can tell which note it points to without looking up its ID. Clicking it, or moving the cursor next to it, shows the link as written so it can be edited. Links inside code blocks and inline code are left as they are.</p><h4>Code block language auto-completion</h4><p>Starting with v0.104.0, typing ``` to insert a code block will automatically open a list of suggested language types which have syntax highlighting.</p><p>The list of languages matches the one for <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes set in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>, it's not the full list of languages supported by Trilium.</p><h3>Other features</h3><ul><li>The <a class=\"reference-link\" href=\"#root/_help_BFvAtE74rbP6\">Table of contents</a> will be displayed in the <a class=\"reference-link\" href=\"#root/_help_RnaPdbciOfeq\">Right Sidebar</a> based on the Markdown-level headings.</li></ul><h3>Shared notes</h3><p>When a Markdown note is <a href=\"#root/_help_R9pX4DGra2Vt\">shared publicly</a>, it will be rendered with extended formatting just like <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes.</p><p>Most of the features described previously should be supported. If you face any issues, feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report it</a> alongside a sample Markdown file.</p><h2>Creating Markdown notes</h2><p>There are two ways to create a Markdown note:</p><ol><li>Create a new note (e.g. in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>) and select the type <em>Markdown</em>, just like all the other note types.</li><li>Create a note of type <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> and select as the language either <em>Markdown</em> or <em>GitHub-Flavored Markdown</em>. This maintains compatibility with your existing notes prior to the introduction of this feature.</li></ol><aside class=\"admonition note\"><p>There is no distinction between the new Markdown note type and code notes of type Markdown; internally both are represented as <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes with one of the following MIME types:</p><ul><li><code>text/markdown</code></li><li><code>text/x-markdown</code></li><li><code>text/x-gfm</code> (GitHub Flavored Markdown)</li></ul></aside><h2>Import/export</h2><h3>Import</h3><p>By default, when importing a single Markdown file it automatically gets converted to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note. To avoid that and have it imported as a Markdown note instead:</p><ul><li>Right click the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and select <em>Import into note</em>.</li><li>Select the file normally.</li><li>Uncheck <em>Import HTML, Markdown and TXT as text notes if it's unclear from the metadata</em>.</li></ul><p>When importing a Trilium ZIP, it will preserve the Markdown type without converting to text notes thanks to the meta-information in it.</p><h3>Exporting</h3><p>When exporting Markdown files, the extension is preserved and the content remains the same as in the source view (with some small exceptions such as handling of attachments).</p><p>When exporting Markdown files as ZIP, choosing HTML or Markdown as the export format makes no difference as that only affects <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes.</p><p>If the Markdown note contains attachments, a ZIP export will rewrite the links to attachments so that they are replaced with a relative path to the attachment. On import, the links are re-written back.</p><h2>Conversion between text notes and Markdown notes</h2><p><a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes can be converted into Markdown notes and vice versa. See <a class=\"reference-link\" href=\"#root/_help_jludwdW7N4hg\">Converting between note types</a>.</p><h2>Sync-scrolling & block highlight</h2><p>When scrolling through the editing pane, the preview pane will attempt to synchronize its position to make it easier to see the preview.</p><p>In addition, the block in the preview matching the position of the cursor in the source view will appear slightly highlighted.</p><p>The sync is currently one-way only, scrolling the preview will not synchronize the position of the editor.</p><p>This feature cannot be disabled as of now; if the scrolling feels distracting, consider temporarily switching to the editor mode and then switching to preview mode when ready.</p><aside class=\"admonition note\"><p>This feature of synchronizing the scroll is based on blocks but it's provided on a best-effort basis since our underlying Markdown library doesn't support this feature natively, so we had to implement our own algorithm. Feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report issues</a>, but always provide a sample Markdown file to be able to reproduce it.</p></aside>",+ "_help_6RM1Q7ppFVoj": "<p>Trilium has always supported Markdown through its <a href=\"#root/_help_Oau6X9rCuegd\">import feature</a>, however the file was either transformed to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note (converted to Trilium's internal HTML format) or saved as a <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> note with only syntax highlight.</p><p>This note type is a split view, meaning that both the source code and a preview of the document are displayed side-by-side. See <a class=\"reference-link\" href=\"#root/_help_SL5f1Auq7sVN\">Note types with split view</a> for more information.</p><h2>Rationale</h2><p>The goal of this note type is to fill a gap: rendering Markdown but not altering its structure or its whitespace which would inevitably change otherwise through import/export.</p><p>Even if Markdown is now specially treated by having a preview mechanism, Trilium remains at its core a WYSWYG editor so Markdown will not replace text notes.</p><aside class=\"admonition note\"><p>Feature requests regarding the Markdown implementation will be considered, but if they are outside the realm of Trilium, they will not be implemented. One of the core aspects of the Markdown integration is that it reuses components that are already available through other features of the application.</p></aside><h2>Features</h2><h3>Source view pane</h3><ul><li>Syntax highlighting for the Markdown syntax.</li><li>Nested syntax highlighting for code inside code blocks.</li><li>When editing larger documents, the preview scrolls along with the source editor.</li></ul><h3>Preview pane</h3><p>The following features are supported by Trilium's Markdown format and will show up in the preview pane:</p><ul><li><p>All standard and GitHub-flavored syntax (basic formatting, tables, blockquotes).</p></li><li><p>Basic HTML is also supported (e.g. collapsible blocks using <code><details></code> and <code><summary></code>).</p></li><li><p>Code blocks with syntax highlight.</p><ul><li>The language must be specified for syntax highlight to be applied (e.g. <code>```js</code>).</li><li>Code blocks will respect the text wrapping from the <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> section in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>.</li></ul></li><li><p><a class=\"reference-link\" href=\"#root/_help_NwBbFdNZ9h7O\">Block quotes & admonitions</a></p></li><li><p><a class=\"reference-link\" href=\"#root/_help_YfYAtQBcfo5V\">Math Equations</a> (both inline and block)</p></li><li><p><a class=\"reference-link\" href=\"#root/_help_s1aBHPd79XYj\">Mermaid Diagrams</a> using <code>```mermaid</code></p></li><li><p><a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a> (no built-in Markdown syntax, but HTML syntax works just fine):</p><pre><code class=\"language-text-html\"><figure class=\"include-note\" data-note-id=\"vJDjQm0VK8Na\" data-box-size=\"expandable\">\n <figcaption>An optional caption, with <strong>HTML</strong> formatting</figcaption>\n</figure></code></pre><ul><li>The caption is optional. Markdown is not processed inside the HTML block, so format the caption with HTML tags.</li><li>Includes written as <code><section class=\"include-note\"></code>, the syntax of earlier versions, still work.</li><li>These can also be quickly created via the <code>/include</code> command or via a dedicated keyboard shortcut (not assigned by default).</li></ul></li><li><p><a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> via its HTML syntax, or through a <em>Wikilinks</em>-like format (only <a class=\"reference-link\" href=\"#root/_help_m1lbrzyKDaRB\">Note ID</a>):</p><pre><code class=\"language-text-x-trilium-auto\">[[Hg8TS5ZOxti6]]</code></pre></li><li><p>To-do lists with extended task states:</p><figure class=\"table\"><table class=\"ck-table-resized\" style=\"border-style:none;\"><colgroup><col style=\"width:80.6%;\"><col style=\"width:19.4%;\"></colgroup><tbody><tr><td><pre><code class=\"language-text-x-markdown\">- [ ] None\n- [/] Doing\n- [X] Done\n- [?] Maybe\n- [-] Cancelled</code></pre></td><td><figure class=\"image image-style-align-right\"><img style=\"aspect-ratio:218/221;\" src=\"{{helpAssets}}/User%20Guide/Note%20Types/Markdown_image.png\" width=\"218\" height=\"221\"></figure></td></tr></tbody></table></figure><p>Task states are customizable: you can reorder them, create new ones with different colors and symbols, or delete the ones you don't need. See <a class=\"reference-link\" href=\"#root/_help_i16PM6A7GXdU\">Customizing to-do task states</a> for more details.</p><p>Note that to-do items with task states other than \"None\" and \"Done\" are Trilium-specific and may not work well with other Markdown software.</p></li><li><p><a class=\"reference-link\" href=\"#root/_help_AgjCISero73a\">Footnotes</a> are also supported via the corresponding Markdown syntax:</p><pre><code class=\"language-text-x-trilium-auto\">This is [^1], while this is [^2].\n\n[^1]: the first footnote\n[^2]: the second footnote</code></pre><ul><li>These can also be quickly created using the <code>/footnote</code> command.</li></ul></li><li><p>Page breaks for <a class=\"reference-link\" href=\"#root/_help_NRnIZmSMc5sj\">Printing & Exporting as PDF</a>:</p><pre><code class=\"language-text-x-trilium-auto\"><div class=\"page-break\"></div></code></pre></li><li><p>Highlights (background color) are supported both via the <code>==</code> Markdown syntax, as well as the canonical HTML representation in Trilium:</p><pre><code class=\"language-text-x-trilium-auto\">==highlighted==\n<span style=\"background-color:#e5e64d;--tn-background:#e5e64d;\">Highlighted</span></code></pre></li></ul><h3>Links</h3><p>Multiple types of links are supported:</p><ul><li><p>Web URLs can be written with the standard Markdown syntax:</p><pre><code class=\"language-text-x-trilium-auto\">[Wikipedia](https://www.wikipedia.org)</code></pre></li><li><p><a href=\"#root/_help_hrZ1D00cLbal\">Reference link</a> to other notes with dynamic title, either by manually entering the note ID or via the <em>Add link</em> dialog:</p><pre><code class=\"language-text-x-trilium-auto\">[[B9oMG6rFvvfq]]</code></pre></li><li><p><a href=\"#root/_help_hrZ1D00cLbal\">Reference link</a> to other notes with a custom text:</p><pre><code class=\"language-text-x-trilium-auto\">[This is a link](#root/LhtnZxtVsUMp)</code></pre></li></ul><p>To create a link, either:</p><ul><li>Type it manually using the syntax described above.</li><li>Use the <em>Add link</em> dialog by pressing <kbd>Ctrl</kbd>+<kbd>L</kbd> or typing the <code>/link</code> command.</li></ul><p><a class=\"reference-link\" href=\"#root/_help_UmgZAfcltxkS\">Link Previews</a> are also rendered, but there is no mechanism to insert them automatically as of now, they have to be copied from a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note instead.</p><h3>Keyboard shortcuts</h3><p>The Markdown notes share some of the keyboard shortcuts from <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes:</p><ul><li><em>Cut to note</em> (<kbd>Ctrl</kbd>+<kbd>X</kbd>) which cuts the selection into a new child note.</li><li><em>Add link</em> (<kbd>Ctrl</kbd>+<kbd>L</kbd>) which shows the dialog to create external or reference links.</li><li><em>Date/time</em> (<kbd>Alt</kbd>+<kbd>T</kbd>) which respects the same formatting as text notes.</li><li><em>Include note</em> (not assigned by default), which triggers the same dialog to insert notes as the one for text notes.</li></ul><p>In addition, the following formatting keyboard shortcuts are available:</p><ul><li><kbd>Ctrl</kbd>+<kbd>B</kbd> to toggle <strong>bold</strong>.</li><li><kbd>Ctrl</kbd>+<kbd>I</kbd> to toggle <em>italic</em>.</li><li><kbd>Ctrl</kbd>+<kbd>M</kbd> to wrap the current selection in an inline math (<code>$</code>).</li><li><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd> to toggle <del>strikethrough</del>.</li></ul><h3>Images & attachments</h3><p>Images can be inserted into the document in four different methods:</p><ul><li>Drag & drop directly into the editor area.</li><li>Pasting an image from clipboard.</li><li>Pasting a reference to another <a href=\"#root/_help_0vhv7lsOLy82\">attachment</a> (e.g. <em>Copy reference to clipboard</em> button).</li><li>Use the <code>/image</code> slash command.</li></ul><p>An image reference to an attachment looks like this:</p><pre><code class=\"language-text-x-trilium-auto\"></code></pre><h3>Auto-completion</h3><h4>Slash commands</h4><p>Just like <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, Markdown notes support a selection of slash commands:</p><ul><li>Inserting the current date & time (<code>/date</code>).</li><li><a href=\"#root/_help_nBAXQFj20hS1\">Including</a> another note (<code>/include</code>).</li><li>Uploading and inserting an image (<code>/image</code>).</li><li>Inserting a note link (<code>/link</code>).</li><li>Inserting a math equation block (<code>/math</code>).</li><li>Inserting a <a href=\"#root/_help_AgjCISero73a\">footnote</a> (<code>/footnote</code>).</li><li>Inserting a <a href=\"#root/_help_s1aBHPd79XYj\">Mermaid</a> diagram (<code>/mermaid</code>), with one variant per sample template (e.g. <code>/mermaid:flowchart</code>).</li><li>Inserting a collapsible block (<code>/collapsible</code>).</li><li>Inserting <a href=\"#root/_help_rJ9grSgoExl9\">tabs</a> (<code>/tabs</code>).</li><li>Inserting a page break for printing (<code>/page-break</code>).</li><li>Inserting a table (<code>/table</code>).</li><li>Creating admonitions (e.g. <code>/tip</code>, <code>/note</code>, <code>/important</code>, <code>/caution</code>, <code>/warning</code>).</li><li>Inserting task items (<code>/todo:<state></code>, e.g. <code>/todo:done</code>), one per configured task state.</li><li>Inserting code snippets (<code>/snippet:<name></code>) from your Markdown/plain-text snippet notes.</li></ul><p>The list shows each command by its title, as in Text notes. Typing a command's title, its keyword (as listed above) or a related word such as <code>latex</code> or <code>grid</code> finds it.</p><p>Note that slash commands only work outside of code blocks and inline code.</p><h4>Linking notes with <code>@</code> or <code>[[</code></h4><p>As in <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes, typing <code>@</code> at the start of a line or after a space opens the note search. Picking a note replaces what was typed with a link to it in the Wikilinks-like format (<code>[[noteId]]</code>), which the preview shows as an <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> with the note's title.</p><p>The search runs on everything typed after the <code>@</code>, spaces included, so a title such as <code>@My meeting notes</code> can be typed out; press <kbd>Esc</kbd> to close the list and go on writing. If no note fits, the list offers to create one, as a child of the Markdown note or in the inbox; the link is inserted once the note is created.</p><p>You can also start typing the link directly: <code>[[</code> opens the same list, and closing the brackets yourself dismisses it. To change where an existing link points, place the cursor inside it and pick another note.</p><p>Like slash commands, <code>@</code> and <code>[[</code> do nothing inside code blocks and inline code.</p><p>In the editor, a <code>[[noteId]]</code> link shows as the note's icon and title, so you can tell which note it points to without looking up its ID. Clicking it, or moving the cursor next to it, shows the link as written so it can be edited. Links inside code blocks and inline code are left as they are.</p><h4>Code block language auto-completion</h4><p>Starting with v0.104.0, typing ``` to insert a code block will automatically open a list of suggested language types which have syntax highlighting.</p><p>The list of languages matches the one for <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes set in <a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>, it's not the full list of languages supported by Trilium.</p><h3>Other features</h3><ul><li>The <a class=\"reference-link\" href=\"#root/_help_BFvAtE74rbP6\">Table of contents</a> will be displayed in the <a class=\"reference-link\" href=\"#root/_help_RnaPdbciOfeq\">Right Sidebar</a> based on the Markdown-level headings.</li><li>A Markdown note included in a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note shows its source, its preview or both, and can be edited in place. See <em>Included Markdown</em> in <a class=\"reference-link\" href=\"#root/_help_nBAXQFj20hS1\">Include Note</a>.</li></ul><h3>Shared notes</h3><p>When a Markdown note is <a href=\"#root/_help_R9pX4DGra2Vt\">shared publicly</a>, it will be rendered with extended formatting just like <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes.</p><p>Most of the features described previously should be supported. If you face any issues, feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report it</a> alongside a sample Markdown file.</p><h2>Creating Markdown notes</h2><p>There are two ways to create a Markdown note:</p><ol><li>Create a new note (e.g. in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>) and select the type <em>Markdown</em>, just like all the other note types.</li><li>Create a note of type <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> and select as the language either <em>Markdown</em> or <em>GitHub-Flavored Markdown</em>. This maintains compatibility with your existing notes prior to the introduction of this feature.</li></ol><aside class=\"admonition note\"><p>There is no distinction between the new Markdown note type and code notes of type Markdown; internally both are represented as <a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a> notes with one of the following MIME types:</p><ul><li><code>text/markdown</code></li><li><code>text/x-markdown</code></li><li><code>text/x-gfm</code> (GitHub Flavored Markdown)</li></ul></aside><h2>Import/export</h2><h3>Import</h3><p>By default, when importing a single Markdown file it automatically gets converted to a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note. To avoid that and have it imported as a Markdown note instead:</p><ul><li>Right click the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and select <em>Import into note</em>.</li><li>Select the file normally.</li><li>Uncheck <em>Import HTML, Markdown and TXT as text notes if it's unclear from the metadata</em>.</li></ul><p>When importing a Trilium ZIP, it will preserve the Markdown type without converting to text notes thanks to the meta-information in it.</p><h3>Exporting</h3><p>When exporting Markdown files, the extension is preserved and the content remains the same as in the source view (with some small exceptions such as handling of attachments).</p><p>When exporting Markdown files as ZIP, choosing HTML or Markdown as the export format makes no difference as that only affects <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes.</p><p>If the Markdown note contains attachments, a ZIP export will rewrite the links to attachments so that they are replaced with a relative path to the attachment. On import, the links are re-written back.</p><h2>Conversion between text notes and Markdown notes</h2><p><a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes can be converted into Markdown notes and vice versa. See <a class=\"reference-link\" href=\"#root/_help_jludwdW7N4hg\">Converting between note types</a>.</p><h2>Sync-scrolling & block highlight</h2><p>When scrolling through the editing pane, the preview pane will attempt to synchronize its position to make it easier to see the preview.</p><p>In addition, the block in the preview matching the position of the cursor in the source view will appear slightly highlighted.</p><p>The sync is currently one-way only, scrolling the preview will not synchronize the position of the editor.</p><p>This feature cannot be disabled as of now; if the scrolling feels distracting, consider temporarily switching to the editor mode and then switching to preview mode when ready.</p><aside class=\"admonition note\"><p>This feature of synchronizing the scroll is based on blocks but it's provided on a best-effort basis since our underlying Markdown library doesn't support this feature natively, so we had to implement our own algorithm. Feel free to <a href=\"#root/_help_wy8So3yZZlH9\">report issues</a>, but always provide a sample Markdown file to be able to reproduce it.</p></aside>","_help_jludwdW7N4hg": "<p>A note's type may be converted to another:</p><ul><li><a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> notes to <a class=\"reference-link\" href=\"#root/_help_6RM1Q7ppFVoj\">Markdown</a> notes</li><li>Markdown notes to Text notes</li></ul><p>Before conversion, a revision is saved automatically, so you can restore the original or recover any missing elements from it if the conversion produces undesired results. Read more about <a class=\"reference-link\" href=\"#root/_help_vZWERwf8U3nx\">Note Revisions</a>.</p><h2>Converting individual notes</h2><h3>Markdown to Text Note</h3><p>Markdown notes can be converted to Text Notes with negligible loss of formatting fidelity.</p><p>To do so, go to the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> → <em>Advanced</em> and select <em>Convert to Text Note</em>.</p><h3>Text Note to Markdown</h3><aside class=\"admonition warning\"><p>Since Markdown does not support all the capabilities of Text notes, this conversion is lossy in terms of formatting: some formatting may be lost, and some unsupported elements may even be dropped. It's strongly recommended that you inspect the content for any information that might have gone missing after the conversion.</p></aside><p>To convert a text note to Markdown, go to the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> → <em>Advanced</em> and select <em>Convert to Markdown Note</em>.</p><h2>Converting multiple notes</h2><p>A note type conversion can also be performed on an entire subtree or a set of multiple notes using <a class=\"reference-link\" href=\"#root/_help_ivYnonVFBxbQ\">Bulk Actions</a>.</p>","_help_GTwFsgaA0lCt": "<p>Collections are a unique type of note that don't have content, but instead display their child notes in various presentation methods.</p><h2>Main collections</h2><div class=\"trilium-tabs\"><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-calendar\"></span> Calendar</p><div class=\"trilium-tab-panel\"><p><a class=\"reference-link\" href=\"#root/_help_xWbu3jpNWapp\">Calendar</a> displays a week, month or year calendar with the notes being shown as events. New events can be added easily by dragging across the calendar.</p><figure class=\"image\"><img style=\"aspect-ratio:1651/810;\" src=\"{{helpAssets}}/User%20Guide/Collections_collection_calendar.webp\" width=\"1651\" height=\"810\"></figure></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-table\"></span> Table</p><div class=\"trilium-tab-panel\"><p><a class=\"reference-link\" href=\"#root/_help_2FvYrpmOXm29\">Table</a> displays each note as a row in a table, with <a class=\"reference-link\" href=\"#root/_help_OFXdgB2nNk1F\">Promoted Attributes</a> being shown as well. This makes it easy to visualize attributes of notes, as well as making them easily editable.</p><figure class=\"image\"><img style=\"aspect-ratio:1643/647;\" src=\"{{helpAssets}}/User%20Guide/Collections_collection_table.webp\" width=\"1643\" height=\"647\"></figure></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-columns\"></span> Kanban Board</p><div class=\"trilium-tab-panel\"><p><a class=\"reference-link\" href=\"#root/_help_CtBQqbwXDx1w\">Kanban Board</a> displays notes in columns, grouped by the value of a label. Items and columns can easily be created or dragged around to change their status.</p><figure class=\"image\"><img style=\"aspect-ratio:1174/850;\" src=\"{{helpAssets}}/User%20Guide/Collections_collection_board.webp\" width=\"1174\" height=\"850\"></figure></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-map-alt\"></span> Geo Map</p><div class=\"trilium-tab-panel\"><p><a class=\"reference-link\" href=\"#root/_help_81SGnPGMk7Xc\">Geo Map</a> which displays a geographical map in which the notes are represented as pins on the map. New markers can be easily added by pointing on the map. In addition <a href=\"#root/_help_C2H9HK4BzwG7\">shapes</a> such as paths, rectangles and circles can be added, as well as GPX tracks.</p><figure class=\"image\"><img style=\"aspect-ratio:844/639;\" src=\"{{helpAssets}}/User%20Guide/Collections_collection_geomap.webp\" width=\"844\" height=\"639\"></figure></div></section><section class=\"trilium-tab\"><p class=\"trilium-tab-title\"><span class=\"tn-icon bx bx-slideshow\"></span> Presentation</p><div class=\"trilium-tab-panel\"><p><a class=\"reference-link\" href=\"#root/_help_zP3PMqaG71Ct\">Presentation</a> which shows each note as a slide and can be presented full-screen with smooth transitions or exported to PDF for sharing.</p><figure class=\"image\"><img style=\"aspect-ratio:1120/763;\" src=\"{{helpAssets}}/User%20Guide/Collections_collection_presentation.webp\" width=\"1120\" height=\"763\"></figure></div></section></div><h2>Classic collections</h2><p>Classic collections are read-only mode and compiles the contents of all child notes into one continuous view. This makes it ideal for reading extensive information broken into smaller, manageable segments.</p><ul><li><a class=\"reference-link\" href=\"#root/_help_8QqnMzx393bx\">Grid View</a> which is the default presentation method for child notes (see <a class=\"reference-link\" href=\"#root/_help_0ESUbbAxVnoK\">Note List</a>), where the notes are displayed as tiles with their title and content being visible.</li><li><a class=\"reference-link\" href=\"#root/_help_mULW0Q3VojwY\">List View</a> is similar to <a class=\"reference-link\" href=\"#root/_help_8QqnMzx393bx\">Grid View</a>, but it displays the notes one under the other with the content being expandable/collapsible, but also works recursively.</li></ul><p>Classic collections make use of pagination to support a large number of notes. The size of a page can be customized via <code>pageSize</code>.</p><h2>Creating a new collection</h2><p>To create a new collection, right-click a note in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and select <em>Insert child note</em> → <em>Collection</em> → the desired type.</p><p>By default, collections come with a default configuration and sometimes even sample notes. To create a collection completely from scratch:</p><ol><li>Create a new note of type <em>Text</em> (or any type).</li><li>Change the <a href=\"#root/_help_KSZ04uQ2D1St\">note type</a> to <em>Collection</em>.</li><li>In <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a>, select the desired view type.</li><li>Consult the help page of the corresponding view type in order to understand how to configure them.</li></ol><h2>Configuration</h2><p>To change the configuration of a collection or even switch to a different collection (e.g. from Kanban Board to a Calendar), see the <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a> bar at the top of the note.</p><h2>Archived notes</h2><p>By default, <a href=\"#root/_help_MKmLg5x6xkor\">archived notes</a> will not be shown in collections. This behavior can be changed by going to <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a> and checking <em>Show archived notes</em>.</p><p>Archived notes will be generally indicated by being greyed out as opposed to the normal ones.</p><h2>Hiding the child notes from the note tree</h2><p>For collections with a large number of items, it can be helpful to hide the items from the note tree for performance reasons and to reduce clutter. This is especially useful for standalone collections, such as a geomap or a task board.</p><p>To do so, go to <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a> and select <em>Hide child notes in tree</em>.</p><h2>Advanced use cases</h2><h3>Adding a description to a collection</h3><p>To add a text before the collection, for example to describe it:</p><ol><li>Create a new collection.</li><li>Change the <a href=\"#root/_help_KSZ04uQ2D1St\">note type</a> from <em>Collection</em> to <em>Text</em>.</li></ol><p>Now the text will be displayed above while still maintaining the collection view.</p><p>The only downside to this method is that <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a> will not be shown anymore. In this case, modify the attributes manually or switch back temporarily to the <em>Collection</em> type for configuration purposes.</p><h3>Using saved search</h3><p>Collections, by default, only display the child notes. However, it is possible to use the <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a> functionality to display notes all across the tree, with advanced querying functionality.</p><p>To do so, simply start a <a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a> and go to the <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a> and select a desired type of collection. To keep the search-based collection, use a <a class=\"reference-link\" href=\"#root/_help_m523cpzocqaD\">Saved Search</a>.</p><aside class=\"admonition important\"><p>While in search, none of the collections will not display the child notes of the search results. The reason is that the search might hit a note multiple times, causing an exponential rise in the number of results.</p></aside><h2>Under the hood</h2><p>Collections by themselves are simply notes with no content that rely on the <a class=\"reference-link\" href=\"#root/_help_0ESUbbAxVnoK\">Note List</a> mechanism (the one that lists the children notes at the bottom of a note) to display information.</p><p>By default, new collections use predefined <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a> that are stored safely in the <a class=\"reference-link\" href=\"#root/_help_2mUhVmZK8RF3\">Hidden Notes</a> to define some basic configuration such as the type of view, but also some <a class=\"reference-link\" href=\"#root/_help_OFXdgB2nNk1F\">Promoted Attributes</a> to make editing easier.</p><p>Collections don't store their configuration (e.g. the position on the map, the hidden columns in a table) in the content of the note itself, but as attachments.</p>","_help_xWbu3jpNWapp": "<figure class=\"image\"><img style=\"aspect-ratio:2016/1413;\" src=\"{{helpAssets}}/User%20Guide/Collections/1_Calendar_image.png\" width=\"2016\" height=\"1413\"></figure><p>The Calendar view will display each child note in a calendar that has a start date and optionally an end date, as an event.</p><p>The Calendar view has multiple display modes:</p><ul><li>Month view, where the entire month is displayed and all-day events can be inserted. Both time-specific events and all-day events are listed.</li><li>Week view, where all the 7 days of the week (or 5 if the weekends are hidden) are displayed in columns. This mode allows entering and displaying time-specific events, not just all-day events.</li><li>Day view, which views only a single day. Especially useful for heavy agendas or mobile views.</li><li>List view, which displays all the events of a given month in sequence.</li><li>Year view, which displays the entire year for quick reference.</li></ul><p>Unlike other Collection view types, the Calendar view also allows some kind of interaction, such as moving events around as well as creating new ones.</p><h2>Creating a calendar</h2><p>Right click on an existing note in the <a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and select <em>Insert child note</em> → <em>Collection</em> → <em>Calendar</em>.</p><h2>Creating a new event/note</h2><p>To create a new event:</p><ul><li>First, click the desired day (month & year views) or the desired timeslot (day view).</li><li>Alternatively, drag across multiple days (or time slots) to set both the start and end date.</li></ul><p>In either cases, a small popup will show with a prompt for a title and the date & time of the event that will be created. The date and time can be changed there the same way as in the popup view of an existing event (see below).</p><p>At this point, the event hasn't been created yet to protect against accidental clicks. Add a title optionally and press the <em>Create</em> button. If no title is provided, the event will follow the <a class=\"reference-link\" href=\"#root/_help_47ZrP6FNuoG8\">Default Note Title</a> rules.</p><p>The <span class=\"tn-icon bx bx-detail\"></span> template field below the date and time shows the note type or template the event's note is made from. To make the event from another one, press the field and select it from the list; the calendar remembers the choice for the next event. Select <em>More templates…</em> to change which templates are listed (see <a href=\"#event-templates\">Event templates</a>). The date and time entered for the event replace any dates and times the template carries.</p><p>To give the event a time before creating it (for example, after clicking a day in the month view), press <em>Add time</em> and set the start and end time; the duration is shown to the right of them. To make the event all-day again, press the <span class=\"tn-icon bx bx-x\"></span> button at the end of the row. Adding or removing a time keeps the dates, so an event can start at a time on one day and end at a time on another (for example, a night shift). Changing the start date or time moves the end by the same amount, keeping the duration. An empty end date means the event ends on the day it starts; setting the end time before the start time moves the end date to the next day.</p><p>After creating the event, it will show up on the calendar. To edit the content of the event (including recurrence), click on it to bring it into the popup view.</p><aside class=\"admonition note\"><p>Creating new notes from the calendar will respect the <code>~child:template</code> relation if set on the Collection note.</p></aside><h2>Interacting with events</h2><ul><li>Hovering the mouse over an event will display information about the note.<br><img src=\"{{helpAssets}}/User%20Guide/Collections/4_Calendar_image.png\"></li><li>Left clicking the event will open a dedicated popup to quickly configure the event or edit its note content.</li><li>Right click will offer more options including opening the note in a new split or window.</li><li>Drag and drop an event on the calendar to move it to another day.</li><li>The length of an event can be changed by placing the mouse to the right edge of the event and dragging the mouse around.</li></ul><p>On a <a href=\"#root/_help_CoFPLs3dRlXc\">read-only</a> calendar, events can't be dragged, resized or created, their context menu only offers the places to open them in, and the button to pin the current date is hidden. Switching between the month, week and day views still works, but the choice isn't saved.</p><h3>Popup view</h3><p>When an event is clicked, a popup will show near the event which contains the following inforamtion:</p><ul><li>The title and icon of the event, both editable.</li><li>Buttons to interact with the event:<ul><li>Open the event in the same pane, new tab, etc.</li><li>Color picker to change the color of the event.</li><li>Button to remove the event from the calendar, which can optionally delete its corresponding note.</li></ul></li><li>Calendar-specific features:<ul><li>The start date and, for an event spanning several days, the end date.</li><li>The start and end time with the duration to the right of them, and a <span class=\"tn-icon bx bx-x\"></span> button that removes the time, making the event all-day. An all-day event shows an <em>Add time</em> button instead.</li><li>A full recurrence editor, opened from the dropdown below the time, to have the same event show up weekly, monthly, etc.</li></ul></li><li>The <a class=\"reference-link\" href=\"#root/_help_OFXdgB2nNk1F\">Promoted Attributes</a> of the marker, if any.</li><li>The note's content which can be edited directly from the panel.</li></ul><p>To dismiss the popup:</p><ul><li>Press the X button at the top-right of the popup.</li><li>In the calendar, press anywhere outside the popup.</li><li>Or simply press the <kbd>Escape</kbd> key.</li></ul><p>It is possible to switch between events by clicking on them even when the popup view is already open.</p><p>Events can have <a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a> between them and clicking on such a link will automatically navigate the calendar to the right date and the popup view to the new note.</p><h2>Interaction on mobile</h2><p>When Trilium is on mobile, the interaction with the calendar is slightly different:</p><ul><li>Clicking on an event displays the popup view, which allows editing the event.</li><li>Long-presing an event triggers the contextual menu, including the option to open in <a class=\"reference-link\" href=\"#root/_help_ZjLYv08Rp3qC\">Quick edit</a>.</li><li>To insert a new event, touch and hold the empty space. When successful, the empty space will become colored to indicate the selection.<ul><li>Before releasing, drag across multiple spaces to create multi-day events.</li><li>When released, a prompt will appear to enter the note title.</li></ul></li><li>To move an existing event, touch and hold the event until the empty space near it will become colored.<ul><li>At this point the event can be dragged across other days on the calendar.</li><li>Or the event can be resized by tapping on the small circle to the right end of the event.</li><li>To exit out of editing mode, simply tap the empty space anywhere on the calendar.</li></ul></li></ul><h2>Configuring the calendar view</h2><p>In the <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a>, it's possible to:</p><ul><li>Hide weekends from the week view.</li><li>Display week numbers on the calendar.</li><li>Hide routine events from the month, year and list views (see <a href=\"#hiding-routine-events\">Hiding routine events</a>).</li><li>Set the slot duration (the length of each time row in day/week view).</li><li>Set the slot label interval (how often time labels appear on the axis in day/week view).</li></ul><p>The same settings are also listed under <em>General</em> in the <span class=\"tn-icon bx bx-cog\"></span> <em>Calendar properties</em> dialog (see <a href=\"#event-templates\">Event templates</a> for how to open it). The time slots are listed there whichever view the calendar is in. Its <em>Included notes</em> section sets whether archived notes are shown and how deep the calendar looks for events (see <a href=\"#limiting-the-depth\">Limiting the depth</a>).</p><h3>Event templates</h3><p>By default, a new event is a <a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a> note. To make events from other note types, or from <a class=\"reference-link\" href=\"#root/_help_KC1HB96bqqHX\">Templates</a> with predefined content and attributes (such as a color), open the <span class=\"tn-icon bx bx-cog\"></span> <em>Calendar properties</em> dialog from the <a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> or from the settings menu of the <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a>, and find <em>Event templates</em>. Here you can:</p><ul><li>Include a note type or note template already created in your knowledge base by pressing the <span class=\"tn-icon bx bx-list-plus\"></span> <em>Add existing template</em> button and then selecting the desired note type or template.</li><li>Create a new template by pressing the <span class=\"tn-icon bx bx-plus\"></span> <em>Create a new template</em> button. The template is created as a child of the calendar, and is not shown as an event.</li><li>Press the <span class=\"tn-icon bx bx-x\"></span> button to remove a template from the list. The template is removed only from the list, not deleted.</li><li>Press the <span class=\"tn-icon bx bx-dots-vertical-rounded\"></span> button of a custom template to edit, open in a new window, duplicate, or delete it.</li><li>Drag a template by its handle to reorder the list shown when creating an event.</li></ul><p>The dialog is not available on a read-only calendar, or on a calendar marked with <code>#calendarRoot</code> or <code>#workspaceCalendarRoot</code> (see <a href=\"#using-with-the-journal--calendar\">Using with the Journal / calendar</a>).</p><h3>Event attributes</h3><p>Events can show the values of their attributes below their title, in the month view, and in the week and day views for all-day events and for timed ones tall enough to hold them. To choose which attributes are shown, open the <span class=\"tn-icon bx bx-cog\"></span> <em>Calendar properties</em> dialog (see <a href=\"#event-templates\">Event templates</a> for how to open it) and find <em>Event attributes</em>. It lists the <a class=\"reference-link\" href=\"#root/_help_OFXdgB2nNk1F\">Promoted Attributes</a> the calendar defines, and those its events define themselves. Here you can:</p><ul><li>Turn an attribute on to show it on the events. New attributes are hidden until you turn them on, which keeps the calendar from getting cluttered.</li><li>Drag an attribute by its handle to change the order in which the events show them.</li><li>Create a new attribute, which is shown on the events right away, or edit or delete one the calendar defines.</li></ul><p>The dates, times and recurrence of the events are not listed, as the calendar always shows them itself.</p><p>If an event has a <code>#calendar:displayedAttributes</code> label, including one inherited from the calendar, the attributes listed in that label are shown instead.</p><h2>Configuring the calendar using attributes</h2><p>The following attributes can be added to the Collection type:</p><figure class=\"table\"><table><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>#calendar:hideWeekends</code></td><td>When present (regardless of value), it will hide Saturday and Sundays from the calendar.</td></tr><tr><td><code>#calendar:weekNumbers</code></td><td>When present (regardless of value), it will show the number of the week on the calendar.</td></tr><tr><td><code>#calendar:hideRoutineEvents</code></td><td>When present (regardless of value), it will hide routine events from the month, year and list views. See <a href=\"#hiding-routine-events\">Hiding routine events</a>.</td></tr><tr><td><code>#calendar:initialDate</code></td><td>Change the date the calendar opens on. When not present, the calendar opens on the current date.</td></tr><tr><td><code>#calendar:view</code></td><td><p>Which view to display in the calendar:</p><ul><li><code>timeGridDay</code> for the <em>day</em> view;</li><li><code>timeGridWeek</code> for the <em>week</em> view;</li><li><code>dayGridMonth</code> for the <em>month</em> view;</li><li><code>multiMonthYear</code> for the <em>year</em> view;</li><li><code>listMonth</code> for the <em>list</em> view.</li></ul><p>Any other value will be dismissed and the default view (month) will be used instead.</p><p>The value of this label is automatically updated when changing the view using the UI buttons.</p></td></tr><tr><td><code>#calendar:slotDuration</code></td><td>Sets how long each timeslot is on the calendar. Defaults to <code>00:15:00</code> (15 minutes). Must have the format \"HH:MM:SS\". For example, to create timeslots for every 10 minutes, you would set <code>#calendar:slotDuration=\"00:10:00\"</code>.</td></tr><tr><td><code>#calendar:slotLabelInterval</code></td><td>Sets how often the timeslots on the calendar should be labeled. Defaults to <code>01:00:00</code> (1 hour). Must have the format \"HH:MM:SS\". For example, to label timeslots every 30 minutes, you would set <code>#calendar:slotLabelInterval=\"00:30:00\"</code>.</td></tr><tr><td><code>~child:template</code></td><td>Defines the template for newly created notes in the calendar (via dragging or clicking).</td></tr></tbody></table></figure><p>In addition, the first day of the week can be either Sunday or Monday and can be adjusted from the application settings.</p><h2>Configuring the calendar events using attributes</h2><p>For each note of the calendar, the following attributes can be used:</p><figure class=\"table\"><table><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>#startDate</code></td><td>The date the event starts, which will display it in the calendar. The format is <code>YYYY-MM-DD</code> (year, month and day separated by a minus sign).</td></tr><tr><td><code>#endDate</code></td><td>Similar to <code>startDate</code>, mentions the end date if the event spans across multiple days. The date is inclusive, so the end day is also considered. The attribute can be missing for single-day events.</td></tr><tr><td><code>#startTime</code></td><td>The time the event starts at. If this value is missing, then the event is considered a full-day event. The format is <code>HH:MM</code> (hours in 24-hour format and minutes).</td></tr><tr><td><code>#endTime</code></td><td>Similar to <code>startTime</code>, it mentions the time at which the event ends (in relation with <code>endDate</code> if present, or <code>startDate</code>).</td></tr><tr><td><code>#recurrence</code></td><td>This is an optional CalDAV <code>RRULE</code> string that if present, determines whether a task should repeat or not. Note that it does not include the <code>DTSTART</code> attribute, which is derived from the <code>#startDate</code> and <code>#startTime</code> directly. For examples of valid <code>RRULE</code> strings see <a href=\"https://icalendar.org/rrule-tool.html\">https://icalendar.org/rrule-tool.html</a></td></tr><tr><td><code>#color</code></td><td>Displays the event with a specified color (named such as <code>red</code>, <code>gray</code> or hex such as <code>#FF0000</code>). This will also change the color of the note in other places such as the note tree.</td></tr><tr><td><code>#calendar:color</code></td><td><strong>❌️ Removed since v0.100.0. Use</strong> <code>#color</code> <strong>instead.</strong> <br> <br>Similar to <code>#color</code>, but applies the color only for the event in the calendar and not for other places such as the note tree.</td></tr><tr><td><code>#iconClass</code></td><td>If present, the icon of the note will be displayed to the left of the event title.</td></tr><tr><td><code>#calendar:title</code></td><td>Changes the title of an event to point to an attribute of the note other than the title, can either a label or a relation (without the <code>#</code> or <code>~</code> symbol). See <em>Use-cases</em> for more information.</td></tr><tr><td><code>#calendar:titleTemplate</code></td><td>Changes the title an event is displayed with on the calendar, filled in again for every occurrence of a repeating event. See <em>Use-cases</em> for displaying an age on a birthday.</td></tr><tr><td><code>#calendar:displayedAttributes</code></td><td>Takes precedence over the <a href=\"#event-attributes\">Event attributes</a> chosen in the calendar's properties. Allows displaying the value of one or more attributes in the calendar, in the order given, like this: <br> <br><img src=\"{{helpAssets}}/User%20Guide/Collections/6_Calendar_image.png\"> <br> <br><code>#weight=\"70\" #Mood=\"Good\" #calendar:displayedAttributes=\"weight,Mood\"</code> <br> <br>It can also be used with relations, case in which it will display the title of the target note: <br> <br><code>~assignee=@My assignee #calendar:displayedAttributes=\"assignee\"</code></td></tr><tr><td><code>#calendar:startDate</code></td><td>Allows using a different label to represent the start date, other than <code>startDate</code> (e.g. <code>expiryDate</code>). The label name <strong>must not be</strong> prefixed with <code>#</code>. If the label is not defined for a note, the default will be used instead.</td></tr><tr><td><code>#calendar:endDate</code></td><td>Similar to <code>#calendar:startDate</code>, allows changing the attribute which is being used to read the end date.</td></tr><tr><td><code>#calendar:startTime</code></td><td>Similar to <code>#calendar:startDate</code>, allows changing the attribute which is being used to read the start time.</td></tr><tr><td><code>#calendar:endTime</code></td><td>Similar to <code>#calendar:startDate</code>, allows changing the attribute which is being used to read the end time.</td></tr></tbody></table></figure><h2>How the calendar works</h2><p><img src=\"{{helpAssets}}/User%20Guide/Collections/8_Calendar_image.png\"></p><p>The calendar displays all the child notes of the Collection that have a <code>#startDate</code>. An <code>#endDate</code> can optionally be added.</p><p>A text note with a start date is shown with the <span class=\"tn-icon bx bx-calendar-event\"></span> icon in the note tree and elsewhere, unless it has an icon of its own (set with <code>#iconClass</code>). The start date is read from the label <code>#calendar:startDate</code> names, if any.</p><p>The start date & end date can easily be edited from the calendar collection itself by clicking on the event. To edit the date while in the event note itself, the following attributes can be added to the Collection note:</p><pre><code class=\"language-text-x-trilium-auto\">#viewType=calendar #label:startDate(inheritable)=\"promoted,alias=Start Date,single,date\"\n#label:endDate(inheritable)=\"promoted,alias=End Date,single,date\"\n#hidePromotedAttributes </code></pre><p>This will result in:</p><p><img src=\"{{helpAssets}}/User%20Guide/Collections/7_Calendar_image.png\"></p><p>When not used in a Journal, the calendar is recursive. That is, it will look for events not just in its child notes but also in the children of these child notes.</p><h3>Limiting the depth</h3><p>To limit how deep the calendar looks for events, set <em>Maximum nesting depth</em> under <em>Included notes</em> in the <span class=\"tn-icon bx bx-cog\"></span><em>Calendar properties</em> dialog (see <a href=\"#event-templates\">Event templates</a> for how to open it), or the <code>#maxNestingDepth</code> label: <code>0</code> shows only the child notes, <code>1</code> adds their children, and so on. Without a value, events are looked for at every level. The setting doesn't apply in a Journal.</p><h2>Recurrence</h2><p>The built in calendar view also supports repeating tasks (e.g. every week, every month as well as more complex recurrency rules).</p><p>Starting with v0.105.0, recurrence can be directly edited from the calendar by clicking on an event and then selecting the <em>Repeats</em> option.</p><h3>Custom recurrence using a subset of RRULE</h3><p>If the existing recurrence editor from the event popup is not sufficient, more complex rules can be manually set via the <code>#recurrence</code> label.</p><p>For example, to make a note repeat on the calendar:</p><ul><li>Every Day - <code>#recurrence=\"FREQ=DAILY;INTERVAL=1\"</code></li><li>Every 3 days - <code>#recurrence=\"FREQ=DAILY;INTERVAL=3\"</code></li><li>Every week - <code>#recurrence=\"FREQ=WEEKLY;INTERVAL=1\"</code></li><li>Every 2 weeks on Monday, Wednesday and Friday - <code>#recurrence=\"FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR\"</code></li><li>Every 3 months - <code>#recurrence=\"FREQ=MONTHLY;INTERVAL=3\"</code></li><li>Every 2 months on the First Sunday - <code>#recurrence=\"FREQ=MONTHLY;INTERVAL=2;BYDAY=1SU\"</code></li><li>Every month on the Last Friday - <code>#recurrence=\"FREQ=MONTHLY;INTERVAL=1;BYDAY=-1FR\"</code></li></ul><p>For other examples of valid <code>RRULE</code> strings see <a href=\"https://icalendar.org/rrule-tool.html\">https://icalendar.org/rrule-tool.html</a></p><p>Note that the recurrence string does not include the <code>DTSTART</code> attribute as defined in the iCAL specifications. This is derived directly from the <code>startDate</code> and <code>startTime</code> attributes</p><p>If you want to override the label the calendar uses to fetch the recurrence string, you can use the <code>#calendar:recurrence</code> attribute. For example, you can set <code>#calendar:recurrence=taskRepeats</code>. Then you can set your recurrence string like <code>#taskRepeats=\"FREQ=DAILY;INTERVAL=1\"</code></p><p>Also note that the recurrence label can be made promoted as with the start and end dates. </p><aside class=\"admonition warning\"><p>If the recurrence string is not valid, a toast will be shown with the note ID and title of the note with the erroneous recurrence message. This note will not be added to the calendar</p></aside><h3>Hiding routine events</h3><p>Events that repeat on most days of the week, such as sleep or working hours, fill every cell of the month view. To hide them from the views that show many days at once, check <em>Hide routine events</em> in the <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a> (or set <code>#calendar:hideRoutineEvents</code>).</p><p>An event counts as routine when it has a start time and repeats on 4 or more days a week on average, for example:</p><figure class=\"table\"><table><thead><tr><th>Event</th><th>Days a week</th><th>Hidden from the month, year and list views</th></tr></thead><tbody><tr><td>Every day from 23:00 to 07:00</td><td>7</td><td>Yes</td></tr><tr><td>Monday to Friday from 09:00 to 17:00</td><td>5</td><td>Yes</td></tr><tr><td>Every other day at 07:00</td><td>3.5</td><td>No</td></tr><tr><td>Monday, Wednesday and Friday at 18:00</td><td>3</td><td>No</td></tr><tr><td>Every day, without a start time</td><td>7</td><td>No, as it lasts the whole day</td></tr><tr><td>Every month or every year</td><td>—</td><td>No</td></tr></tbody></table></figure><p>The day and week views always show routine events. To show them everywhere again, uncheck the option.</p><h2>Customizing the slot duration and label interval</h2><p>Time slots in day and week views can be customized from <a class=\"reference-link\" href=\"#root/_help_CssoWBu8I7jF\">Collection Properties</a></p><ul><li><em>Slot duration</em> controls how tall each time slot is on the calendar (essentially the smallest unit of time the grid is divided into).<ul><li>A shorter duration means more rows and finer granularity; a longer one means fewer, chunkier rows.</li><li>The default is one row every 15 minutes.</li></ul></li><li><em>Label interval</em> controls how often a time label appears on the left-hand axis.<ul><li>This is independent of the slot size: you can have very small slots but only label every hour to keep the axis readable.</li><li>The default is a time label shown every hour.</li></ul></li></ul><aside class=\"admonition note\"><p>These values can also be customized directly via the <code>#calendar:slotDuration</code> and <code>#calendar:slotLabelInterval</code> <a href=\"#root/_help_HI6GBBIduIgv\">labels</a>. Both values use <code>HH:mm:ss</code> format. Hours can go up to <code>24</code> (<code>24:00:00</code>), while minutes and seconds must be between <code>00</code> and <code>59</code>. The minimum meaningful duration is 1 minute (<code>00:01:00</code>).</p></aside><h2>Use-cases</h2><h3>Using with the Journal / calendar</h3><p>It is possible to integrate the calendar view into the Journal with day notes. In order to do so change the note type of the Journal note (calendar root) to Collection and then select the Calendar View.</p><p>While in journal mode, the popup editor will not show dates, recurrence, colors or removal, since day notes aren't editable events.</p><p>Based on the <code>#calendarRoot</code> (or <code>#workspaceCalendarRoot</code>) attribute, the calendar will know that it's in a calendar and apply the following:</p><ul><li>The calendar events are now rendered based on their <code>dateNote</code> attribute rather than <code>startDate</code>.</li><li>Interactive editing such as dragging over an empty era or resizing an event is no longer possible.</li><li>Clicking on the empty space on a date will automatically open that day's note or create it if it does not exist.</li><li>Direct children of a day note will be displayed on the calendar despite not having a <code>dateNote</code> attribute. Children of the child notes will not be displayed.</li></ul><img src=\"{{helpAssets}}/User%20Guide/Collections/5_Calendar_image.png\" width=\"1217\" height=\"724\"><h3>Using a different attribute as event title</h3><p><img class=\"image-style-align-right\" src=\"{{helpAssets}}/User%20Guide/Collections/2_Calendar_image.png\" width=\"445\" height=\"124\">By default, events are displayed on the calendar by their note title. However, it is possible to configure a different attribute to be displayed instead.</p><p>To do so, assign <code>#calendar:title</code> to the child note (not the calendar/Collection note), with the value being <code>name</code> where <code>name</code> can be any label (make not to add the <code>#</code> prefix). The attribute can also come through inheritance such as a template attribute. If the note does not have the requested label, the title of the note will be used instead.</p><pre><code class=\"language-text-x-trilium-auto\">#startDate=2025-02-11 #endDate=2025-02-13 #name=\"My vacation\" #calendar:title=\"name\"</code></pre><h3>Using a relation attribute as event title</h3><p><img class=\"image-style-align-right image_resized\" style=\"aspect-ratio:294/151;width:21.22%;\" src=\"{{helpAssets}}/User%20Guide/Collections/3_Calendar_image.png\" width=\"294\" height=\"151\">Similarly to using an attribute, use <code>#calendar:title</code> and set it to <code>name</code> where <code>name</code> is the name of the relation to use.</p><p>Moreover, if there are more relations of the same name, they will be displayed as multiple events coming from the same note.</p><pre><code class=\"language-text-x-trilium-auto\">#startDate=2025-02-14 #endDate=2025-02-15 ~for=@John Smith ~for=@Jane Doe #calendar:title=\"for\"</code></pre><p><img class=\"image-style-align-left\" src=\"{{helpAssets}}/User%20Guide/Collections/Calendar_image.png\" width=\"296\" height=\"150\">Note that it's even possible to have a <code>#calendar:title</code> on the target note (e.g. “John Smith”) which will try to render an attribute of it. Note that it's not possible to use a relation here as well for safety reasons (an accidental recursion of attributes could cause the application to loop infinitely).</p><pre><code class=\"language-text-x-trilium-auto\">#calendar:title=\"shortName\" #shortName=\"John S.\"</code></pre><h3>Displaying an age on a recurring event</h3><p>A birthday or an anniversary repeats every year, and what is interesting about each occurrence is the number of years it marks. To display it:</p><ol><li>Set the event's start date to the original date (for example, the date of birth).</li><li>Click the event, then select the <em>Repeats</em> dropdown.</li><li>Select <em>Yearly</em> and check <em>Show the number of years in the title</em>.</li></ol><p>The event is then displayed as “John Smith (35)” in 2025, “John Smith (36)” in 2026, and so on. Only the calendar is affected; the note keeps its own title.</p><p>The checkbox sets the <code>#calendar:titleTemplate</code> label, which sets the title an event is displayed with and is filled in again for every occurrence the recurrence rule produces:</p><pre><code class=\"language-text-x-trilium-auto\">#startDate=1990-05-12 #recurrence=\"FREQ=YEARLY\" #calendar:titleTemplate=\"${title} (${years})\"</code></pre><p>To word the title differently, edit the label directly. The checkbox is then disabled, as it is when the template is inherited, so that it never overwrites a template of your own.</p><p>The following values can be used in the template:</p><figure class=\"table\"><table><thead><tr><th>Value</th><th>Description</th></tr></thead><tbody><tr><td><code>${title}</code></td><td>The title the event would otherwise be displayed with: the note title, or the attribute <code>#calendar:title</code> points to.</td></tr><tr><td><code>${years}</code></td><td>The whole years between <code>#startDate</code> and the occurrence being displayed. It is <code>0</code> on the first occurrence.</td></tr><tr><td><code>${date}</code></td><td>The date of the occurrence being displayed, as a <a href=\"https://day.js.org/docs/en/display/format\">day.js</a> object. For example, <code>${date.format('YYYY')}</code>.</td></tr><tr><td><code>${startDate}</code></td><td>The date the event starts on, in the same form. For example, <code>${startDate.format('YYYY')}</code>.</td></tr></tbody></table></figure><p>To use the same template for every event of a calendar, make the label inheritable on the Collection note:</p><pre><code class=\"language-text-x-trilium-auto\">#calendar:titleTemplate(inheritable)=\"${title} (${years})\"</code></pre><aside class=\"admonition note\"><p>A template that cannot be read — an unknown value, or an expression other than a value and the <code>format</code> call shown above — leaves the event with its plain title and reports the reason in the browser console.</p></aside>",diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Attachments.md b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Attachments.mdindex 87f52448fd..f952d2646c 100644--- a/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Attachments.md+++ b/docs/User Guide/User Guide/Basic Concepts and Features/Notes/Attachments.md@@ -39,7 +39,7 @@ Links follow changes to their attachment: renaming it updates the title they sho## Embedding an attachment-An attachment can be shown in the text instead of linked, the way <a class="reference-link" href="../../Note%20Types/Text/Include%20Note.md">Include Note</a> shows a note: a picture is displayed, a PDF, a video or a document is previewed, and a code or text file is shown with syntax highlighting. An embedded code file can also be edited in place (see _Editing an include in place_ in <a class="reference-link" href="../../Note%20Types/Text/Include%20Note.md">Include Note</a>).+An attachment can be shown in the text instead of linked, the way <a class="reference-link" href="../../Note%20Types/Text/Include%20Note.md">Include Note</a> shows a note: a picture is displayed, a PDF, a video or a document is previewed, a code or text file is shown with syntax highlighting, and a Markdown file such as a `.md` file is shown rendered. An embedded code file can also be edited in place (see _Editing an include in place_ in <a class="reference-link" href="../../Note%20Types/Text/Include%20Note.md">Include Note</a>), and an embedded Markdown file shows its source, its rendering or both, as an included Markdown note does (see _Included Markdown_ there).* To attach files and embed them straight away, press the <span class="tn-icon cke cke-paper-clip"></span>_Attach file_ button. Each file gets an embed of its own, which shows the file name while the file uploads.* To embed an attachment that is already linked, right-click a link to it in a text note being edited and select _Convert link to an embed_, at the end of the menu.@@ -65,4 +65,4 @@ To do so:## Attachment previews-Attachments share the same content preview for images, videos, PDFs, etc. as the <a class="reference-link" href="../../Note%20Types/File.md">File</a> note type.\ No newline at end of file+Attachments share the same content preview for images, videos, PDFs, etc. as the <a class="reference-link" href="../../Note%20Types/File.md">File</a> note type. A Markdown attachment is previewed rendered, as a <a class="reference-link" href="../../Note%20Types/Markdown.md">Markdown</a> note is.\ No newline at end of filediff --git a/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/Note types with split view.md b/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/Note types with split view.mdindex 276e157fe4..faacfc467a 100644--- a/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/Note types with split view.md+++ b/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/Note types with split view.md@@ -14,6 +14,8 @@ The split comes with three different display modes which can be toggled from theThe display node is stored at note level.+A Markdown note included in a text note, or a Markdown file embedded in one, has the same three display modes, switched from the title row and the toolbar of the include. See _Included Markdown_ in <a class="reference-link" href="../../Note%20Types/Text/Include%20Note.md">Include Note</a>.+## Relation to read-only notesIf a note is marked as [read-only](../Notes/Read-Only%20Notes.md), the source view will not be editable. While in preview mode, marking a note as read-only has no effect since the preview itself is not editable.\ No newline at end of filediff --git a/docs/User Guide/User Guide/Note Types/Markdown.md b/docs/User Guide/User Guide/Note Types/Markdown.mdindex bc7942e815..3625d23939 100644--- a/docs/User Guide/User Guide/Note Types/Markdown.md+++ b/docs/User Guide/User Guide/Note Types/Markdown.md@@ -197,6 +197,7 @@ The list of languages matches the one for <a class="reference-link" href="Code.### Other features* The <a class="reference-link" href="Text/Table%20of%20contents.md">Table of contents</a> will be displayed in the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Right%20Sidebar.md">Right Sidebar</a> based on the Markdown-level headings.+* A Markdown note included in a <a class="reference-link" href="Text.md">Text</a> note shows its source, its preview or both, and can be edited in place. See _Included Markdown_ in <a class="reference-link" href="Text/Include%20Note.md">Include Note</a>.### Shared notesdiff --git a/docs/User Guide/User Guide/Note Types/Text/Include Note.md b/docs/User Guide/User Guide/Note Types/Text/Include Note.mdindex 8574c23125..672ec3f601 100644--- a/docs/User Guide/User Guide/Note Types/Text/Include Note.md+++ b/docs/User Guide/User Guide/Note Types/Text/Include Note.md@@ -66,7 +66,7 @@ To open an included note in a new tab, press the <span class="tn-icon bx bx-linkThe <span class="tn-icon bx bx-dots-vertical-rounded"></span> _More actions_ button at the end of the title row opens the same menu as right-clicking anywhere on the title row: the other places to open the note in and, for an embedded attachment, the actions on the attachment.-In a note being edited, the menu also has the commands of the include's toolbar: the _Size_ submenu, _Show title_ and _Show caption_, each checked while it is in effect, and _Convert to link_ at the end. A drawing canvas, an included text or code note and an embedded code file also have _Editable_, above _Size_. For an embedded attachment they follow its first group of actions; for an included note they end the menu.+In a note being edited, the menu also has the commands of the include's toolbar: the _Size_ submenu, _Show title_ and _Show caption_, each checked while it is in effect, and _Convert to link_ at the end. A drawing canvas, an included text, code or Markdown note and an embedded code or Markdown file also have _Editable_, above _Size_. An included Markdown note and an embedded Markdown file also have _Source view_, _Split view_ and _Preview_ after _Editable_. For an embedded attachment they follow its first group of actions; for an included note they end the menu.To show an include of size _Medium_ or _Full_ on the whole screen, press the <span class="tn-icon bx bx-fullscreen"></span> _Fullscreen_ button at the end of its title. An excerpt of the blocks of a note has an <span class="tn-icon bx bx-pencil"></span> _Edit excerpt_ button there instead; see <a class="reference-link" href="Block%20references.md">Block references</a>. To return, press <span class="tn-icon bx bx-exit"></span> _Exit fullscreen_ in the top-right corner, or <kbd>Esc</kbd>.@@ -106,7 +106,7 @@ In a _Small_ or _Medium_ box, the image is scaled down to fit the height of the## Editing an include in place-An included text note, an included code note and an embedded code file such as a `.js`, `.py` or `.txt` attachment can be edited without leaving the note that includes them. A code note or file is shown with syntax highlighting until then.+An included text note, an included code note and an embedded code file such as a `.js`, `.py` or `.txt` attachment can be edited without leaving the note that includes them. A code note or file is shown with syntax highlighting until then. Included Markdown can be edited too, see _Included Markdown_ below.* To edit, select the include and turn on the <span class="tn-icon bx bx-edit-alt"></span> _Editable_ button at the start of its toolbar, or check _Editable_ in its <span class="tn-icon cke cke-three-vertical-dots"></span> _More actions_ menu. Turn _Editable_ off to return to the preview.* While _Editable_ is on, the arrow keys move the caret into the include and back out, as through the rest of the text. Entering from above or from the left puts the caret at the start of the include, and entering from below or from the right puts it at the end. A collapsed _Expandable_ include is skipped.@@ -120,6 +120,18 @@ An included text note, an included code note and an embedded code file such as a* Editing is not available in a [read-only note](../../Basic%20Concepts%20and%20Features/Notes/Read-Only%20Notes.md), for an included note marked `#readOnly`, or for an attachment of another note.* <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/Navigation/Search%20in%20note.md">Search in note</a> finds the text of included text and code notes among the results of the note around them, and replaces it while _Editable_ is on.+## Included Markdown++An included <a class="reference-link" href="../Markdown.md">Markdown</a> note and an embedded Markdown file, such as a `.md` attachment, are shown with the same three views as a Markdown note in its own tab (see <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20types%20with%20split%20view.md">Note types with split view</a>): <span class="tn-icon bx bx-code"></span> _Source view_, <span class="tn-icon bx bxs-dock-left"></span> _Split view_ and <span class="tn-icon bx bx-show"></span> _Preview_.++* To switch the view, press one of the three buttons in the title row of the include. In a note being edited, the toolbar of the include has the same buttons after _Editable_, and its <span class="tn-icon cke cke-three-vertical-dots"></span> _More actions_ menu has them as _Source view_, _Split view_ and _Preview_.+* Until a view is chosen, the include shows the _Preview_, and the _Split view_ while _Editable_ is on.+* To edit the Markdown, turn on _Editable_ (see _Editing an include in place_ above). The source is edited in the code editor of a Markdown note, and the preview follows the changes as you type. While _Editable_ is off, the source can be read and copied but not changed.+* As in a Markdown note, the preview scrolls along with the source and highlights the block where the cursor is, and <kbd>Ctrl</kbd>+<kbd>B</kbd>, <kbd>Ctrl</kbd>+<kbd>I</kbd>, <kbd>Ctrl</kbd>+<kbd>M</kbd> and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>X</kbd> format the selection.+* In a note being edited, the view is saved with the include, so two includes of the same note can show different views. In a [read-only note](../../Basic%20Concepts%20and%20Features/Notes/Read-Only%20Notes.md), the view can be changed too, until the note is opened again.+* While the source shows, the include has the height of its box size, or the height it was resized to. A _Full_ include gets a fixed height too, instead of fitting its content.+* <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/Navigation/Search%20in%20note.md">Search in note</a> searches the source while it shows, and the preview otherwise.+## Drawing canvasesA drawing canvas is an Excalidraw canvas, like the one of a <a class="reference-link" href="../Canvas.md">Canvas</a> note, drawn directly in the text note. It is not a note of its own: the drawing is kept in a `Canvas.excalidraw` [attachment](../../Basic%20Concepts%20and%20Features/Notes/Attachments.md) of the text note and is saved together with the text.diff --git a/packages/ckeditor5/src/augmentation.ts b/packages/ckeditor5/src/augmentation.tsindex 37502a3b30..b0fda0bb6e 100644--- a/packages/ckeditor5/src/augmentation.ts+++ b/packages/ckeditor5/src/augmentation.ts@@ -80,6 +80,11 @@ declare global {* then turn on and off. The embed carries `data-editable="true"` while it is on.*/hasEditableFlag?: boolean;+ /**+ * Whether the content shows its source, its rendering or both, which the toolbar and the+ * menu of the embed then switch. The embed carries the mode as `data-display-mode`.+ */+ hasDisplayModes?: boolean;}interface EditorComponent extends Component {diff --git a/packages/ckeditor5/src/plugins/content_embed/content_embed.spec.ts b/packages/ckeditor5/src/plugins/content_embed/content_embed.spec.tsindex 6dd8d4a010..ca39f1f1bf 100644--- a/packages/ckeditor5/src/plugins/content_embed/content_embed.spec.ts+++ b/packages/ckeditor5/src/plugins/content_embed/content_embed.spec.ts@@ -15,7 +15,10 @@ import {Widget,type ModelElement} from "ckeditor5";+import bxCode from "boxicons/svg/regular/bx-code.svg?raw";import bxEditAlt from "boxicons/svg/regular/bx-edit-alt.svg?raw";+import bxShow from "boxicons/svg/regular/bx-show.svg?raw";+import bxsDockLeft from "boxicons/svg/solid/bxs-dock-left.svg?raw";import bxWindowAlt from "boxicons/svg/regular/bx-window-alt.svg?raw";import { beforeEach, describe, expect, it, vi } from "vitest";@@ -30,7 +33,11 @@ import ContentEmbed, {COMMAND_NAME,CONVERT_EMBED_TO_LINK_COMMAND,CONVERT_LINK_TO_EMBED_COMMAND,+ CONTENT_EMBED_DISPLAY_MODE_COMMAND,+ CONTENT_EMBED_DISPLAY_MODE_SEPARATOR,CONTENT_EMBED_MENU,+ DISPLAY_MODE_BUTTONS,+ DISPLAY_MODES,TOGGLE_CAPTION_COMMAND_NAME,TOGGLE_EDITABLE_COMMAND_NAME,TOGGLE_TITLE_COMMAND_NAME@@ -1008,7 +1015,7 @@ describe("ContentEmbed with attachments", () => {const states = [ embed, note, tiny, unsized ].map((wrapper) => plugin.getEmbedStateAt(wrapper));- const notEditable = { isEditable: false, isEditableToggleable: false };+ const notEditable = { isEditable: false, isEditableToggleable: false, displayMode: null };expect(states).toEqual([ {...notEditable, boxSize: "small", isTitleShown: true, isTitleToggleable: true,hasCaption: false, isCaptionToggleable: true, isConvertibleToLink: true@@ -1734,6 +1741,168 @@ describe("ContentEmbed editable flag", () => {});});+describe("ContentEmbed display mode", () => {+ const SPLIT = "<figure class=\"include-note\" data-attachment-id=\"a1\""+ + " data-box-size=\"medium\" data-display-mode=\"split\"> </figure>";+ let editor: ClassicEditor;+ let getContentEmbedTools: ReturnType<typeof vi.fn>;++ beforeEach(async () => {+ getContentEmbedTools = vi.fn(() => ({ hasDisplayModes: true }));+ installGlobMock({+ getComponentByEl: () => ({+ loadEmbeddedAttachment: vi.fn(), loadEmbeddedNote: vi.fn(), getContentEmbedTools+ })+ });++ editor = await createTestEditor([ Essentials, Paragraph, Undo, Widget, ContentEmbed ]);+ });++ function getCommand() {+ const command = editor.commands.get(CONTENT_EMBED_DISPLAY_MODE_COMMAND);+ if (!command) {+ throw new Error("Expected the display mode command.");+ }+ return command;+ }++ function getRenderedEmbed() {+ const embed = editor.editing.view.getDomRoot()?.querySelector("figure.include-note");+ if (!embed) {+ throw new Error("Expected a rendered embed.");+ }+ return embed;+ }++ function setSelectedEditable() {+ editor.model.change((writer) => {+ const embed = editor.model.document.selection.getSelectedElement();+ if (embed) writer.setAttribute("editable", true, embed);+ });+ }++ it("loads and saves the mode, drops an unknown one, and marks the embed it renders", () => {+ editor.setData(SPLIT);+ expect(getModelData(editor.model, { withoutSelection: true }))+ .toContain("displayMode=\"split\"");+ expect(editor.getData()).toBe(SPLIT);+ expect(getRenderedEmbed().getAttribute("data-display-mode")).toBe("split");++ editor.setData(SPLIT.replace("\"split\"", "\"other\""));+ expect(getModelData(editor.model, { withoutSelection: true })).not.toContain("displayMode");+ expect(getRenderedEmbed().hasAttribute("data-display-mode")).toBe(false);+ });++ it("tells the mode, which follows Editable for editable content until one is picked", () => {+ getContentEmbedTools.mockReturnValue({ hasDisplayModes: true, hasEditableFlag: true });+ editor.setData(SPLIT.replace(" data-display-mode=\"split\"", ""));+ const embed = editor.model.document.getRoot()?.getChild(0) ?? null;+ editor.model.change((writer) => writer.setSelection(embed, "on"));+ const command = getCommand();+ expect([ command.isEnabled, command.value ]).toEqual([ true, "preview" ]);++ setSelectedEditable();+ expect(command.value).toBe("split");++ // Content that cannot be edited has no Editable toggle, and shows the preview.+ getContentEmbedTools.mockReturnValue({ hasDisplayModes: true });+ editor.ui.update();+ expect(command.value).toBe("preview");+ });++ it("switches the mode as one undo step, keeping the Editable flag", () => {+ getContentEmbedTools.mockReturnValue({ hasDisplayModes: true, hasEditableFlag: true });+ const embed = insertContentEmbed(editor, "n1", "medium");+ editor.model.change((writer) => writer.setAttribute("editable", true, embed));+ const wrapper = getRenderedEmbed().querySelector(".include-note-wrapper");++ editor.execute(CONTENT_EMBED_DISPLAY_MODE_COMMAND, { value: "source" });+ expect(getCommand().value).toBe("source");+ expect(getRenderedEmbed().getAttribute("data-display-mode")).toBe("source");+ expect(editor.getData()).toContain("data-display-mode=\"source\"");+ expect(editor.getData()).toContain("data-editable=\"true\"");++ editor.execute("undo");+ expect(getCommand().value).toBe("split");+ expect(getRenderedEmbed().hasAttribute("data-display-mode")).toBe(false);+ expect(getRenderedEmbed().querySelector(".include-note-wrapper")).toBe(wrapper);+ });++ it("is offered only for content that has display modes", () => {+ insertContentEmbed(editor, "n1", "medium");+ expect(getCommand().isEnabled).toBe(true);++ getContentEmbedTools.mockReturnValue({ hasEditableFlag: true });+ editor.ui.update();+ expect(getCommand().isEnabled).toBe(false);+ expect(getCommand().value).toBeNull();+ expect(editor.plugins.get(ContentEmbed).getEmbedStateAt(getRenderedEmbed()))+ .toMatchObject({ displayMode: null });++ getContentEmbedTools.mockReturnValue({ hasDisplayModes: true });+ expect(editor.plugins.get(ContentEmbed).getEmbedStateAt(getRenderedEmbed()))+ .toMatchObject({ displayMode: "preview" });+ });++ it("separates the display modes from the Editable toggle, while both show", () => {+ const separator = editor.ui.componentFactory.create(CONTENT_EMBED_DISPLAY_MODE_SEPARATOR);+ separator.render();+ insertContentEmbed(editor, "n1", "medium");+ const isShown = () => !separator.element?.classList.contains("ck-hidden");+ expect(separator.element?.classList.contains("ck-toolbar__separator")).toBe(true);+ expect(isShown()).toBe(false);++ getContentEmbedTools.mockReturnValue({ hasEditableFlag: true, hasDisplayModes: true });+ editor.ui.update();+ expect(isShown()).toBe(true);++ getContentEmbedTools.mockReturnValue({ hasEditableFlag: true });+ editor.ui.update();+ expect(isShown()).toBe(false);+ });++ it("offers a button per mode, on while it is the mode and shown only while enabled", () => {+ const buttons = DISPLAY_MODES.map((mode) => {+ const button = editor.ui.componentFactory.create(DISPLAY_MODE_BUTTONS[mode]);+ if (!(button instanceof ButtonView)) {+ throw new Error("Expected a button.");+ }+ return button;+ });+ const focus = vi.spyOn(editor.editing.view, "focus");+ insertContentEmbed(editor, "n1", "medium");+ expect(buttons.map((button) => button.label))+ .toEqual([ "Source view", "Split view", "Preview" ]);+ expect(buttons.map((button) => [ button.icon, button.isToggleable ]))+ .toEqual([ [ bxCode, true ], [ bxsDockLeft, true ], [ bxShow, true ] ]);+ expect(buttons.map((button) => [ button.isOn, button.isVisible ]))+ .toEqual([ [ false, true ], [ false, true ], [ true, true ] ]);++ buttons[0].fire("execute");+ expect(getCommand().value).toBe("source");+ expect(buttons.map((button) => button.isOn)).toEqual([ true, false, false ]);+ expect(focus).toHaveBeenCalled();++ getContentEmbedTools.mockReturnValue(null);+ editor.ui.update();+ expect(buttons.map((button) => button.isVisible)).toEqual([ false, false, false ]);+ });++ it("changes nothing when no embed is selected", () => {+ editor.setData(SPLIT + "<p>after</p>");+ setModelData(editor.model, "<paragraph>foo[]bar</paragraph>");+ const before = editor.getData();++ // The decorated `Command#execute()` skips a disabled command, so the command is forced+ // enabled to run `execute()` with no embed selected.+ const command = getCommand();+ command.isEnabled = true;+ command.execute({ value: "source" });++ expect(editor.getData()).toBe(before);+ });+});+describe("ContentEmbed resizing", () => {const RESIZED = "<figure class=\"include-note\""+ " style=\"--include-note-height:12.5em;--include-note-width:30em;\""diff --git a/packages/ckeditor5/src/plugins/content_embed/content_embed.ts b/packages/ckeditor5/src/plugins/content_embed/content_embed.tsindex 82a4e3bc7b..b68f17635d 100644--- a/packages/ckeditor5/src/plugins/content_embed/content_embed.ts+++ b/packages/ckeditor5/src/plugins/content_embed/content_embed.ts@@ -7,6 +7,7 @@ import {IconCaption,IconLink,IconThreeVerticalDots,+ type Locale,type MapperModelToViewPositionEvent,ModelElement,type ModelNode,@@ -16,12 +17,16 @@ import {Plugin,toWidget,toWidgetEditable,+ View,type ViewEditableElement,type ViewElement,Widget,type Observable} from 'ckeditor5';+import codeIcon from 'boxicons/svg/regular/bx-code.svg?raw';import editIcon from 'boxicons/svg/regular/bx-edit-alt.svg?raw';+import showIcon from 'boxicons/svg/regular/bx-show.svg?raw';+import dockLeftIcon from 'boxicons/svg/solid/bxs-dock-left.svg?raw';import windowIcon from 'boxicons/svg/regular/bx-window-alt.svg?raw';import noteIcon from '../../icons/note.svg?raw';import { encodeBlockParameter, parseBlockRange } from '@triliumnext/commons';@@ -38,6 +43,9 @@ export const TOGGLE_CAPTION_COMMAND_NAME = 'toggleContentEmbedCaption';export const TOGGLE_TITLE_COMMAND_NAME = 'toggleContentEmbedTitle';export const TOGGLE_EDITABLE_COMMAND_NAME = 'toggleContentEmbedEditable';export const CODE_VIEW_COMMAND_NAME = 'setContentEmbedCodeView';+export const CONTENT_EMBED_DISPLAY_MODE_COMMAND = 'contentEmbedDisplayMode';+/** The toolbar separator between the Editable toggle and the display modes. */+export const CONTENT_EMBED_DISPLAY_MODE_SEPARATOR = 'contentEmbedDisplayModeSeparator';/** The toolbar button that opens the context menu of an embed whose title is hidden. */export const CONTENT_EMBED_MENU = 'contentEmbedMenu';@@ -45,6 +53,24 @@ export const BOX_SIZES = [ 'tiny', 'small', 'medium', 'full', 'expandable' ] asexport type BoxSizeValue = typeof BOX_SIZES[number];+/** What content with display modes shows: its source, its rendering, or both side by side. */+export const DISPLAY_MODES = [ 'source', 'split', 'preview' ] as const;++export type DisplayModeValue = typeof DISPLAY_MODES[number];++/** The toolbar button of each display mode. */+export const DISPLAY_MODE_BUTTONS: Record<DisplayModeValue, string> = {+ source: 'contentEmbedDisplayMode:source',+ split: 'contentEmbedDisplayMode:split',+ preview: 'contentEmbedDisplayMode:preview'+};++const DISPLAY_MODE_ICONS: Record<DisplayModeValue, string> = {+ source: codeIcon,+ split: dockLeftIcon,+ preview: showIcon+};+/** The box sizes that can be resized. Tiny and Full fit their content. */const RESIZABLE_BOX_SIZES: unknown[] = [ 'small', 'medium', 'expandable' ];@@ -59,6 +85,9 @@ const FLAG_ATTRIBUTES = [type EmbedFlag = typeof FLAG_ATTRIBUTES[number][0];+/** The display mode of an embed, saved in a `data-*` attribute while one is picked. */+const DISPLAY_MODE_ATTRIBUTE = [ 'displayMode', 'data-display-mode' ] as const;+/*** How an embed of an attachment shows its code: the language, as a MIME type, the tab width, and* whether it indents with tabs. Each is saved in a `data-*` attribute while it is set.@@ -82,6 +111,8 @@ export interface ContentEmbedState {isEditable: boolean;/** Whether the content has an editable mode, which its content type opts in to. */isEditableToggleable: boolean;+ /** What the content shows, for content that has display modes, otherwise `null`. */+ displayMode: DisplayModeValue | null;boxSize: BoxSizeValue | null;/** Whether the title shows, which a Tiny or an Expandable embed always does. */isTitleShown: boolean;@@ -118,6 +149,18 @@ export function getBoxSizeLabel(t: (message: string) => string, size: BoxSizeVal}}+/** The user-facing name of a display mode, as literal `t()` calls for the same reason. */+export function getDisplayModeLabel( t: ( message: string ) => string, mode: DisplayModeValue ) {+ switch ( mode ) {+ case 'source':+ return t( 'Source view' );+ case 'split':+ return t( 'Split view' );+ case 'preview':+ return t( 'Preview' );+ }+}+export default class ContentEmbed extends Plugin {/** The buttons that the content of the selected embed adds to its toolbar, or `null`. */declare public selectedEmbedTools: ContentEmbedToolProvider | null;@@ -175,6 +218,9 @@ export default class ContentEmbed extends Plugin {return {isEditable: !!embed.getAttribute( 'editable' ),isEditableToggleable: isEmbedEditableToggleable( editor, embed ),+ displayMode: hasEmbedDisplayModes( editor, embed )+ ? getEmbedDisplayMode( editor, embed )+ : null,boxSize: embed.getAttribute( 'boxSize' ) as BoxSizeValue | undefined ?? null,isTitleShown: !isTitleToggleable || !embed.getAttribute( 'hideTitle' ),isTitleToggleable,@@ -303,6 +349,42 @@ class ContentEmbedUI extends Plugin {return buttonView;} );+ editor.ui.componentFactory.add( CONTENT_EMBED_DISPLAY_MODE_SEPARATOR, locale => {+ const separator = new ToolbarItemSeparatorView( locale );+ separator.bind( 'isVisible' ).to(+ editor.plugins.get( ContentEmbed ), 'selectedEmbedTools',+ tools => !!tools?.hasEditableFlag && !!tools.hasDisplayModes );+ return separator;+ } );++ for ( const mode of DISPLAY_MODES ) {+ editor.ui.componentFactory.add( DISPLAY_MODE_BUTTONS[ mode ], locale => {+ const command = editor.commands.get( CONTENT_EMBED_DISPLAY_MODE_COMMAND );+ const buttonView = new ButtonView( locale );++ buttonView.set( {+ label: getDisplayModeLabel( t, mode ),+ icon: DISPLAY_MODE_ICONS[ mode ],+ tooltip: true,+ isToggleable: true+ } );++ // Shown only for content that has display modes.+ if ( command ) {+ buttonView.bind( 'isOn' ).to( command, 'value', value => value === mode );+ buttonView.bind( 'isEnabled' ).to( command );+ buttonView.bind( 'isVisible' ).to( command, 'isEnabled' );+ }++ this.listenTo( buttonView, 'execute', () => {+ editor.execute( CONTENT_EMBED_DISPLAY_MODE_COMMAND, { value: mode } );+ editor.editing.view.focus();+ } );++ return buttonView;+ } );+ }+editor.ui.componentFactory.add( TOGGLE_TITLE_COMMAND_NAME, locale => {const command = editor.commands.get( TOGGLE_TITLE_COMMAND_NAME );const buttonView = new ButtonView( locale );@@ -394,6 +476,8 @@ class ContentEmbedEditing extends Plugin {commands.add(TOGGLE_EDITABLE_COMMAND_NAME, new ToggleContentEmbedEditableCommand( editor ) );commands.add( CODE_VIEW_COMMAND_NAME, new SetContentEmbedCodeViewCommand( editor ) );+ commands.add(+ CONTENT_EMBED_DISPLAY_MODE_COMMAND, new ContentEmbedDisplayModeCommand( editor ) );editor.model.document.registerPostFixer( writer => this.removeTinyCaptions( writer ) );@@ -428,8 +512,8 @@ class ContentEmbedEditing extends Plugin {// An embed shows either a note or an attachment. An embed that// `FileUploadEditing` is uploading carries the upload attributes instead of its id.allowAttributes: [- 'noteId', 'block', 'attachmentId', 'boxSize', 'hideTitle', 'editable', 'uploadId',- 'uploadStatus', 'uploadFileName',+ 'noteId', 'block', 'attachmentId', 'boxSize', 'hideTitle', 'editable',+ 'displayMode', 'uploadId', 'uploadStatus', 'uploadFileName',...CODE_VIEW_ATTRIBUTES.map( ( [ setting ] ) => setting )],@@ -467,6 +551,7 @@ class ContentEmbedEditing extends Plugin {...embedded,boxSize: viewElement.getAttribute( 'data-box-size' ),...getFlagsOfView( viewElement ),+ ...getDisplayModeOfView( viewElement ),...getCodeViewOfView( viewElement )} );},@@ -484,6 +569,7 @@ class ContentEmbedEditing extends Plugin {...getEmbeddedEntityAttributes( modelElement ),'data-box-size': modelElement.getAttribute( 'boxSize' ),...getFlagAttributes( modelElement ),+ ...getDisplayModeAttributes( modelElement ),...getCodeViewAttributes( modelElement )} );}@@ -499,6 +585,7 @@ class ContentEmbedEditing extends Plugin {...getEmbeddedEntityAttributes( modelElement ),'data-box-size': boxSize,...getFlagAttributes( modelElement ),+ ...getDisplayModeAttributes( modelElement ),...getCodeViewAttributes( modelElement )} );@@ -557,9 +644,11 @@ class ContentEmbedEditing extends Plugin {} );// Marks the view of the embed without drawing the content again. Content with an- // editable mode reads `data-editable` from the embed, and a code file the- // `data-code-*` attributes.- const markedAttributes = [ ...FLAG_ATTRIBUTES, ...CODE_VIEW_ATTRIBUTES ];+ // editable mode reads `data-editable` from the embed, content with display modes+ // `data-display-mode`, and a code file the `data-code-*` attributes.+ const markedAttributes = [+ ...FLAG_ATTRIBUTES, DISPLAY_MODE_ATTRIBUTE, ...CODE_VIEW_ATTRIBUTES+ ];for ( const [ attribute, dataAttribute ] of markedAttributes ) {dispatcher.on( `attribute:${ attribute }:contentEmbed`, ( _evt, data, api ) => {const viewElement = api.mapper.toViewElement( data.item as ModelElement );@@ -851,6 +940,37 @@ export class SetContentEmbedCodeViewCommand extends Command {}}+/**+ * Sets what the content of the selected embed shows, for content that has display modes. The+ * Editable flag stays as it is: it tells whether the source shown can be changed.+ */+export class ContentEmbedDisplayModeCommand extends Command {+ /** The mode of the selected embed, or `null`. */+ declare value: DisplayModeValue | null;++ constructor( editor: Editor ) {+ super( editor );+ // Content declares its display modes once it renders, which changes nothing in the model.+ this.listenTo( editor.ui, 'update', () => this.refresh(), { priority: 'high' } );+ }++ override refresh() {+ const embed = getSelectedContentEmbed( this.editor );++ this.isEnabled = !!embed && hasEmbedDisplayModes( this.editor, embed );+ this.value = embed && this.isEnabled ? getEmbedDisplayMode( this.editor, embed ) : null;+ }++ override execute( { value }: { value: DisplayModeValue } ) {+ const embed = getSelectedContentEmbed( this.editor );+ if ( !embed ) {+ return;+ }++ this.editor.model.change( writer => writer.setAttribute( 'displayMode', value, embed ) );+ }+}+/** Sets the flag of the selected embed when it is off, and removes it when it is on. */function toggleSelectedEmbedFlag( editor: Editor, flag: EmbedFlag ) {const embed = getSelectedContentEmbed( editor );@@ -1016,6 +1136,27 @@ function isEmbedEditableToggleable( editor: Editor, embed: ModelElement ) {return !!getEmbedTools( editor, embed )?.hasEditableFlag;}+/** Whether the content of `embed` has display modes, which its content type opts in to. */+function hasEmbedDisplayModes( editor: Editor, embed: ModelElement ) {+ return !!getEmbedTools( editor, embed )?.hasDisplayModes;+}++/**+ * What the content of `embed` shows: its mode, or split while it is edited and preview otherwise.+ * Content that cannot be edited has no Editable toggle, and shows the preview.+ */+function getEmbedDisplayMode( editor: Editor, embed: ModelElement ): DisplayModeValue {+ const isEditing = !!embed.getAttribute( 'editable' )+ && isEmbedEditableToggleable( editor, embed );+ return toDisplayMode( embed.getAttribute( 'displayMode' ) )+ ?? ( isEditing ? 'split' : 'preview' );+}++/** `value` when it names a display mode, otherwise `null`. */+export function toDisplayMode( value: unknown ): DisplayModeValue | null {+ return DISPLAY_MODES.find( mode => mode === value ) ?? null;+}+/** Whether `embed` can have a caption. A Tiny embed has none. */function isEmbedCaptionToggleable( editor: Editor, embed: ModelElement ) {return embed.getAttribute( 'boxSize' ) !== 'tiny'@@ -1112,6 +1253,18 @@ function getFlagsOfView( viewElement: ViewElement ): Partial<Record<EmbedFlag, t.map( ( [ flag ] ) => [ flag, true ] ) );}+/** The `data-display-mode` attribute of `element`, when it has a display mode. */+function getDisplayModeAttributes( element: ModelElement ): Record<string, string> {+ const mode = toDisplayMode( element.getAttribute( 'displayMode' ) );+ return mode ? { 'data-display-mode': mode } : {};+}++/** The display mode that the `data-display-mode` attribute of a saved embed names. */+function getDisplayModeOfView( viewElement: ViewElement ): { displayMode?: DisplayModeValue } {+ const mode = toDisplayMode( viewElement.getAttribute( 'data-display-mode' ) );+ return mode ? { displayMode: mode } : {};+}+/** Whether the content of the selected embed, whose buttons are `tools`, hides `name`. */export function isToolbarItemHidden(tools: ContentEmbedToolProvider | null,@@ -1445,5 +1598,27 @@ declare module 'ckeditor5' {toggleContentEmbedTitle: ToggleContentEmbedTitleCommand;toggleContentEmbedEditable: ToggleContentEmbedEditableCommand;setContentEmbedCodeView: SetContentEmbedCodeViewCommand;+ contentEmbedDisplayMode: ContentEmbedDisplayModeCommand;+ }+}++/** A toolbar separator that shows only while `isVisible`, as the items on both sides do. */+class ToolbarItemSeparatorView extends View {+ declare public isVisible: boolean;++ constructor( locale?: Locale ) {+ super( locale );+ this.set( 'isVisible', false );++ this.setTemplate( {+ tag: 'span',+ attributes: {+ class: [+ 'ck',+ 'ck-toolbar__separator',+ this.bindTemplate.if( 'isVisible', 'ck-hidden', isVisible => !isVisible )+ ]+ }+ } );}}diff --git a/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.spec.ts b/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.spec.tsindex 71dbd8ced4..47a07e44ff 100644--- a/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.spec.ts+++ b/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.spec.ts@@ -102,13 +102,17 @@ describe("ContentEmbedToolbar", () => {expect(requires).toContain(ContentEmbedTools);});- it("offers the Editable toggle, the content's tools, then the embed's own items", () => {+ it("offers Editable, the display modes, the content's tools, then the embed's items", () => {const repository = editor.plugins.get(WidgetToolbarRepository) as unknown as {_toolbarDefinitions: Map<string, { itemsConfig: string[] }>;};expect(repository._toolbarDefinitions.get("contentEmbed")?.itemsConfig).toEqual([TOGGLE_EDITABLE_COMMAND_NAME,+ "contentEmbedDisplayModeSeparator",+ "contentEmbedDisplayMode:source",+ "contentEmbedDisplayMode:split",+ "contentEmbedDisplayMode:preview",CONTENT_EMBED_TOOLS,"contentEmbedBoxSizeDropdown",TOGGLE_TITLE_COMMAND_NAME,diff --git a/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.ts b/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.tsindex 0e5000459d..e9f8272659 100644--- a/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.ts+++ b/packages/ckeditor5/src/plugins/content_embed/content_embed_toolbar.ts@@ -2,6 +2,9 @@ import { Plugin, WidgetToolbarRepository, isWidget, type ViewElement } from "ckeimport ContentEmbed, {CONVERT_EMBED_TO_LINK_COMMAND,CONTENT_EMBED_MENU,+ CONTENT_EMBED_DISPLAY_MODE_SEPARATOR,+ DISPLAY_MODE_BUTTONS,+ DISPLAY_MODES,TOGGLE_CAPTION_COMMAND_NAME,TOGGLE_EDITABLE_COMMAND_NAME,TOGGLE_TITLE_COMMAND_NAME@@ -26,6 +29,8 @@ export default class ContentEmbedToolbar extends Plugin {widgetToolbarRepository.register("contentEmbed", {items: [TOGGLE_EDITABLE_COMMAND_NAME,+ CONTENT_EMBED_DISPLAY_MODE_SEPARATOR,+ ...DISPLAY_MODES.map((mode) => DISPLAY_MODE_BUTTONS[mode]),CONTENT_EMBED_TOOLS,CONTENT_EMBED_BOX_SIZE_DROPDOWN,TOGGLE_TITLE_COMMAND_NAME,