feat: Markdown renderer

packages/site-kit/package.json

@@ -20,22 +20,29 @@
 	"homepage": "https://github.com/sveltejs/site-kit#readme",
 	"dependencies": {
 		"esm-env": "^1.0.0",
-		"svelte-local-storage-store": "^0.4.0"
+		"svelte-local-storage-store": "^0.5.0"
 	},
 	"devDependencies": {
-		"@sveltejs/kit": "^1.15.5",
+		"@sveltejs/kit": "^1.20.4",
 		"@sveltejs/package": "^2.0.2",
+		"@types/marked": "^5.0.0",
+		"@types/node": "^20.3.1",
+		"@types/prettier": "^2.7.3",
 		"flexsearch": "^0.7.31",
-		"svelte": "^3.58.0",
-		"typescript": "^5.0.4",
-		"vite": "^4.2.1"
+		"magic-string": "^0.30.0",
+		"marked": "^5.1.0",
+		"prettier": "^2.8.8",
+		"shiki-twoslash": "^3.1.2",
+		"svelte": "^3.59.1",
+		"typescript": "^5.1.3",
+		"vite": "^4.3.9"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"peerDependencies": {
 		"@sveltejs/kit": "^1.0.0",
-		"svelte": "^3.54.0 || ^4.0.0-next.0 || ^4.0.0"
+		"svelte": "^3.54.0 || ^4.0.0-next.1 || ^4.0.0"
 	},
 	"types": "./dist/types.d.ts",
 	"exports": {
@@ -61,6 +68,11 @@
 			"default": "./dist/docs/index.js",
 			"svelte": "./dist/docs/index.js"
 		},
+		"./markdown": {
+			"types": "./dist/markdown/index.d.ts",
+			"default": "./dist/markdown/index.js",
+			"svelte": "./dist/markdown/index.js"
+		},
 		"./nav": {
 			"types": "./dist/nav/index.d.ts",
 			"default": "./dist/nav/index.js",
@@ -83,4 +95,4 @@
 	"files": [
 		"dist"
 	]
-}
+}

packages/site-kit/src/lib/docs/DocsContents.svelte

@@ -147,6 +147,10 @@
 			color: var(--sk-theme-1) !important;
 			font-weight: 400;
 		}
