Skip to content

Build your personal knowledge base with Trilium Notes

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.html
index 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 @@
&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"
+
+ 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.md
index 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 GitH
There 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.
+
## Wikilinks
Basic 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.ts
index 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: RenderToHt
options.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.ts
index 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) || "&nbsp;";
+ const panel = this.parser.parse(token.tokens as Token[]).trim() || "<p>&nbsp;</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.ts
index 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.ts
index 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.ts
index 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("&lt;b&gt;Linux&lt;/b&gt;", "<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("&nbsp;", "<p>&nbsp;</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);
+ });
+ });
});