docs: rework docs site to have different sections (#2686)

This PR starts putting in place the high-level changes we want to make
to the docs site.
- It makes separate sections for Reference and Examples and Community.
- Gets rid of the secondary sidebar and integrates it into the main
sidebar.
- Groups the reference articles by type.
- Pulls in the examples alongside code and a live playground so people
don't have to visit examples.tldraw.com separately.

<img width="1458" alt="Screenshot 2024-01-30 at 09 43 46"
src="https://github.com/tldraw/tldraw/assets/469604/4f5aa339-3a69-4d9b-9b9f-dfdddea623e8">

Again, this is the top-level changes and there's more to be done for the
next PR(s):
  - create quick start page
  - clean up installation page
  - add accordion to Examples page prbly
  - put fun stuff in header (from footer)
  - landing page
  - something for landing page of API
  - search cmd-k and border
  - cleanup _sidebarReferenceContentLinks
  - external links _blank
  - address potential skew issue with code examples
  - have a link to other examples (next.js, etc.)

### Change Type

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

### Test Plan

1. Make sure examples work!

### Release Notes

- Rework our docs site to pull together the examples app and reference
section more cohesively.

---------

Co-authored-by: Taha <98838967+Taha-Hassan-Git@users.noreply.github.com>
Co-authored-by: Steve Ruiz <steveruizok@gmail.com>
Co-authored-by: Mitja Bezenšek <mitja.bezensek@gmail.com>
Co-authored-by: alex <alex@dytry.ch>
Co-authored-by: Lu Wilson <l2wilson94@gmail.com>
Co-authored-by: Dan Groshev <git@dgroshev.com>

apps/docs/utils/ContentDatabase.ts

@@ -141,7 +141,10 @@ export class ContentDatabase {
 		return { prev: prev ?? null, next: next ?? null }
 	}
 
+	// TODO(mime): make this more generic, not per docs area
 	private _sidebarContentLinks: SidebarContentLink[] | undefined
+	private _sidebarReferenceContentLinks: SidebarContentLink[] | undefined
+	private _sidebarExamplesContentLinks: SidebarContentLink[] | undefined
 
 	async getSidebarContentList({
 		sectionId,
@@ -154,9 +157,15 @@ export class ContentDatabase {
 	}): Promise<SidebarContentList> {
 		let links: SidebarContentLink[]
 
-		if (this._sidebarContentLinks && process.env.NODE_ENV !== 'development') {
+		const cachedLinks =
+			sectionId === 'examples'
+				? this._sidebarExamplesContentLinks
+				: sectionId === 'reference'
+					? this._sidebarReferenceContentLinks
+					: this._sidebarContentLinks
+		if (cachedLinks && process.env.NODE_ENV !== 'development') {
 			// Use the previously cached sidebar links
-			links = this._sidebarContentLinks
+			links = cachedLinks
 		} else {
 			// Generate sidebar links and cache them
 			links = []
@@ -168,12 +177,31 @@ export class ContentDatabase {
 
 				const children: SidebarContentLink[] = []
 
+				if (section.sidebar_behavior === 'hidden') {
+					continue
+				}
+
+				if (
+					(sectionId === 'reference' && section.id !== 'reference') ||
+					(sectionId !== 'reference' && section.id === 'reference')
+				) {
+					continue
+				}
+
+				if (
+					(sectionId === 'examples' && section.id !== 'examples') ||
+					(sectionId !== 'examples' && section.id === 'examples')
+				) {
+					continue
+				}
+
 				if (section.sidebar_behavior === 'show-title') {
 					links.push({
 						type: 'article',
 						title: section.title,
 						url: section.path,
 						articleId: section.id,
+						groupId: null,
 					})
 					continue
 				}
@@ -204,6 +232,7 @@ export class ContentDatabase {
 								articleId: article.id,
 								title: article.title,
 								url: article.path,
+								groupId: article.groupId,
 							}
 
 							ucg.push(sidebarArticleLink)
@@ -228,6 +257,7 @@ export class ContentDatabase {
 							const sidebarArticleLink: SidebarContentArticleLink = {
 								type: 'article' as const,
 								articleId: article.id,
+								groupId: article.groupId,
 								title: article.title,
 								url: article.path,
 							}
@@ -244,7 +274,14 @@ export class ContentDatabase {
 				links.push({ type: 'section', title: section.title, url: section.path, children })
 
 				// Cache the links structure for next time
-				this._sidebarContentLinks = links
+				if (sectionId === 'examples') {
+					this._sidebarExamplesContentLinks = links
+				}
+				if (sectionId === 'reference') {
+					this._sidebarReferenceContentLinks = links
+				} else {
+					this._sidebarContentLinks = links
+				}
 			}
 		}