feat(guide): add outline for pages (#8722)

Co-authored-by: iCrawl <buechler.noel@outlook.com>

packages/guide/src/components/Outline.tsx

@@ -0,0 +1,72 @@
+import type { MarkdownHeading } from 'astro';
+import { useEffect, useMemo, useState } from 'react';
+import { Scrollbars } from 'react-custom-scrollbars-2';
+import { VscListSelection } from 'react-icons/vsc';
+import { useLocation } from 'react-use';
+
+const LINK_HEIGHT = 30;
+const INDICATOR_SIZE = 10;
+const INDICATOR_OFFSET = (LINK_HEIGHT - INDICATOR_SIZE) / 2;
+
+export function Outline({ headings }: { headings: MarkdownHeading[] }) {
+	const state = useLocation();
+	const [active, setActive] = useState(0);
+
+	const headingItems = useMemo(
+		() =>
+			headings.map((heading, idx) => (
+				<a
+					className={`dark:border-dark-100 border-light-800 pl-6.5 focus:ring-width-2 focus:ring-blurple ml-[10px] border-l p-[5px] text-sm outline-0 focus:rounded focus:border-0 focus:ring ${
+						idx === active
+							? 'bg-blurple text-white'
+							: 'dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800'
+					}`}
+					href={`#${heading.slug}`}
+					key={heading.slug}
+					style={{ paddingLeft: `${heading.depth * 14}px` }}
+					title={heading.text}
+				>
+					<span className="line-clamp-1">{heading.text}</span>
+				</a>
+			)),
+		[headings, active],
+	);
+
+	useEffect(() => {
+		const idx = headings.findIndex((heading) => heading.slug === state.hash?.slice(1));
+		if (idx >= 0) {
+			setActive(idx);
+		}
+	}, [state, headings]);
+
+	return (
+		<Scrollbars
+			autoHide
+			hideTracksWhenNotNeeded
+			renderThumbVertical={(props) => <div {...props} className="dark:bg-dark-100 bg-light-900 z-30 rounded" />}
+			renderTrackVertical={(props) => (
+				<div {...props} className="absolute top-0.5 right-0.5 bottom-0.5 z-30 w-1.5 rounded" />
+			)}
+			universal
+		>
+			<div className="flex flex-col break-all p-3 pb-8">
+				<div className="mt-4 ml-2 flex flex-row gap-2">
+					<VscListSelection size={25} />
+					<span className="font-semibold">Contents</span>
+				</div>
+				<div className="mt-4 ml-2 flex flex-col gap-2">
+					<div className="relative flex flex-col">
+						<div
+							className="bg-blurple absolute h-[10px] w-[10px] rounded-full border-2 border-black dark:border-white"
+							style={{
+								left: INDICATOR_SIZE / 2 + 0.5,
+								transform: `translateY(${active * LINK_HEIGHT + INDICATOR_OFFSET}px)`,
+							}}
+						/>
+						{headingItems}
+					</div>
+				</div>
+			</div>
+		</Scrollbars>
+	);
+}

packages/guide/src/components/SidebarItems.tsx

@@ -1,29 +1,43 @@
 import { Section } from '@discordjs/ui';
 import type { MDXInstance } from 'astro';
+import { useEffect, useMemo, useState } from 'react';
+import { useLocation } from 'react-use';
 
 export type MDXPage = MDXInstance<{ category: string; title: string }>;
 
 export function SidebarItems({ pages }: { pages: MDXPage[] }) {
-	const categories = pages.reduce<Record<string, MDXPage[]>>((acc, page) => {
-		if (acc[page.frontmatter.category]) {
-			acc[page.frontmatter.category]?.push(page);
-		} else {
-			acc[page.frontmatter.category] = [page];
-		}
+	const state = useLocation();
+	const [active, setActive] = useState<string | undefined>('');
 
-		return acc;
-	}, {});
+	const categories = useMemo(
+		() =>
+			pages.reduce<Record<string, MDXPage[]>>((acc, page) => {
+				if (acc[page.frontmatter.category]) {
+					acc[page.frontmatter.category]?.push(page);
+				} else {
+					acc[page.frontmatter.category] = [page];
+				}
+
+				return acc;
+			}, {}),
+		[pages],
+	);
+
+	useEffect(() => {
+		setActive(state.pathname);
+	}, [state]);
 
 	return Object.keys(categories).map((category, idx) => (
 		<Section key={idx} title={category}>
 			{categories[category]?.map((member, index) => (
 				<a
 					className={`dark:border-dark-100 border-light-800 focus:ring-width-2 focus:ring-blurple ml-5 flex flex-col border-l p-[5px] pl-6 outline-0 focus:rounded focus:border-0 focus:ring ${
-						false
+						(member.url || '/') === active
 							? 'bg-blurple text-white'
 							: 'dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800'
 					}`}
-					href={member.url}
+					// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+					href={member.url || '/'}
 					key={index}
 					title={member.frontmatter.title}
 				>

packages/guide/src/components/SidebarLayout.astro

@@ -1,8 +1,13 @@
 ---
+import type { MarkdownLayoutProps } from 'astro';
 import { Navbar } from './Navbar.jsx';
+import { Outline } from './Outline.jsx';
 import { SidebarItems } from './SidebarItems.jsx';
 
 const pages = await Astro.glob<{ category: string; title: string }>('../pages/**/*.mdx');
+
+type Props = MarkdownLayoutProps<{}>;
+const { headings } = Astro.props;
 ---
 
 <Navbar client:load>
@@ -10,15 +15,23 @@ const pages = await Astro.glob<{ category: string; title: string }>('../pages/**
 		<SidebarItems client:load pages={pages} />
 	</div>
 </Navbar>
-<main class="pt-18 lg:pl-76">
+<main class="pt-18 lg:pl-76 xl:pr-64">
 	<article class="dark:bg-dark-600 bg-light-600">
 		<div class="dark:bg-dark-800 relative z-10 min-h-[calc(100vh_-_70px)] bg-white p-6 pb-20 shadow">
-			<div class="prose max-w-none">
+			<div class="prose max-w-full">
 				<slot />
 			</div>
+			<div
+				class="h-[calc(100vh - 72px)] dark:bg-dark-600 dark:border-dark-100 border-light-800 fixed top-[72px] right-0 bottom-0 z-20 hidden w-64 border-l bg-white pr-2 xl:block"
+			>
+				<Outline client:load headings={headings} />
+			</div>
 		</div>
+
 		<div class="h-76 md:h-52"></div>
-		<footer class="dark:bg-dark-600 h-76 lg:pl-84 bg-light-600 fixed bottom-0 left-0 right-0 md:h-52 md:pl-4 md:pr-16">
+		<footer
+			class="dark:bg-dark-600 h-76 lg:pl-84 bg-light-600 fixed bottom-0 left-0 right-0 md:h-52 md:pl-4 md:pr-16 xl:pr-76"
+		>
 			<div class="mx-auto flex max-w-6xl flex-col place-items-center gap-12 pt-12 lg:place-content-center">
 				<div class="flex w-full flex-col place-content-between place-items-center gap-12 md:flex-row md:gap-0">
 					<a
@@ -86,4 +99,5 @@ const pages = await Astro.glob<{ category: string; title: string }>('../pages/**
 			</div>
 		</footer>
 	</article>
+	<div>Test</div>
 </main>

packages/guide/src/layouts/SidebarLayout.astro

@@ -1,8 +1,12 @@
 ---
 import '@code-hike/mdx/styles.css';
 import '../styles/ch.css';
+import type { MarkdownLayoutProps } from 'astro';
 import SidebarLayout from '../components/SidebarLayout.astro';
 import { DESCRIPTION } from '../util/constants.js';
+
+type Props = MarkdownLayoutProps<{}>;
+const props = Astro.props;
 ---
 
 <html lang="en">
@@ -51,7 +55,7 @@ import { DESCRIPTION } from '../util/constants.js';
 						.addEventListener('change', (ev) => setTheme(ev.matches, persistedColorPreference));
 			})();
 		</script>
-		<SidebarLayout>
+		<SidebarLayout {...props}>
 			<slot />
 		</SidebarLayout>
 	</body>

packages/ui/unocss.config.ts

@@ -49,11 +49,16 @@ export default defineConfig({
 				'a > img': {
 					display: 'inline-block',
 				},
+				h1: {
+					'scroll-margin-top': '6.5rem',
+				},
 				h2: {
 					'margin-top': '1.25em',
+					'scroll-margin-top': '6.5rem',
 				},
 				h3: {
-					'margin-top': '0.75em',
+					'margin-top': '1.25em',
+					'scroll-margin-top': '6.5rem',
 				},
 				// eslint-disable-next-line id-length
 				p: {