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
feat(markdown): export and import tabs blocks as MkDocs content tabs
Elian Doran04d8b0901538
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.htmlindex b89f7f5e2c..bc203dba3f 100644--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.html+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Import & Export/Markdown/Supported syntax.html@@ -29,6 +29,23 @@> This is a caution.</code></pre><p>There are currently no plans of supporting alternative admonition syntaxessuch 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"++ Run the **installer**.++=== "Linux"++ Use the package.++===! "Another block"++ 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.</p><h2>Wikilinks</h2><p>Basic support for wikilinks has been added in v0.96.0:</p><ul>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.mdindex 5322ddd2b3..dbcb3904f0 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@@ -39,6 +39,26 @@ The Markdown syntax for admonitions as supported by Trilium is the one that GitHThere are currently no plans of supporting alternative admonition syntaxes such as `!!! note`.+## Tabs++Tabs use the syntax of [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/): each tab starts with a `=== "Title"` line, followed by its content indented by four spaces. Consecutive tabs form one tabs block, and `===!` starts a new block right after another one:++```+=== "Windows"++ Run the **installer**.++=== "Linux"++ Use the package.++===! "Another block"++ This tab starts a separate tabs block.+```++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.+## WikilinksBasic support for wikilinks has been added in v0.96.0:diff --git a/packages/commons/src/lib/markdown_renderer.ts b/packages/commons/src/lib/markdown_renderer.tsindex f33878f7af..9ca8ec90e0 100644--- a/packages/commons/src/lib/markdown_renderer.ts+++ b/packages/commons/src/lib/markdown_renderer.ts@@ -84,6 +84,7 @@ import {createCommentExtension,createHighlightExtension,createLiteralTildeExtension,+ createTabsExtensions,createTransclusionExtension,createWikiLinkExtension,transclusionExtension,@@ -617,7 +618,8 @@ export function renderToHtml(content: string, title: string, options: RenderToHtoptions.transclusion ? createTransclusionExtension(options.transclusion) : transclusionExtension,options.wikiLink ? createWikiLinkExtension(options.wikiLink) : wikiLinkExtension,createHighlightExtension(),- createLiteralTildeExtension()+ createLiteralTildeExtension(),+ ...createTabsExtensions()];if (options.obsidian) {extensions.push(createCommentExtension());diff --git a/packages/commons/src/lib/marked_extensions.ts b/packages/commons/src/lib/marked_extensions.tsindex 2cc503ca2e..3904d24618 100644--- a/packages/commons/src/lib/marked_extensions.ts+++ b/packages/commons/src/lib/marked_extensions.ts@@ -229,6 +229,82 @@ export function createLiteralTildeExtension(): TokenizerAndRendererExtension {};}+/**+ * Creates the extensions for the tabbed syntax of Python-Markdown's `pymdownx.tabbed` (used by+ * Material for MkDocs), which the Markdown export writes for a tabs block:+ *+ * ```markdown+ * === "Windows"+ *+ * Content of the tab, indented four spaces.+ *+ * ===! "Other"+ *+ * `===!` starts a new tabs block instead of adding a tab to the previous one.+ * ```+ *+ * Consecutive tabs become one `<div class="trilium-tabs">` in the markup the text editor+ * downcasts. A title is plain text, and an empty panel gets the empty paragraph the editor keeps+ * in every panel.+ */+export function createTabsExtensions(): TokenizerAndRendererExtension[] {+ return [+ {+ name: "tabs",+ level: "block",++ start(src: string) {+ return /^===!? +"/m.exec(src)?.index;+ },++ tokenizer(src) {+ const tabs: Token[] = [];+ let raw = "";+ let rest = src;+ for (;;) {+ const header = TAB_HEADER.exec(rest);+ if (!header || (header[1] && tabs.length)) {+ break;+ }+ const body = TAB_BODY.exec(rest.slice(header[0].length))?.[0] ?? "";+ const content = body.replace(/^(?: {4}|\t)/gm, "");+ tabs.push({+ type: "tab",+ raw: header[0] + body,+ title: header[2],+ tokens: this.lexer.blockTokens(content, [])+ });+ raw += header[0] + body;+ rest = rest.slice(header[0].length + body.length);+ }++ if (tabs.length) {+ return { type: "tabs", raw, tokens: tabs };+ }+ },++ renderer(token) {+ return `<div class="trilium-tabs">${this.parser.parse(token.tokens as Token[])}</div>`;+ }+ },+ {+ name: "tab",+ renderer(token) {+ const title = escapeHtml(token.title as string) || " ";+ const panel = this.parser.parse(token.tokens as Token[]).trim() || "<p> </p>";+ return `<section class="trilium-tab"><p class="trilium-tab-title">${title}</p>` ++ `<div class="trilium-tab-panel">${panel}</div></section>`;+ }+ }+ ];+}++/** `=== "Title"`, or `===! "Title"` to start a new block; the title runs to the last quote. */+const TAB_HEADER = /^===(!)? +"(.*)" *(?:\n|$)/;++/** The lines of a tab's panel: blank, or indented by four spaces or a tab. */+const TAB_BODY = /^(?:[ \t]*\n|(?: {4}|\t).*(?:\n|$))*/;+/** Pre-configured wiki-link extension for server-side (uses /noteId format) */export const wikiLinkExtension = createWikiLinkExtension();diff --git a/packages/trilium-core/src/services/export/markdown.spec.ts b/packages/trilium-core/src/services/export/markdown.spec.tsindex 5cecf334ff..61b3c28d27 100644--- a/packages/trilium-core/src/services/export/markdown.spec.ts+++ b/packages/trilium-core/src/services/export/markdown.spec.ts@@ -962,4 +962,43 @@ describe("Markdown export", () => {});});+ describe("tabs blocks", () => {+ const tab = (title: string, panel: string) =>+ `<section class="trilium-tab"><p class="trilium-tab-title">${title}</p><div class="trilium-tab-panel">${panel}</div></section>`;+ const tabs = (...items: string[]) => `<div class="trilium-tabs">${items.join("")}</div>`;++ it("exports each tab as a MkDocs tabbed section with its panel indented four spaces", () => {+ const html = tabs(+ tab("Windows", "<p>Run the <strong>installer</strong>.</p><pre><code class=\"language-text-x-sh\">setup.exe</code></pre>"),+ tab("Say \"hi\"", "<ul><li>One</li><li>Two</li></ul>")+ );+ expect(markdownExportService.toMarkdown(html)).toBe(trimIndentation`\+ === "Windows"++ Run the **installer**.++ \`\`\`sh+ setup.exe+ \`\`\`++ === "Say "hi""++ * One+ * Two`);+ });++ it("indents nested tabs once more and starts a block that follows another one with ===!", () => {+ const html = tabs(tab("Outer", tabs(tab("Inner", "<p>x</p>")))) + tabs(tab("Next", "<p>y</p>"));+ expect(markdownExportService.toMarkdown(html)).toBe(trimIndentation`\+ === "Outer"++ === "Inner"++ x++ ===! "Next"++ y`);+ });+ });});diff --git a/packages/trilium-core/src/services/export/markdown.ts b/packages/trilium-core/src/services/export/markdown.tsindex df10f50590..c5801a4f3e 100644--- a/packages/trilium-core/src/services/export/markdown.ts+++ b/packages/trilium-core/src/services/export/markdown.ts@@ -71,6 +71,12 @@ function toMarkdown(content: string, options: ToMarkdownOptions = {}) {return linkPreviewReplacement(node);}+ // A tab without text still keeps its `=== ""` line, or the import loses the tab.+ const blankTabs = blankTabsReplacement(node);+ if (blankTabs !== null) {+ return blankTabs;+ }+// Original implementation as per https://github.com/mixmark-io/turndown/blob/master/src/turndown.js.return ("isBlock" in node && node.isBlock) ? '\n\n' : '';},@@ -80,6 +86,8 @@ function toMarkdown(content: string, options: ToMarkdownOptions = {}) {instance.addRule("img", buildImageFilter());instance.addRule("admonition", buildAdmonitionFilter());instance.addRule("details", buildDetailsFilter());+ instance.addRule("tabTitle", buildTabTitleFilter());+ instance.addRule("tabPanel", buildTabPanelFilter());instance.addRule("inlineLink", buildInlineLinkFilter());instance.addRule("figure", buildFigureFilter());instance.addRule("linkPreview", buildLinkPreviewFilter());@@ -418,6 +426,76 @@ function buildDetailsFilter(): Rule {};}+/**+ * Tabs blocks export to the tabbed syntax of Python-Markdown's `pymdownx.tabbed` (used by Material+ * for MkDocs): a `=== "Title"` line per tab, followed by the panel indented four spaces. A block+ * that directly follows another one starts with `===! "Title"`, which keeps the two apart. The+ * shared Markdown renderer reads the same syntax back.+ */+function buildTabTitleFilter(): Rule {+ return {+ filter(node) {+ return node.classList.contains(TAB_TITLE_CLASS);+ },+ replacement(_content, node) {+ return `\n\n${tabTitleLine(node)}\n\n`;+ }+ };+}++function buildTabPanelFilter(): Rule {+ return {+ filter(node) {+ return node.classList.contains(TAB_PANEL_CLASS);+ },+ replacement(content) {+ const indented = content+ .trim()+ .split("\n")+ .map((line) => (line ? ` ${line}` : line))+ .join("\n");+ return `\n\n${indented}\n\n`;+ }+ };+}++/** The title lines of a tabs block, tab or title that holds no text; `null` for any other node. */+function blankTabsReplacement(node: Node): string | null {+ if (!isElement(node)) {+ return null;+ }+ const childrenWithClass = (parent: Element, className: string) =>+ Array.from(parent.children).filter((child) => child.classList.contains(className));++ const titles = node.classList.contains(TABS_CLASS)+ ? childrenWithClass(node, TAB_CLASS).flatMap((tab) => childrenWithClass(tab, TAB_TITLE_CLASS))+ : node.classList.contains(TAB_CLASS)+ ? childrenWithClass(node, TAB_TITLE_CLASS)+ : node.classList.contains(TAB_TITLE_CLASS) ? [node] : null;+ if (!titles) {+ return null;+ }+ return `\n\n${titles.map(tabTitleLine).join("\n\n")}\n\n`;+}++function tabTitleLine(title: Element): string {+ const tab = title.parentElement;+ const block = tab?.parentElement;+ const startsNewBlock = block?.firstElementChild === tab+ && block?.previousElementSibling?.classList.contains(TABS_CLASS);+ const text = (title.textContent ?? "").replace(/\s+/g, " ").trim();+ return `===${startsNewBlock ? "!" : ""} "${text}"`;+}++function isElement(node: Node): node is Element {+ return node.nodeType === 1;+}++const TABS_CLASS = "trilium-tabs";+const TAB_CLASS = "trilium-tab";+const TAB_TITLE_CLASS = "trilium-tab-title";+const TAB_PANEL_CLASS = "trilium-tab-panel";+// Keep in line with https://github.com/mixmark-io/turndown/blob/master/src/commonmark-rules.js.function buildListItemFilter(): Rule {return {diff --git a/packages/trilium-core/src/services/import/markdown.spec.ts b/packages/trilium-core/src/services/import/markdown.spec.tsindex 71d05cfd2e..a1af795022 100644--- a/packages/trilium-core/src/services/import/markdown.spec.ts+++ b/packages/trilium-core/src/services/import/markdown.spec.ts@@ -665,4 +665,47 @@ $$`;}});});++ describe("tabs blocks", () => {+ const tab = (title: string, panel: string) =>+ `<section class="trilium-tab"><p class="trilium-tab-title">${title}</p><div class="trilium-tab-panel">${panel}</div></section>`;+ const tabs = (...items: string[]) => `<div class="trilium-tabs">${items.join("")}</div>`;++ it("renders MkDocs tabbed sections as a tabs block, starting a new block at ===!", () => {+ const input = trimIndentation`\+ === "Windows"++ Run the **installer**.++ === "<b>Linux</b>"+ - One+ - Two++ ===! "Other"++ x++ After.`;+ expect(markdownService.renderToHtml(input, "Title")).toStrictEqual(+ tabs(+ tab("Windows", "<p>Run the <strong>installer</strong>.</p>"),+ tab("<b>Linux</b>", "<ul><li>One</li><li>Two</li></ul>")+ ) ++ tabs(tab("Other", "<p>x</p>")) ++ "<p>After.</p>"+ );+ });++ it("round-trips tabs blocks through the Markdown exporter", () => {+ const original =+ tabs(+ tab("Windows", "<p>Run the <strong>installer</strong>.</p><ul><li>One</li><li>Two</li></ul>"),+ tab(" ", "<p> </p>"),+ tab("Nested", tabs(tab("A", "<p>a</p>"), tab("B", "<blockquote><p>b</p></blockquote>")))+ ) ++ tabs(tab("Next", "<p>y</p>"));+ expect(markdownService.renderToHtml(markdownExportService.toMarkdown(original), "Title"))+ .toStrictEqual(original);+ });+ });});