[docs] Fix links, little style tweaks (#2724)

This PR is a small but mighty improvement to our docs.

### Change Type

- [ ] `patch` — Bug fix
- [ ] `minor` — New feature
- [ ] `major` — Breaking change
- [ ] `dependencies` — Changes to package dependencies[^1]
- [x] `documentation` — Changes to the documentation only[^2]
- [ ] `tests` — Changes to any test code only[^2]
- [ ] `internal` — Any other changes that don't affect the published
package[^2]
- [ ] I don't know

[^1]: publishes a `patch` release, for devDependencies use `internal`
[^2]: will not publish a new version

---------

Co-authored-by: Mime Čuvalo <mimecuvalo@gmail.com>

apps/docs/app/[...id]/page.tsx

@@ -1,5 +1,6 @@
 import { ArticleDocsPage } from '@/components/ArticleDocsPage'
 import { CategoryDocsPage } from '@/components/CategoryDocsPage'
+import { ExampleDocsPage } from '@/components/ExampleDocsPage'
 import { SectionDocsPage } from '@/components/SectionDocsPage'
 import { getDb } from '@/utils/ContentDatabase'
 import { Metadata } from 'next'
@@ -110,6 +111,9 @@ export default async function ContentPage({ params }: { params: { id: string | s
 			return <CategoryDocsPage category={content.category} />
 		}
 		case 'article': {
+			if (content.article.componentCode) {
+				return <ExampleDocsPage article={content.article} />
+			}
 			return <ArticleDocsPage article={content.article} />
 		}
 		default: {

apps/docs/components/ArticleDocsPage.tsx

@@ -3,7 +3,6 @@ import { getDb } from '@/utils/ContentDatabase'
 import { ArticleDetails } from './ArticleDetails'
 import { ArticleNavLinks } from './ArticleNavLinks'
 import { Breadcrumb } from './Breadcrumb'
-import ExampleCodeBlock from './ExampleCodeBlock'
 import { Header } from './Header'
 import { Mdx } from './Mdx'
 import { Sidebar } from './Sidebar'
@@ -27,25 +26,13 @@ export async function ArticleDocsPage({ article }: { article: Article }) {
 		<>
 			<Header sectionId={section.id} />
 			<Sidebar headings={headings} {...sidebar} />
-			<main
+			<main className={`article${isGenerated ? ' article__api-docs' : ''}`}>
-				className={`article${isGenerated ? ' article__api-docs' : ''}${article.componentCode ? ' article__example' : ''}`}
-			>
 				<div className="page-header">
 					<Breadcrumb section={section} category={category} />
 					<h1>{article.title}</h1>
 				</div>
 				{article.hero && <Image alt="hero" title={article.title} src={`images/${article.hero}`} />}
 				{article.content && <Mdx content={article.content} />}
-				{article.componentCode && (
-					<ExampleCodeBlock
-						articleId={article.id}
-						files={{
-							'App.tsx': article.componentCode,
-							...(article.componentCodeFiles ? JSON.parse(article.componentCodeFiles) : null),
-						}}
-						activeFile={'App.tsx'}
-					/>
-				)}
 				{isGenerated ? null : <ArticleDetails article={article} />}
 				{links && <ArticleNavLinks links={links} />}
 			</main>

apps/docs/components/ExampleCodeBlock.tsx

@@ -25,12 +25,10 @@ export default function ExampleCodeBlock({
 	}
 
 	return (
-		<>
+		<div className="code-example">
-			<iframe
+			<iframe src={`${SERVER}/${articleId}/full`} />
-				src={`${SERVER}/${articleId}/full`}
-				style={{ border: 0, height: '50vh', width: '100%' }}
-			/>
 			<SandpackProvider
+				className="sandpack"
 				key={`sandpack-${theme}-${activeFile}`}
 				template="react-ts"
 				options={{ activeFile }}
@@ -47,6 +45,6 @@ export default function ExampleCodeBlock({
 			>
 				<SandpackCodeEditor readOnly />
 			</SandpackProvider>
-		</>
+		</div>
 	)
 }

apps/docs/components/ExampleDocsPage.tsx

@@ -0,0 +1,49 @@
+import { Article } from '@/types/content-types'
+import { getDb } from '@/utils/ContentDatabase'
+import { ArticleNavLinks } from './ArticleNavLinks'
+import { Breadcrumb } from './Breadcrumb'
+import ExampleCodeBlock from './ExampleCodeBlock'
+import { Header } from './Header'
+import { Mdx } from './Mdx'
+import { Sidebar } from './Sidebar'
+import { Image } from './mdx-components/generic'
+
+export async function ExampleDocsPage({ article }: { article: Article }) {
+	const db = await getDb()
+	const section = await db.getSection(article.sectionId)
+	const category = await db.getCategory(article.categoryId)
+	const headings = await db.getArticleHeadings(article.id)
+	const links = await db.getArticleLinks(article)
+	const sidebar = await db.getSidebarContentList({
+		sectionId: section.id,
+		categoryId: category.id,
+		articleId: article.id,
+	})
+
+	return (
+		<>
+			<Header sectionId={section.id} />
+			<Sidebar headings={headings} {...sidebar} />
+			<main className={`article article__example`}>
+				<div className="page-header">
+					<Breadcrumb section={section} category={category} />
+					<h1>{article.title}</h1>
+				</div>
+				{article.hero && <Image alt="hero" title={article.title} src={`images/${article.hero}`} />}
+				{article.description && <Mdx content={article.description} />}
+				{article.componentCode && (
+					<ExampleCodeBlock
+						articleId={article.id}
+						files={{
+							'App.tsx': article.componentCode,
+							...(article.componentCodeFiles ? JSON.parse(article.componentCodeFiles) : null),
+						}}
+						activeFile={'App.tsx'}
+					/>
+				)}
+				{article.content && <Mdx content={article.content} />}
+				{links && <ArticleNavLinks links={links} />}
+			</main>
+		</>
+	)
+}

apps/docs/components/Header.tsx

@@ -22,11 +22,19 @@ export function Header({ sectionId }: { sectionId?: string }) {
 			<Search />
 			<div className="layout__header__sections_and_socials">
 				<SectionLinks sectionId={sectionId} />
-				<ThemeSwitcher />
+				<a
+					href="https://x.com/tldraw/"
+					className="sidebar__button icon-button"
+					title="twitter"
+					target="_blank"
+				>
+					<Icon icon="twitter" />
+				</a>
 				<a
 					href="https://discord.com/invite/SBBEVCA4PG"
 					className="sidebar__button icon-button"
 					title="discord"
+					target="_blank"
 				>
 					<Icon icon="discord" />
 				</a>
@@ -34,9 +42,11 @@ export function Header({ sectionId }: { sectionId?: string }) {
 					href="https://github.com/tldraw/tldraw"
 					className="sidebar__button icon-button"
 					title="github"
+					target="_blank"
 				>
 					<Icon icon="github" />
 				</a>
+				<ThemeSwitcher />
 			</div>
 		</div>
 	)
@@ -62,7 +72,7 @@ export function SectionLinks({ sectionId }: { sectionId?: string | null }) {
 				Reference
 			</a>
 			<a
-				href="/examples/basic/develop"
+				href="/examples/basic/basic"
 				title="Examples"
 				data-active={sectionId === 'examples'}
 				className="layout_header__section"

apps/docs/components/Sidebar.tsx

@@ -42,7 +42,7 @@ export function Sidebar({ headings, links, sectionId, categoryId, articleId }: S
 	return (
 		<>
 			<linkContext.Provider value={{ activeId, articleId, categoryId, sectionId }}>
-				<div className="sidebar" onScroll={(e) => e.stopPropagation()}>
+				<div className="sidebar scroll-light" onScroll={(e) => e.stopPropagation()}>
 					<Search />
 					<div className="sidebar__section__links">
 						<SectionLinks sectionId={sectionId} />
@@ -125,7 +125,7 @@ function SidebarCategory({
 		<li className="sidebar__category">
 			{hasGroups ? (
 				<>
-					<span className="sidebar__link">{title}</span>
+					<span className="sidebar__link sidebar__category__title">{title}</span>
 					<Accordion.Root
 						type="multiple"
 						defaultValue={[`${linkCtx?.categoryId}-${activeGroup}-${linkCtx?.articleId}`]}
@@ -162,7 +162,11 @@ function SidebarCategory({
 				</>
 			) : (
 				<>
-					<Link href={children[0].url} title={title} className="sidebar__link">
+					<Link
+						href={children[0].url}
+						title={title}
+						className="sidebar__link sidebar__category__title"
+					>
 						{title}
 					</Link>
 					<ul className="sidebar__list">

apps/docs/scripts/functions/generateSection.ts

@@ -119,6 +119,13 @@ export function generateSection(section: InputSection, articles: Articles, index
 						: `/${section.id}/${categoryId}/${articleId}`,
 		}
 
+		if (isExamples) {
+			// split content above the first ---
+			const splitUp = parsed.content.split('---\n')
+			article.description = splitUp[0]
+			article.content = splitUp.slice(1).join('---\n')
+		}
+
 		if (isIndex) {
 			article.categoryIndex = -1
 			article.sectionIndex = -1

apps/docs/styles/globals.css

@@ -471,10 +471,6 @@ body {
 	overflow-x: auto;
 }
 
-.article.article__example pre {
-	margin: 0px;
-}
-
 .article__api-docs pre {
 	margin: 24px 0px;
 }
@@ -959,6 +955,12 @@ body {
 	box-shadow: var(--shadow-small);
 }
 
+.sidebar__category__title {
+	font-size: 14px;
+}
+
+/* --------------------- Search --------------------- */
+
 .sidebar .search__wrapper {
 	display: none;
 }
@@ -1235,6 +1237,33 @@ html[data-theme='light'] .hero__dark {
 	display: none;
 }
 
+/* ------------------ Code Example ------------------ */
+
+.code-example iframe {
+	border: 0;
+	min-height: 500px;
+	height: 50vh;
+	width: 100%;
+}
+
+.code-example .sandpack {
+	margin-bottom: 32px;
+}
+
+.code-example .sandpack {
+	border-radius: 6px;
+	padding: 0px;
+	border: 1px solid var(--color-tint-3);
+	border-radius: 6px;
+	overflow: hidden;
+}
+
+.code-example .sandpack pre {
+	background-color: transparent;
+	margin: 0px;
+	padding: 0px;
+}
+
 /* ------------------- Hero images ------------------ */
 
 .hero__images {
@@ -1344,3 +1373,34 @@ html[data-theme='light'] .hero__dark {
 [data-state='open'] > .CaretDown {
 	transform: rotate(-180deg);
 }
+
+/* --------------------- Scroll --------------------- */
+
+.scroll-light {
+	scrollbar-width: thin;
+}
+.scroll-light::-webkit-scrollbar {
+	display: block;
+	width: 8px;
+	height: 8px;
+	position: absolute;
+	top: 0;
+	left: 0;
+	background-color: inherit;
+}
+.scroll-light::-webkit-scrollbar-button {
+	display: none;
+	width: 0;
+	height: 10px;
+}
+.scroll-light::-webkit-scrollbar-thumb {
+	background-clip: padding-box;
+	width: 0;
+	min-height: 36px;
+	border: 2px solid transparent;
+	border-radius: 6px;
+	background-color: rgba(0, 0, 0, 0.25);
+}
+.scroll-light::-webkit-scrollbar-thumb:hover {
+	background-color: rgba(144, 144, 144);
+}