+
+		.ts-toggle {
+			display: none;
+		}
 	}
 
 	@media (min-width: 832px) {

packages/site-kit/src/lib/docs/DocsOnThisPage.svelte

@@ -49,7 +49,7 @@
 		content = contentEl;
 
 		const { top } = content.getBoundingClientRect();
-		headings = content.querySelectorAll('h2[id]');
+		headings = content.querySelectorAll('h2[id], h3[id]');
 		positions = Array.from(headings).map((heading) => {
 			const style = getComputedStyle(heading);
 			return heading.getBoundingClientRect().top - parseFloat(style.scrollMarginTop) - top;

packages/site-kit/src/lib/docs/Tooltip.svelte

@@ -0,0 +1,71 @@
+<script>
+	import { tick } from 'svelte';
+
+	export let html = '';
+	export let x = 0;
+	export let y = 0;
+
+	let width = 1;
+
+	/** @type {HTMLDivElement}*/
+	let tooltip;
+
+	// bit of a gross hack but it works — this prevents the
+	// tooltip from disappearing off the side of the screen
+	$: if (html && tooltip) {
+		tick().then(() => {
+			width = tooltip.getBoundingClientRect().width;
+		});
+	}
+</script>
+
+<div
+	on:mouseenter
+	on:mouseleave
+	role="tooltip"
+	class="tooltip-container"
+	style:left="{x}px"
+	style:top="{y}px"
+	style:--offset="{Math.min(-10, window.innerWidth - (x + width + 10))}px"
+>
+	<div bind:this={tooltip} class="tooltip">
+		<span>{@html html}</span>
+	</div>
+</div>
+
+<style>
+	.tooltip-container {
+		--bg: var(--sk-theme-2);
+		--arrow-size: 0.4rem;
+		position: absolute;
+		transform: translate(var(--offset), calc(2rem + var(--arrow-size)));
+	}
+
+	.tooltip {
+		margin: 0 2rem 0 0;
+		background-color: var(--bg);
+		color: #fff;
+		text-align: left;
+		padding: 0.4rem 0.6rem;
+		border-radius: var(--sk-border-radius);
+		font-family: var(--sk-font-mono);
+		font-size: 1.2rem;
+		white-space: pre-wrap;
+		z-index: 100;
+		filter: drop-shadow(2px 4px 6px #67677866);
+	}
+
+	.tooltip::after {
+		content: '';
+		position: absolute;
+		left: calc(-1 * var(--offset) - var(--arrow-size));
+		top: calc(-2 * var(--arrow-size));
+		border: var(--arrow-size) solid transparent;
+		border-bottom-color: var(--bg);
+	}
+
+	.tooltip :global(a) {
+		color: white;
+		text-decoration: underline;
+	}
+</style>

packages/site-kit/src/lib/docs/hover.js

@@ -0,0 +1,70 @@
+import { onMount } from 'svelte';
+import Tooltip from './Tooltip.svelte';
+
+export function setupDocsHovers() {
+	onMount(() => {
+		/** @type {Tooltip | null} */
+		let tooltip;
+
+		/** @type {NodeJS.Timeout} */
+		let timeout;
+
+		/** @param {MouseEvent} event */
+		function over(event) {
+			const target = /** @type {HTMLElement} */ (event.target);
+
+			if (target.tagName === 'DATA-LSP') {
+				clearTimeout(timeout);
+
+				if (!tooltip) {
+					tooltip = new Tooltip({
+						target: document.body
+					});
+
+					tooltip.$on('mouseenter', () => {
+						clearTimeout(timeout);
+					});
+
+					tooltip.$on('mouseleave', () => {
+						clearTimeout(timeout);
+						tooltip?.$destroy();
+						tooltip = null;
+					});
+				}
+
+				const rect = target?.getBoundingClientRect();
+				const html = target?.getAttribute('lsp');
+
+				const x = (rect.left + rect.right) / 2 + window.scrollX;
+				const y = rect.top + window.scrollY;
+
+				if (html) {
+					tooltip.$set({
+						html,
+						x,
+						y
+					});
+				}
+			}
+		}
+
+		/** @param {MouseEvent} event */
+		function out(event) {
+			const target = /** @type {HTMLElement} */ (event.target);
+			if (target.tagName === 'DATA-LSP') {
+				timeout = setTimeout(() => {
+					tooltip?.$destroy();
+					tooltip = null;
+				}, 200);
+			}
+		}
+
+		window.addEventListener('mouseover', over);
+		window.addEventListener('mouseout', out);
+
+		return () => {
+			window.removeEventListener('mouseover', over);
+			window.removeEventListener('mouseout', out);
+		};
+	});
+}

packages/site-kit/src/lib/docs/index.js

@@ -1,4 +1,4 @@
 export { default as DocsContents } from './DocsContents.svelte';
 export { default as DocsOnThisPage } from './DocsOnThisPage.svelte';
 export { default as TSToggle } from './TSToggle.svelte';
-export { default as DocsMobileNav } from './DocsMobileNav.svelte';
+export { setupDocsHovers } from './hover.js';

packages/site-kit/src/lib/markdown/index.js

@@ -0,0 +1,34 @@
+export {
+	render_content_markdown as renderContentMarkdown,
+	replace_export_type_placeholders as replaceExportTypePlaceholders
+} from './renderer';
+
+export {
+	extract_frontmatter as extractFrontmatter,
+	transform as markedTransform,
+	normalizeSlugify,
+	slugify,
+	removeMarkdown,
+	escape
+} from './utils';
+
+/**
+ * @typedef {{
+ *   name?: string;
+ *   comment?: string;
+ *   exempt?: boolean;
+ *   types?: ModuleChild[];
+ *   exports?: ModuleChild[];
+ * }[]} Modules
+ */
+
+/**
+ * @typedef {{
+ *   name: string;
+ *   snippet: string;
+ *   comment: string;
+ *   deprecated?: string;
+ *   bullets?: string[];
+ *   children?: ModuleChild[];
+ * }} ModuleChild
+ */