Skip to content

Build your personal knowledge base with Trilium Notes

fix(markdown): keep anchors in Markdown exports

Elian Doran76624f5e2200
diff --git a/apps/server/src/assets/help/help_content.json b/apps/server/src/assets/help/help_content.json
index b9776b1dea..6f9dbaee41 100644
--- a/apps/server/src/assets/help/help_content.json
+++ b/apps/server/src/assets/help/help_content.json
@@ -99,7 +99,7 @@
"_help_w4rMEhJsALlA": "<h2>Using different fonts</h2><p>Trilium comes by default with its own font (<em>Inter</em>), but the font can be adjusted in&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;→ <em>Appearance</em>, by checking <em>Use different fonts</em> in the <em>Fonts</em> section.</p><p>The font can be personalized for the following areas of the application:</p><ul><li>Interface text, for most of the UI (menus, toolbars, dialogs).</li><li><a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>.</li><li>Document text, for the actual content of the notes (especially for&nbsp;<a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a>&nbsp;notes).</li><li>Monospace text, e.g. for&nbsp;<a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a>&nbsp;notes and&nbsp;<a class=\"reference-link\" href=\"#root/_help_QxEyIjRBizuC\">Code blocks</a>.</li></ul><p>Each area also has its own <em>Size</em>. The note tree and document sizes are relative to the interface size, so changing the interface size moves them along with it.</p><p>The list of fonts contains the following items:</p><ul><li><strong>Generic fonts</strong><ul><li><em>Theme defined</em> which uses the font that is embedded with the current <a href=\"#root/_help_Wy267RK4M69c\">theme</a>. For example on the default modern theme, the font is <em>Inter</em>. This does not require the font to be installed.</li><li><em>System default</em> which uses a combination of fonts that works best for the <a href=\"#root/_help_poXkQfguuA0U\">desktop app</a>. For example on Windows it will use <em>Segoe UI</em>.</li><li>Generic font selections for fonts with serifs (e.g. <em>Times New Roman</em>-like), no serifs and monospace.</li></ul></li><li><strong>Web fonts</strong> which appear on the&nbsp;<a class=\"reference-link\" href=\"#root/_help_WOcw2SLH6tbX\">Server Installation</a>, which is a predefined list of fonts and grouped into Sans-serif, serif, monospace and handwriting. The fonts that are not supported by your system (i.e. not installed) are not displayed.</li><li><strong>System fonts</strong> which appear on the&nbsp;<a class=\"reference-link\" href=\"#root/_help_poXkQfguuA0U\">Desktop Installation</a>. Unlike the server fonts which are predefined, the system fonts are listed from your operating system.</li><li><strong>Custom fonts</strong>, allowing any font to be used provided it's imported into Trilium. See the section below for more information.</li></ul><p>Font changes take effect after a reload; the section offers a <em>Reload to apply changes</em> button once something has been changed.</p><h2>Custom fonts</h2><p>A font file imported into Trilium can be used by the application itself, without writing any CSS.</p><h3>Adding a font</h3><ol><li>Import the font file, by dragging it into the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>&nbsp;or through <em>Import into note</em>. TrueType (<code>.ttf</code>), OpenType (<code>.otf</code>) and Web Open Font Format (<code>.woff</code>, <code>.woff2</code>) files are recognized; the note takes the font's name without its extension and is marked with a font icon (an “A” icon).</li><li>Select the resulting note where a preview of a font will be displayed: a specimen line to type your own text into, a slider for its size, a preview in multiple sizes, and the Latin character set.</li><li>Turn on <em>In font picker</em> above the specimen.</li><li>In&nbsp;<a class=\"reference-link\" href=\"#root/_help_4TIF1oA4VQRO\">Options</a>&nbsp;→ <em>Appearance</em> → <em>Fonts</em>, the font is now offered under <em>Custom fonts</em>, ahead of the built-in families, and can be set for any of the four areas.</li></ol><aside class=\"admonition note\"><p>Embedded OpenType (<code>.eot</code>) files and TrueType collections (<code>.ttc</code>) cannot be drawn by the browser, so they are treated as ordinary files: no preview, and no entry in the picker.</p></aside><h3>How custom fonts behave</h3><ul><li>Each entry is named after its note, so renaming the note renames the entry. The setting refers to the note itself rather than to its name, and keeps working across a rename.</li><li>The font file is an ordinary note, so&nbsp;<a class=\"reference-link\" href=\"#root/_help_cbkrhQjrkKrh\">Synchronization</a>&nbsp;carries it to your other devices. The choice of font is not synced: appearance settings are deliberately kept per-device, so on another device the font is already there and only needs to be selected again.</li><li>A font kept in a <a href=\"#root/_help_bwg0e8ewQMak\">protected note</a> can only be previewed and used while the protected session is open.</li></ul><p>For theme authors, a font can also be embedded in a theme's CSS through&nbsp;<a class=\"reference-link\" href=\"#root/_help_d3fAXQ2diepH\">Custom Resource Providers</a>, which is the route to take when the font should come with the theme rather than be chosen in the settings.</p><h3>Downloading from Google Fonts</h3><p>A large selection of fonts can be easily retrieved from Google Fonts, as follows:</p><ol><li>Go to <a href=\"https://fonts.google.com\">https://fonts.google.com</a>.</li><li>Search for a desired font.</li><li>Press <em>Get font</em> in the top right.</li><li>Check that the list of fonts on the left side corresponds to your selection.</li><li>Press <em>Download all</em>.</li><li>In the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, create a note where to store the new fonts.</li><li>In the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, drag-and-drop the .zip file directly onto the newly created note and follow the steps from the previous section.</li></ol><h2>Programming ligatures</h2><p>Some fonts support programming ligatures, which will turn character combinations such as <code>!=</code> into <code>≠</code> or <code>-&gt;</code> as <code>→</code> in&nbsp;<a class=\"reference-link\" href=\"#root/_help_QxEyIjRBizuC\">Code blocks</a>&nbsp;and&nbsp;<a class=\"reference-link\" href=\"#root/_help_6f9hih2hXXZk\">Code</a>&nbsp;notes.</p><p>These are only a display affordance, so copying the text is not affected. Regardless, this feature can be disabled in Trilium by unchecking <em>Programming ligatures</em> in the font settings.</p>",
"_help_mHbBMPDPkVV5": "<p>To import a note:</p><ul><li>The easiest way to import is to simply drag &amp; drop a file or an archive into the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>.<ul><li>This will automatically detect some formats such as&nbsp;<a class=\"reference-link\" href=\"#root/_help_iWD7wiIuMtgV\">Obsidian</a>.</li><li><em>Safe import</em> is automatically on to prevent accidental running of foreign scripts.</li></ul></li><li>To configure an import, there is a dedicated dialog which can be accessed from either&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>&nbsp;→ <em>Import into note</em> or&nbsp;<a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>&nbsp;→ <em>Import into note</em>.<ul><li>This feature allows for dedicated importers for others apps such as&nbsp;<a class=\"reference-link\" href=\"#root/_help_iWD7wiIuMtgV\">Obsidian</a>&nbsp;or&nbsp;<a class=\"reference-link\" href=\"#root/_help_GnhlmrATVqcH\">Microsoft OneNote</a>.</li><li><em>Safe import</em> as well as other options can be configured from the collapsed <em>Options</em> section at the bottom.</li></ul></li></ul><p>To export a note, right click the note in the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>&nbsp;and select <em>Export</em>. Similarly, in&nbsp;<a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>&nbsp;there is a <em>Export note</em> option.</p><h2>Supported formats</h2><p>Trilium natively supports the following formats for both import and export.</p><ul><li>HTML:<ul><li>This is the main format used by Trilium, where standard tags are used to represent basic formatting and layout (e.g. <code>&lt;strong&gt;</code>, <code>&lt;table&gt;</code>, <code>&lt;pre&gt;</code>).</li><li>Note that HTML is not a standardized format so some more specific features such as admonitions or&nbsp;<a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>&nbsp;might not be supported by other applications.</li><li>The notes can also be exported as <a href=\"#root/_help_ycBFjKrrwE9p\">static HTML that can be used for web publishing</a>.</li></ul></li><li><a class=\"reference-link\" href=\"#root/_help_Oau6X9rCuegd\">Markdown</a><ul><li>Most of the formatting is preserved, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_rJ9grSgoExl9\">Supported syntax</a>.</li></ul></li><li>OPML (Outliner Interchange Format)<ul><li>Supports both OPML v1.0 for plain text and v2.0 with HTML support.</li></ul></li></ul><p>To import from other applications such as OneNote, Notion and others, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_ckZ2uNWQmVeX\">Importing data from other applications</a>.</p><h2>Maximum import size</h2><p>Versions prior to v0.104.0 had an upload limit of 250 MiB that could be bypassed via a <code>TRILIUM_NO_UPLOAD_LIMIT</code> environment variable; with v0.104.0 this limit was removed.</p><p>Nevertheless, there is still a limit for the maximum size of a <strong>single item</strong> (whether it's a&nbsp;<a class=\"reference-link\" href=\"#root/_help_W8vYD3Q1zjCR\">File</a>, an&nbsp;<a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>&nbsp;or even a&nbsp;<a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a>&nbsp;note). The limit is approximately 374 MiB and it's determined by the&nbsp;<a class=\"reference-link\" href=\"#root/_help_cbkrhQjrkKrh\">Synchronization</a>&nbsp;protocol. Attempts to import such large files will be refused.</p><p>During large imports or exports, memory consumption might spike but it will remain somewhere around the 2 gigabyte mark. Tested with a 2.4 GB database with ~21k notes.</p><aside class=\"admonition important\"><p>For the&nbsp;<a class=\"reference-link\" href=\"#root/_help_poXkQfguuA0U\">Desktop Installation</a>, there are two distinct import mechanisms:</p><ul><li>A quick import, from the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>.</li><li>The import dialog (via right click in the note tree → <em>Import into note</em> or from&nbsp;<a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>).</li></ul><p>When dealing with large files (multi-gigabyte), prefer using the import dialog as it has a special mechanism which makes sure that the file is read directly from disk rather than uploaded again.</p></aside><h2>Exporting the root note</h2><p>The root note is the top-most note. Exporting it behaves just like any other note: right click on it in the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>&nbsp;and select <em>Export</em>.</p><p>Starting with v0.104.0, when a root note is imported, it will be imported as a child of your existing root note. This behavior makes sure that the import cannot change or overwrite your existing notes.</p><p>You can easily move the notes onto the root using the tree's&nbsp;<a class=\"reference-link\" href=\"#root/_help_yTjUdsOi4CIE\">Multiple selection</a>&nbsp;and delete the redundant root note.</p><figure class=\"table\"><table><thead><tr><th scope=\"col\">Before</th><th scope=\"col\">After</th></tr></thead><tbody><tr><td><ul><li>root<ul><li>one</li><li>two</li></ul></li></ul></td><td><ul><li>root (existing)<ul><li>root (from import)<ul><li>one</li><li>two</li></ul></li></ul></li></ul></td></tr></tbody></table></figure><aside class=\"admonition tip\"><p>Instead of exporting full ZIPs (including the root note), consider using <a href=\"#root/_help_ODY7qQn5m2FT\">backups</a> instead. Backups always contain the entire structure, as well as additional information a ZIP export does not have: maintains note IDs, contains the options/tokens and handle&nbsp;<a class=\"reference-link\" href=\"#root/_help_bwg0e8ewQMak\">Protected Notes</a>&nbsp;better.</p></aside><h2>Exporting the User Guide</h2><p>The in-app User Guide can be exported like any other note: right click one of its pages or chapters in the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a> and select <em>Export</em>, or use&nbsp;<a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a> → <em>Export note</em>.</p><ul><li>Exporting a chapter with <em>This note &amp; all descendants</em> writes the pictures and files of each page as its attachments. Importing that archive creates an ordinary copy that you can edit, with its pictures and the links between its pages working.</li><li>Exporting a single page with <em>Only this note</em> embeds its pictures in the exported file.</li></ul>",
"_help_Oau6X9rCuegd": "<p>Trilium supports Markdown for both import and export, while trying to keep compatibility as high as possible.</p><h2>Import</h2><h3>Clipboard import</h3><p>If you want to import just a chunk of markdown from clipboard, you can do it from editor block menu:</p><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Import%20%26%20Export/Markdown_markdown-inline-import.gif\"></p><h3>File import</h3><p>You can also import Markdown files from files:</p><ul><li>single markdown file (with .md extension)</li><li>whole tree of markdown files (packaged into <a href=\"https://en.wikipedia.org/wiki/Tar_(computing)\">.zip</a> archive)<ul><li>Markdown files need to be packaged into ZIP archive because browser can't read directories, only single files.</li><li>You can use e.g. <a href=\"https://www.7-zip.org\">7-zip</a> to package directory of markdown files into the ZIP file</li></ul></li></ul><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Import%20%26%20Export/Markdown_markdown-file-import.gif\"></p><h2>Export</h2><h3>Subtree export</h3><p>You can export whole subtree to ZIP archive which will have directory structured modelled after subtree structure:</p><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Import%20%26%20Export/Markdown_markdown-export-subtree.gif\"></p><h3>Single note export</h3><p>If you want to export just single note without its subtree, you can do it from Note actions menu:</p><p><img src=\"{{helpAssets}}/User%20Guide/Basic%20Concepts%20and%20Features/Import%20%26%20Export/Markdown_markdown-export-note.gif\"></p><h3>Exporting protected notes</h3><p>If you want to export protected notes, enter a protected session first! This will export the notes in an unencrypted form, so if you reimport into Trilium, make sure to re-protect these notes.</p><h2>Supported syntax</h2><p>See the dedicated page:&nbsp;<a class=\"reference-link\" href=\"#root/_help_rJ9grSgoExl9\">Supported syntax</a></p>",
- "_help_rJ9grSgoExl9": "<p><a href=\"https://github.github.com/gfm/\">GitHub-Flavored Markdown</a> is the main syntax that Trilium is following.</p><h2>Images</h2><p>When exporting, images are usually kept in the basic Markdown syntax but will use the HTML syntax if the image has a custom width. Figures are always embedded as HTML.</p><h2>Tables</h2><p>Simple tables are supported with the Markdown syntax. If the table is too complex or contains elements that would render as HTML, the table is also rendered as HTML.</p><h2>Links</h2><p>Standard Markdown links are supported.</p><p>Trilium internal links (that mirror a note's title and display its icon) are embedded as HTML in order to preserve the information on import.</p><h2>Math equations</h2><p>Both inline and display equations are supported, using the <code>$</code> and <code>$$</code> syntaxes.</p><h2>Admonitions</h2><p>The Markdown syntax for admonitions as supported by Trilium is the one that GitHub uses, which is as follows:</p><pre><code class=\"language-text-x-trilium-auto\">&gt; [!NOTE]\n&gt; This is a note.\n\n&gt; [!TIP]\n&gt; This is a tip.\n\n&gt; [!IMPORTANT]\n&gt; This is a very important information.\n\n&gt; [!CAUTION]\n&gt; This is a caution.</code></pre><p>There are currently no plans of supporting alternative admonition syntaxes such as <code>!!! note</code>.</p><h2>Tabs</h2><p>Tabs use the syntax of <a href=\"https://squidfunk.github.io/mkdocs-material/reference/content-tabs/\">Material for MkDocs</a>: each tab starts with a <code>=== \"Title\"</code> line, followed by its content indented by four spaces. Consecutive tabs form one tabs block, and <code>===!</code> starts a new block right after another one:</p><pre><code class=\"language-text-x-trilium-auto\">=== \"Windows\"\n\n Run the **installer**.\n\n=== \"Linux\"\n\n Use the package.\n\n===! \"Another block\"\n\n This tab starts a separate tabs block.</code></pre><p>Tabs can be nested by indenting the inner tabs inside the content of a tab. A tab title is plain text, so its formatting is not kept on export. For how tabs blocks work in a text note, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_EK2ckIZ74tbT\">Content tabs</a>.</p><h2>Wikilinks</h2><p>Basic support for wikilinks has been added in v0.96.0:</p><ul><li><code>[[foo/bar]]</code> will look for the <code>bar.md</code> file in the <code>foo</code> directory and turn it into an internal link.</li><li><code>![[foo/baz.png]]</code> will look for the <code>baz.png</code> file in the <code>foo</code> directory and turn it into an image.</li></ul><p>This feature is import-only, which means that it will turn wikilinks into Trilium-compatible syntax, but it will not export Trilium Notes into Markdown files with this syntax.</p><aside class=\"admonition important\"><p>The path to pages in wikilinks is resolved relatively to the <em>import root</em> and not the current directory of the note. This is to be inline with other platforms that use wikilinks such as SilverBullet.</p><p>The root path of the import is determined as follows:</p><ul><li>If there is a single directory within the archive at root level, then that directory is considered the root.</li><li>If there are multiple files &amp; directories at root level, then the archive root (containing all of these items) is considered the root.</li></ul></aside><h2>Highlights</h2><p>Background highlights are supported in two ways:</p><ul><li><p>The Markdown <code>==</code> extension which is supported by other Markdown-based applications such as Obsidian:</p><pre><code class=\"language-text-x-trilium-auto\">==highlighted==</code></pre></li><li><p>The canonical HTML representation of highlights, as supported by Trilium:</p><pre><code class=\"language-text-html\">&lt;span style=\"background-color:hsl(0,0%,100%);\"&gt;Highlighted&lt;/span&gt;</code></pre></li></ul><p>When the yellow highlight is used, import/export prefers the <code>==</code> syntax whereas the canonical HTML reprepresentation is used otherwise.</p>",
+ "_help_rJ9grSgoExl9": "<p><a href=\"https://github.github.com/gfm/\">GitHub-Flavored Markdown</a> is the main syntax that Trilium is following.</p><h2>Images</h2><p>When exporting, images are usually kept in the basic Markdown syntax but will use the HTML syntax if the image has a custom width. Figures are always embedded as HTML.</p><h2>Tables</h2><p>Simple tables are supported with the Markdown syntax. If the table is too complex or contains elements that would render as HTML, the table is also rendered as HTML.</p><h2>Links</h2><p>Standard Markdown links are supported.</p><p>Trilium internal links (that mirror a note's title and display its icon) are embedded as HTML in order to preserve the information on import.</p><p><a class=\"reference-link\" href=\"#root/_help_oSuaNgyyKnhu\">Anchors</a> are kept as HTML as well, so links to an anchor still lead to it after the note is imported again.</p><h2>Math equations</h2><p>Both inline and display equations are supported, using the <code>$</code> and <code>$$</code> syntaxes.</p><h2>Admonitions</h2><p>The Markdown syntax for admonitions as supported by Trilium is the one that GitHub uses, which is as follows:</p><pre><code class=\"language-text-x-trilium-auto\">&gt; [!NOTE]\n&gt; This is a note.\n\n&gt; [!TIP]\n&gt; This is a tip.\n\n&gt; [!IMPORTANT]\n&gt; This is a very important information.\n\n&gt; [!CAUTION]\n&gt; This is a caution.</code></pre><p>There are currently no plans of supporting alternative admonition syntaxes such as <code>!!! note</code>.</p><h2>Tabs</h2><p>Tabs use the syntax of <a href=\"https://squidfunk.github.io/mkdocs-material/reference/content-tabs/\">Material for MkDocs</a>: each tab starts with a <code>=== \"Title\"</code> line, followed by its content indented by four spaces. Consecutive tabs form one tabs block, and <code>===!</code> starts a new block right after another one:</p><pre><code class=\"language-text-x-trilium-auto\">=== \"Windows\"\n\n Run the **installer**.\n\n=== \"Linux\"\n\n Use the package.\n\n===! \"Another block\"\n\n This tab starts a separate tabs block.</code></pre><p>Tabs can be nested by indenting the inner tabs inside the content of a tab. A tab title is plain text, so its formatting is not kept on export. For how tabs blocks work in a text note, see&nbsp;<a class=\"reference-link\" href=\"#root/_help_EK2ckIZ74tbT\">Content tabs</a>.</p><h2>Wikilinks</h2><p>Basic support for wikilinks has been added in v0.96.0:</p><ul><li><code>[[foo/bar]]</code> will look for the <code>bar.md</code> file in the <code>foo</code> directory and turn it into an internal link.</li><li><code>![[foo/baz.png]]</code> will look for the <code>baz.png</code> file in the <code>foo</code> directory and turn it into an image.</li></ul><p>This feature is import-only, which means that it will turn wikilinks into Trilium-compatible syntax, but it will not export Trilium Notes into Markdown files with this syntax.</p><aside class=\"admonition important\"><p>The path to pages in wikilinks is resolved relatively to the <em>import root</em> and not the current directory of the note. This is to be inline with other platforms that use wikilinks such as SilverBullet.</p><p>The root path of the import is determined as follows:</p><ul><li>If there is a single directory within the archive at root level, then that directory is considered the root.</li><li>If there are multiple files &amp; directories at root level, then the archive root (containing all of these items) is considered the root.</li></ul></aside><h2>Highlights</h2><p>Background highlights are supported in two ways:</p><ul><li><p>The Markdown <code>==</code> extension which is supported by other Markdown-based applications such as Obsidian:</p><pre><code class=\"language-text-x-trilium-auto\">==highlighted==</code></pre></li><li><p>The canonical HTML representation of highlights, as supported by Trilium:</p><pre><code class=\"language-text-html\">&lt;span style=\"background-color:hsl(0,0%,100%);\"&gt;Highlighted&lt;/span&gt;</code></pre></li></ul><p>When the yellow highlight is used, import/export prefers the <code>==</code> syntax whereas the canonical HTML reprepresentation is used otherwise.</p>",
"_help_ckZ2uNWQmVeX": "<p>Starting with version v0.104.0, Trilium's importer was expanded to application-specific imports. Unlike the standard HTML or&nbsp;<a class=\"reference-link\" href=\"#root/_help_Oau6X9rCuegd\">Markdown</a>&nbsp;import/export, these importers are tailored to support the features and note structure of a particular application.</p><h2>Supported applications</h2><ul><li><a class=\"reference-link\" href=\"#root/_help_GnhlmrATVqcH\">Microsoft OneNote</a>, by connecting to your account using Microsoft Graph.</li><li><a class=\"reference-link\" href=\"#root/_help_Y5mKeJ6dsCld\">Notion</a>, via a ZIP export.</li><li><a class=\"reference-link\" href=\"#root/_help_nhQVuO4zvIxi\">Google Keep</a>, via a ZIP export from <em>Google Takeout</em> (Keep has no dedicated export mechanism).</li><li><a class=\"reference-link\" href=\"#root/_help_syuSEKf2rUGr\">Evernote</a>, via an ENEX export.</li><li><a class=\"reference-link\" href=\"#root/_help_83zmPBJRgfnW\">Anytype</a>, via a JSON export.</li><li><a class=\"reference-link\" href=\"#root/_help_iWD7wiIuMtgV\">Obsidian</a>, via a ZIP of the vault.</li></ul><h2>Importing data from another application</h2><p>To import from an application, there are two ways to access the import dialog:</p><ul><li>In the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, right click on a note and select <em>Import into note</em>.</li><li>In the&nbsp;<a class=\"reference-link\" href=\"#root/_help_8YBEPzcpUgxw\">Note menu</a>, select <em>Import files</em>.</li></ul><p>A list of supported applications will appear at the top, each with their own configuration. Simply click one and proceed with the on-screen instructions.</p><h2>Acknowledgement</h2><ul><li>Trilium's importer is inspired by Obsidian's <a href=\"https://github.com/obsidianmd/obsidian-importer\">Importer plugin</a> (licensed under the MIT license), for example regarding the OneNote connection process or the Notion ID management.</li></ul>",
"_help_GnhlmrATVqcH": "<p>Trilium allows importing from OneNote. Currently the only mechanism supported is via the Microsoft Graph API which requires you to authenticate in a browser in order for the notes to be obtained by Trilium.</p><h2>Import process</h2><ol><li>In the&nbsp;<a class=\"reference-link\" href=\"#root/_help_oPVyFC7WL2Lp\">Note Tree</a>, right click and select <em>Import into note</em>.</li><li>In the <em>Import from</em> section, select&nbsp;<span class=\"tn-icon tn-brand tn-brand-onenote\"></span> <em>OneNote</em>.</li><li>Press the <em>Connect</em> button:<ol><li>On the desktop app, you will be redirected to Microsoft's authentication screen where you can log into your account.</li><li>On the web app, the process is slightly more involved as it requires copying the code to clipboard, accessing the link, pasting the code and then signing in once more.</li></ol></li><li>After the connection is successful, you should be able to see a list of sections that can be imported. Simply check the ones to import and press the <em>Import selected</em> button.</li><li>Wait for the import to finish.</li></ol><h2>Supported features</h2><p>The following features are preserved by Trilium during the import process:</p><ul><li>Basic formatting (bold, italic, underline, strikethrough, subscript, super script, font sizes, headings, colors, highlights).<ul><li>Black-colored text is intentionally stripped to allow it to work in dark themes.</li></ul></li><li>Inline code is automatically detected and formatted. Paragraphs that use the Code style are also converted to&nbsp;<a class=\"reference-link\" href=\"#root/_help_QxEyIjRBizuC\">Code blocks</a>.<ul><li>Unfortunately the indentation of the code might be lost because the information is simply not present in the data from the Microsoft API.</li></ul></li><li><a class=\"reference-link\" href=\"#root/_help_S6Xx8QIWTV66\">Lists</a>&nbsp;with different bullet types.</li><li><a class=\"reference-link\" href=\"#root/_help_NdowYOC1GFKS\">Tables</a><ul><li>Cell backgrounds are preserved, including a best-effort hue correction because the colors returned by the Graph API are sometimes incorrect.</li><li>Cell widths are also preserved proportionally, with the only difference that tables in Trilium have a percentage-based width, not fixed pixel sizes.</li></ul></li><li>Images and&nbsp;<a class=\"reference-link\" href=\"#root/_help_0vhv7lsOLy82\">Attachments</a>.<ul><li>Screen clippings are also properly supported since v0.104.1, displaying their timestamp as a figure caption.</li></ul></li><li>To-do lists</li><li>Hand-drawing is preserved and displayed as an SVG image inside the note<ul><li>OneNote's default color (black) is special since it also renders as white for dark themes. Since v0.104.1, this is also supported by using a special SVG tweak which reacts to light/dark themes.</li></ul></li><li>Links between other imported pages are converted to&nbsp;<a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>&nbsp;if the text of the link matches the name of the page, or plain links otherwise. If the pages are not part of the import, the original <code>onenote:</code> link is kept.</li><li>Tags (apart from to-do lists) are preserved by converting them to <a href=\"#root/_help_hD8GawVuazff\">inline icons</a>, which are searchable by the icon's name and can be recolored like any other icon. Some icons are turned into emojis instead.</li></ul><p>Regarding the note structure:</p><ul><li>The order of the pages within a section is maintained.</li><li>Sub-pages and section groups are maintained by nesting notes in a hierarchical structure.</li><li>Creation and modification of both notes and sections is preserved. The order of section or section groups is not preserved (see limitations).</li></ul><h2>Error management and reporting</h2><p>The OneNote importer uses Microsoft's Graph API which handles the HTML export (that we later post-process for Trilium use). The Graph API itself has to process the OneNote pages before sending them to us, and as such it's a time-consuming operation that is directly proportional to the number of notes and the complexity/size of the notes.</p><p>The Graph API throttles access if it detects too many operations. The importer takes that into account, but sometimes this means that most of the time is spent waiting for the Graph API to unblock access rather than actually importing data.</p><p>In addition, some pages may fail at the Graph API level due to an internal timeout on their side or other issues. Trilium will try to refetch pages in order to avoid that but sometimes pages cannot be retrieved even after multiple retries. In that case, the importer will still create a corresponding note in Trilium but with an error report instead of a content. This preserves&nbsp;<a class=\"reference-link\" href=\"#root/_help_hrZ1D00cLbal\">Internal (reference) links</a>&nbsp;and makes it easy to identify and manually fix the pages that failed.</p><p>At the end of the import, the top-level note called <em>OneNote</em> <em>import</em> will contain information about how the import went:</p><ul><li>The number of notes imported;</li><li>The success rate;</li><li>A list of notes that could not be imported, as well as the failure reason;</li><li>Pages whose images/attachments failed to download</li><li>How long the import spent waiting out throttling.</li></ul><p>To avoid cases in which the import is fundamentally broken (e.g. an expired sign-in), the import will error out if it fails to import 6 pages in a row.</p><h2>Attributes</h2><p>Pages imported from OneNote have a few built-in <a href=\"#root/_help_HI6GBBIduIgv\">labels</a>:</p><ul><li><code>oneNotePageId</code>, with the corresponding page ID in OneNote. This can be used to identify the original OneNote page. Trilium doesn't use it in any way at this moment.</li><li><code>oneNoteImportFailed</code> attached to notes that couldn't be imported. This can be used to quickly&nbsp;<a class=\"reference-link\" href=\"#root/_help_eIg8jdvaoNNd\">Search</a>&nbsp;for failed notes.</li></ul><h2>Limitations</h2><h3>Regarding OneNote's freehand structure</h3><p>OneNote is fundamentally different to Trilium in structure because it allows freehand drawing to coexist with text, and text boxes can be placed anywhere in the document (e.g. a common use case is to have columns). Trilium has a document flow mechanism for&nbsp;<a class=\"reference-link\" href=\"#root/_help_iPIMuisry3hd\">Text</a>&nbsp;notes which means that it can't be freely positioned.</p><p>To cope with this difference, Trilium will flatten the text structure into normal paragraphs. The paragraphs will be ordered visually based on the original position of the text boxes, but their horizontal position will not be preserved. Parallel text such as columns may appear interleaved which can cause problems.</p><p>In addition, drawing in OneNote can be interleaved with text boxes. Text notes in Trilium do not allow for this feature, so all drawing will appear at the end. For some use cases (diagrams, for example) this will work fine, but if you have highlights or other text-dependent drawings they will appear out of order.</p><aside class=\"admonition note\"><p>There are plans to support drawing-heavy notes that interleave with text boxes by converting them to a&nbsp;<a class=\"reference-link\" href=\"#root/_help_grjYqerjn243\">Canvas</a>&nbsp;instead.</p></aside><h3>Password-protected sections</h3><p>OneNote supports encryption at section level; when importing a notebook that contains these password-protection sections, Trilium will not be able to read the content of password-protected sections so they will appear empty. This is not a limitation of Trilium, the information is simply not available from the source (Graph API).</p><p>The section itself is kept for reference and all the sections that could not be imported will be shown in the report (the top-level note called <em>OneNote import</em>).</p><p>To unprotect a section in OneNote Desktop, right click on the protected section → <em>Password Protect This Section</em> and press <em>Remove Password</em> and sync. Then re-import either only the protected sections or remove everything and start the import from scratch.</p><h2>Other limitations</h2><p>The following are known limitations due to how the information comes from the import (Microsoft Graph API), which means that they cannot be fixed.</p><ul><li>The order of the sections (and section groups) is not available, the sections are ordered by creation date instead.</li><li>Revision history.</li><li>Paragraph indentation, as well as code block indentation.</li><li>Section colors.</li><li>Drawings inside titles, the title might appear incomplete or “Untitled”.</li></ul><h2>Reporting issues</h2><p>When importing notes, you might find that some text is not rendered properly or the structure is not properly maintained. As long as this issue is not a fundamental issue (like the issue with freehand text not being preserved exactly), it's a good idea to <a href=\"#root/_help_wy8So3yZZlH9\">report it</a>.</p><p>When reporting, make sure that you provide the following information:</p><ul><li>Import again the section, checking the debug checkbox before importing. This preserves the original document (and the hand-drawing data if any) as it came through from OneNote's cloud API so that it can be used for comparison.</li><li>Export only the affected page as ZIP, making sure not to accidentally expose any sensitive information.</li><li>Take screenshots of how the note looked like in OneNote and how it ends up in Trilium.</li><li>Attach the ZIP and the screenshots to the issue report.</li></ul>",
"_help_LpvyEIBIAAj7": "<p>OneNote's <em>Tags</em> functionality is imported in Trilium as&nbsp;<a class=\"reference-link\" href=\"#root/_help_hD8GawVuazff\">Icons</a>&nbsp;using the default icon pack or emojis (if there is no suitable replacement).</p><aside class=\"admonition important\"><p>Custom tags are not supported by OneNote's Graph API so Trilium cannot import them.</p></aside><h3>Decorative tags</h3><p>These remain formatted as paragraphs, with the glyph prepended to the text. A paragraph can carry several tags at once, in which case their glyphs stack.</p><figure class=\"table\"><table><thead><tr><th>OneNote tag</th><th><code>data-tag</code></th><th>Imported as</th><th>Searchable as</th></tr></thead><tbody><tr><td>Important</td><td><code>important</code></td><td><span class=\"tn-icon bx bx-star\"></span></td><td><code>star</code></td></tr><tr><td>Critical</td><td><code>critical</code></td><td><span class=\"tn-icon bx bx-error-circle\"></span></td><td><code>error-circle</code></td></tr><tr><td>Question</td><td><code>question</code></td><td><span class=\"tn-icon bx bx-help-circle\"></span></td><td><code>help-circle</code></td></tr><tr><td>Highlight</td><td><code>highlight</code></td><td><span class=\"tn-icon bx bx-highlight\"></span></td><td><code>highlight</code></td></tr><tr><td>Definition</td><td><code>remember-for-later</code></td><td><span class=\"tn-icon bx bx-pin\"></span></td><td><code>pin</code></td></tr><tr><td>Remember for later</td><td><code>remember-for-later</code></td><td><span class=\"tn-icon bx bx-pin\"></span></td><td><code>pin</code></td></tr><tr><td>Remember for blog</td><td><code>remember-for-blog</code></td><td><span class=\"tn-icon bx bx-edit\"></span></td><td><code>edit</code></td></tr><tr><td>Idea</td><td><code>idea</code></td><td><span class=\"tn-icon bx bx-bulb\"></span></td><td><code>bulb</code></td></tr><tr><td>Password</td><td><code>password</code></td><td><span class=\"tn-icon bx bx-key\"></span></td><td><code>key</code></td></tr><tr><td>Contact</td><td><code>contact</code></td><td><span class=\"tn-icon bx bx-user\"></span></td><td><code>user</code></td></tr><tr><td>Address</td><td><code>address</code></td><td><span class=\"tn-icon bx bx-home\"></span></td><td><code>home</code></td></tr><tr><td>Phone number</td><td><code>phone-number</code></td><td><span class=\"tn-icon bx bx-phone\"></span></td><td><code>phone</code></td></tr><tr><td>Web site to visit</td><td><code>web-site-to-visit</code></td><td><span class=\"tn-icon bx bx-globe\"></span></td><td><code>globe</code></td></tr><tr><td>Source for article</td><td><code>source-for-article</code></td><td><span class=\"tn-icon bx bx-news\"></span></td><td><code>news</code></td></tr><tr><td>Send in email</td><td><code>send-in-email</code></td><td><span class=\"tn-icon bx bx-envelope\"></span></td><td><code>envelope</code></td></tr><tr><td>Movie to see</td><td><code>movie-to-see</code></td><td><span class=\"tn-icon bx bx-movie\"></span></td><td><code>movie</code></td></tr><tr><td>Book to read</td><td><code>book-to-read</code></td><td><span class=\"tn-icon bx bx-book\"></span></td><td><code>book</code></td></tr><tr><td>Music to listen to</td><td><code>music-to-listen-to</code></td><td><span class=\"tn-icon bx bx-music\"></span></td><td><code>music</code></td></tr><tr><td>Project A</td><td><code>project-a</code></td><td>🅰️</td><td>🅰️</td></tr><tr><td>Project B</td><td><code>project-b</code></td><td>🅱️</td><td>🅱️</td></tr></tbody></table></figure><h3>Check box tags</h3><p>These become&nbsp;<a class=\"reference-link\" href=\"#root/_help_fASfBrYnquKU\">To-do Lists</a>, with the glyph inside the item with the tick state preserved:</p><figure class=\"table\"><table><thead><tr><th>OneNote tag</th><th><code>data-tag</code></th><th>Imported as</th><th>Searchable as</th></tr></thead><tbody><tr><td>To Do</td><td><code>to-do</code></td><td><em>(none)</em></td><td>—</td></tr><tr><td>To Do priority 1</td><td><code>to-do-priority-1</code></td><td>1️⃣</td><td>1️⃣</td></tr><tr><td>To Do priority 2</td><td><code>to-do-priority-2</code></td><td>2️⃣</td><td>2️⃣</td></tr><tr><td>Discuss with Person A</td><td><code>discuss-with-person-a</code></td><td><span class=\"tn-icon bx bx-message-rounded\"></span></td><td><code>message-rounded</code></td></tr><tr><td>Discuss with Person B</td><td><code>discuss-with-person-b</code></td><td><span class=\"tn-icon bx bx-message-rounded\"></span></td><td><code>message-rounded</code></td></tr><tr><td>Discuss with manager</td><td><code>discuss-with-manager</code></td><td><span class=\"tn-icon bx bx-conversation\"></span></td><td><code>conversation</code></td></tr><tr><td>Schedule meeting</td><td><code>schedule-meeting</code></td><td><span class=\"tn-icon bx bx-calendar\"></span></td><td><code>calendar</code></td></tr><tr><td>Call back</td><td><code>call-back</code></td><td><span class=\"tn-icon bx bx-phone-call\"></span></td><td><code>phone-call</code></td></tr><tr><td>Client request</td><td><code>client-request</code></td><td><span class=\"tn-icon bx bx-clipboard\"></span></td><td><code>clipboard</code></td></tr></tbody></table></figure>",
diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.md b/docs/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.md
index dc6cf3a94c..257846162c 100644
--- a/docs/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.md
+++ b/docs/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.md
@@ -15,6 +15,8 @@ Standard Markdown links are supported.
Trilium internal links (that mirror a note's title and display its icon) are embedded as HTML in order to preserve the information on import.
+<a class="reference-link" href="../../../Note%20Types/Text/Anchors.md">Anchors</a> are kept as HTML as well, so links to an anchor still lead to it after the note is imported again.
+
## Math equations
Both inline and display equations are supported, using the `$` and `$$` syntaxes.
diff --git a/packages/trilium-core/src/services/export/markdown.spec.ts b/packages/trilium-core/src/services/export/markdown.spec.ts
index 75e0dd7bcb..c62da91005 100644
--- a/packages/trilium-core/src/services/export/markdown.spec.ts
+++ b/packages/trilium-core/src/services/export/markdown.spec.ts
@@ -777,6 +777,19 @@ describe("Markdown export", () => {
expect(markdownExportService.toMarkdown(html)).toBe(expected);
});
+ it("keeps bookmarks as HTML anchors, so links to them still resolve after an import", () => {
+ const html = `<h3><a id="schema-note"></a><code>Note</code></h3>`
+ + `<p>See <a href="#schema-note">the note</a>.<a id="end"></a></p>`
+ + `<p><a id="say-&quot;hi&quot;"></a>Quoted</p>`;
+
+ expect(markdownExportService.toMarkdown(html)).toBe(trimIndentation`\
+ ### <a id="schema-note"></a>\`Note\`
+
+ See [the note](#schema-note).<a id="end"></a>
+
+ <a id="say-&quot;hi&quot;"></a>Quoted`);
+ });
+
it("drops the block ids of a text note, which Markdown has no syntax for", () => {
const html = `<h2 data-trilium-block-id="h1">Title</h2>`
+ `<p data-trilium-block-id="p1">Text</p>`;
diff --git a/packages/trilium-core/src/services/export/markdown.ts b/packages/trilium-core/src/services/export/markdown.ts
index c6883d1111..cae4bd9b09 100644
--- a/packages/trilium-core/src/services/export/markdown.ts
+++ b/packages/trilium-core/src/services/export/markdown.ts
@@ -82,7 +82,6 @@ function toMarkdown(content: string, options: ToMarkdownOptions = {}) {
if (isMulticolumnLayout(node) || isMulticolumnColumn(node)) {
return blankMulticolumnReplacement(node);
}
-
// Original implementation as per https://github.com/mixmark-io/turndown/blob/master/src/turndown.js.
return ("isBlock" in node && node.isBlock) ? '\n\n' : '';
},
@@ -96,6 +95,7 @@ function toMarkdown(content: string, options: ToMarkdownOptions = {}) {
instance.addRule("tabPanel", buildTabPanelFilter());
instance.addRule("multicolumn", buildMulticolumnFilter());
instance.addRule("inlineLink", buildInlineLinkFilter());
+ instance.addRule("bookmark", buildBookmarkFilter());
instance.addRule("figure", buildFigureFilter());
instance.addRule("linkPreview", buildLinkPreviewFilter());
instance.addRule("inlineIcon", buildInlineIconFilter());
@@ -305,6 +305,21 @@ function buildInlineLinkFilter(): Rule {
};
}
+/**
+ * Keeps a bookmark, an `<a>` with an `id` and no `href`, as HTML: Markdown has no syntax for it,
+ * and links to `#<id>` find it only by that `id`.
+ */
+function buildBookmarkFilter(): Rule {
+ return {
+ filter(node) {
+ return node.nodeName === "A" && node.hasAttribute("id") && !node.hasAttribute("href");
+ },
+ replacement(content, node) {
+ return `<a id="${escapeHtml((node as HTMLElement).id)}"></a>${content}`;
+ }
+ };
+}
+
function buildFigureFilter(): Rule {
return {
filter(node, options) {