docs: more cleanup following restructure (#2702)

- add TOC for Reference section
- make external links use _blank to open a new tab
- fix some more /gen links spots I missed, oops
- add a general redirect from old /gen links → /reference
- some more stylistic touchups

### Change Type

- [x] `documentation` — Changes to the documentation only[^2]

### Release Notes

- Docs: further cleanup following restructure.

apps/docs/components/Sidebar.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import {
+	APIGroup,
 	ArticleHeadings,
 	SidebarContentArticleLink,
 	SidebarContentCategoryLink,
@@ -43,7 +44,7 @@ export function Sidebar({
 	useEffect(() => {
 		document.body.classList.remove('sidebar-open')
 
-		document.querySelector('.sidebar [data-active=true]')?.scrollIntoView({ block: 'center' })
+		document.querySelector('.sidebar__nav [data-active=true]')?.scrollIntoView({ block: 'center' })
 
 		// XXX(mime): scrolling the sidebar into position also scrolls the page to the wrong
 		// spot. this compensates for that but, ugh.
@@ -94,7 +95,7 @@ function SidebarLink({ headings, ...props }: SidebarContentLink & { headings?: A
 			return <SidebarArticle headings={headings} {...props} />
 		}
 		case 'category': {
-			return <SidebarCategory {...props} />
+			return <SidebarCategory headings={headings} {...props} />
 		}
 	}
 }
@@ -118,7 +119,11 @@ function SidebarSection({
 	)
 }
 
-function SidebarCategory({ title, children }: SidebarContentCategoryLink) {
+function SidebarCategory({
+	title,
+	children,
+	headings,
+}: SidebarContentCategoryLink & { headings?: ArticleHeadings }) {
 	const linkCtx = useContext(linkContext)
 	if (children.length === 0) return null
 	const hasGroups = children.some((child) => !!(child as SidebarContentArticleLink).groupId)
@@ -126,7 +131,7 @@ function SidebarCategory({ title, children }: SidebarContentCategoryLink) {
 		(child) => (child as SidebarContentArticleLink).articleId === linkCtx?.articleId
 	)
 	const activeGroup = activeArticle && (activeArticle as SidebarContentArticleLink).groupId
-	const groups = ['Class', 'Function', 'Variable', 'Interface', 'Enum', 'TypeAlias', 'Namespace']
+	const groups = Object.values(APIGroup)
 
 	return (
 		<li className="sidebar__category">
@@ -156,9 +161,9 @@ function SidebarCategory({ title, children }: SidebarContentCategoryLink) {
 										<Chevron />
 									</Accordion.Trigger>
 									<Accordion.Content>
-										<ul className="sidebar__list" style={{ paddingLeft: '8px' }}>
+										<ul className="sidebar__list sidebar__group" style={{ paddingLeft: '8px' }}>
 											{articles.map((link) => (
-												<SidebarLink key={link.url} {...link} />
+												<SidebarLink key={link.url} headings={headings} {...link} />
 											))}
 										</ul>
 									</Accordion.Content>
@@ -190,7 +195,8 @@ function SidebarArticle({
 	articleId,
 	headings,
 }: SidebarContentArticleLink & { headings?: ArticleHeadings }) {
-	const isActive = useContext(linkContext)?.activeId === articleId
+	const activeLink = useContext(linkContext)
+	const isActive = activeLink?.activeId === articleId
 
 	return (
 		<li className="sidebar__article">
@@ -201,9 +207,12 @@ function SidebarArticle({
 			{isActive && (
 				<ul className="sidebar__list">
 					{headings
-						?.filter((heading) => heading.level < 3)
+						?.filter((heading) => heading.level < 4)
 						.map((heading) => (
-							<li key={heading.slug}>
+							<li
+								key={heading.slug}
+								data-heading-level={heading.title === 'Constructor' ? 2 : heading.level}
+							>
 								<Link href={`#${heading.slug}`} className="sidebar__link">
 									{heading.isCode ? (
 										<code>{heading.title.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')}</code>

apps/docs/components/mdx-components/generic.tsx

@@ -62,7 +62,21 @@ export const Paragraph = (props: any) => {
 }
 
 export const A = (props: any) => {
-	return <a {...props} />
+	const isLocalUrl = props.href.startsWith('/') || props.href.startsWith('#')
+	let maybeParsedUrl
+	try {
+		maybeParsedUrl = isLocalUrl ? null : new URL(props.href)
+	} catch (e) {
+		console.error(`Invalid URL: ${props.href}`)
+	}
+	const derivedTarget =
+		isLocalUrl ||
+		maybeParsedUrl?.host.includes('tldraw.com') ||
+		maybeParsedUrl?.host.includes('localhost')
+			? undefined
+			: '_blank'
+	const target = props.target ?? derivedTarget
+	return <a {...props} target={target} />
 }
 
 export const Divider = (props: any) => {