[Docs Site] Use Tippy.js for footnotes (#17357)

* [Docs Site] Use Tippy.js for footnotes

* tabindex/hover cutoff fixes

* update style guide link to lib

* new fnref styling

Author: KianNH

astro.config.ts

@@ -169,6 +169,7 @@ export default defineConfig({
 				"./src/mermaid.css",
 				"./src/table.css",
 				"./src/tailwind.css",
+				"./src/tooltips.css",
 			],
 			pagination: false,
 			plugins: runLinkCheck

package-lock.json

@@ -50,7 +50,6 @@
 		"he": "^1.2.0",
 		"instantsearch.css": "^8.5.0",
 		"instantsearch.js": "^4.74.0",
-		"littlefoot": "^4.1.1",
 		"lz-string": "^1.5.0",
 		"marked": "^14.1.1",
 		"mermaid": "^11.3.0",

package.json

@@ -1,7 +1,6 @@
 ---
 import { z } from "astro:schema";
 import { getGlossaryEntry } from "~/util/glossary";
-import "tippy.js/dist/tippy.css";
 import { marked } from "marked";
 
 type Props = z.infer<typeof props>;
@@ -31,31 +30,19 @@ definition = definition.split(/\r?\n/)[0];
 	data-tooltip
 	data-content={marked.parse(definition)}
 	class="border-b-2 border-dashed border-accent-600"
+	tabindex="0"
 	>{
 		link ? (
 			<a href={link}><slot /></a>
 		) : (
 			<slot />
 		)
 	}</span><script>
-	import tippy from "tippy.js";
+	import { addTooltip } from "~/util/tippy";
 
 	const tooltips = document.querySelectorAll<HTMLSpanElement>("[data-tooltip]");
 
 	for (const tooltip of tooltips) {
-		tippy(`#${CSS.escape(tooltip.id)}`, {
-			content: tooltip.dataset.content,
-			allowHTML: true,
-			interactive: true,
-			placement: "auto",
-			arrow: false,
-		});
+		addTooltip(tooltip, tooltip.dataset.content as string);
 	}
-</script><style is:global>
-	.tippy-box {
-		background-color: var(--sl-color-bg-nav);
-		border-color: var(--sl-color-text);
-		border: 0.1em solid;
-		color: var(--sl-color-white);
-	}
-</style>
+</script>

src/components/GlossaryTooltip.astro

@@ -2,7 +2,7 @@
 import type { Props } from "@astrojs/starlight/props";
 import Default from "@astrojs/starlight/components/Head.astro";
 import { differenceInCalendarDays } from "date-fns";
-import "littlefoot/dist/littlefoot.css";
+import "tippy.js/dist/tippy.css";
 
 import { getEntry } from "astro:content";
 import { getPageDescription } from "~/util/description";
@@ -164,51 +164,7 @@ if (Astro.props.entry.data.external_link) {
 }
 ---
 
-<script>
-	import littlefoot from "littlefoot";
-
-	littlefoot();
-	document
-		.querySelectorAll("span.littlefoot")
-		.forEach((x) => x.classList.add("not-content"));
-</script>
-<script>
-	import mermaid from "mermaid";
-
-	const diagrams = document.querySelectorAll<HTMLPreElement>("pre.mermaid");
-
-	let init = false;
-
-	async function render() {
-		const theme =
-			document.documentElement.getAttribute("data-theme") === "light"
-				? "neutral"
-				: "dark";
-
-		for (const diagram of diagrams) {
-			if (!init) {
-				diagram.setAttribute("data-diagram", diagram.textContent as string);
-			}
-
-			const def = diagram.getAttribute("data-diagram") as string;
-
-			mermaid.initialize({ startOnLoad: false, theme });
-			await mermaid
-				.render(`mermaid-${crypto.randomUUID()}`, def)
-				.then(({ svg }) => (diagram.innerHTML = svg));
-
-			diagram.setAttribute("data-processed", "true");
-		}
-
-		init = true;
-	}
-
-	const obs = new MutationObserver(() => render());
-
-	obs.observe(document.documentElement, {
-		attributes: true,
-		attributeFilter: ["data-theme"],
-	});
-</script>
+<script src="src/scripts/footnotes.ts"></script>
+<script src="src/scripts/mermaid.ts"></script>
 <script src="src/scripts/analytics.ts"></script>
 <Default {...Astro.props}><slot /></Default>

src/components/overrides/Head.astro

@@ -47,6 +47,8 @@ if (Astro.props.toc) {
 			];
 
 			for (const header of headers) {
+				if (header.id === "footnote-label") continue;
+
 				const depth = headerDepth(header);
 
 				const title = he.decode(header.innerText);

src/components/overrides/PageSidebar.astro

@@ -7,7 +7,7 @@ To create footnotes, use the following syntax:
 ```mdx live
 You can use GitHub Flavoured Markdown footnotes![^1]
 
-[^1]: Powered by [littlefoot.js](https://littlefoot.js.org)
+[^1]: Powered by [tippy.js](https://atomiks.github.io/tippyjs/)
 ```
 
 Refer to [Footnotes](/style-guide/formatting/footnotes/) to learn when to use them.

src/content/docs/style-guide/components/footnotes.mdx

@@ -0,0 +1,26 @@
+import { addTooltip } from "~/util/tippy";
+
+const footnotes = document.querySelector("section.footnotes");
+
+if (footnotes) {
+	const notes = footnotes.querySelectorAll("li");
+
+	for (const note of notes) {
+		const content = note.querySelector("p") as HTMLParagraphElement;
+
+		const fnrefs = document.querySelectorAll<HTMLAnchorElement>(
+			`#${note.id.replace("fn", "fnref")}`,
+		);
+
+		for (const fnref of fnrefs) {
+			addTooltip(fnref, content.innerHTML);
+
+			fnref.classList.add("footnote");
+
+			fnref.setAttribute("tabindex", "0");
+			fnref.removeAttribute("href");
+		}
+	}
+
+	footnotes.remove();
+}

src/scripts/footnotes.ts

@@ -0,0 +1,36 @@
+import mermaid from "mermaid";
+
+const diagrams = document.querySelectorAll<HTMLPreElement>("pre.mermaid");
+
+let init = false;
+
+async function render() {
+	const theme =
+		document.documentElement.getAttribute("data-theme") === "light"
+			? "neutral"
+			: "dark";
+
+	for (const diagram of diagrams) {
+		if (!init) {
+			diagram.setAttribute("data-diagram", diagram.textContent as string);
+		}
+
+		const def = diagram.getAttribute("data-diagram") as string;
+
+		mermaid.initialize({ startOnLoad: false, theme });
+		await mermaid
+			.render(`mermaid-${crypto.randomUUID()}`, def)
+			.then(({ svg }) => (diagram.innerHTML = svg));
+
+		diagram.setAttribute("data-processed", "true");
+	}
+
+	init = true;
+}
+
+const obs = new MutationObserver(() => render());
+
+obs.observe(document.documentElement, {
+	attributes: true,
+	attributeFilter: ["data-theme"],
+});

src/scripts/mermaid.ts

@@ -0,0 +1,12 @@
+@tailwind utilities;
+
+.footnote {
+	@apply text-xs !text-[--sl-color-accent] font-semibold p-1 -m-1;
+}
+
+.tippy-box {
+    background-color: var(--sl-color-bg-nav);
+    border-color: var(--sl-color-text);
+    border: 0.1em solid;
+    color: var(--sl-color-white);
+}