[docs] design shuffle (#2951)

This PR incorporates design tweaks from #2922 without the home page or
content changes.

These are:
- Replacing all `hello@tldraw.com` with `sales@tldraw.com`
- Fix mailto links.
- Showing the first item in a section on direct routes to the section
- Splitting the article page for human-written content from article page
for generated content
- Splitting the layout for the landing page from the rest of the site
(temporarily identical to the regular content)
- Removing headings from left sidebar
- Restoring headings in right sidebar for human-written pages with > 1
heading link
- Styling block quote
- Adjusting section link appearance / layout in header / menu
- Changing the order of search results to preference docs over examples
- Updating copy on events
- Removing copy on user interface menus
- Adding hero as prop to all articles
- Updated icon
- Fixing a few broken links
- Replaces the sandpack code blocks with hljs code blocks, except in
examples.

### Change Type

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

apps/docs/scripts/functions/checkBrokenLinks.ts

@@ -1,29 +1,25 @@
 import { nicelog } from '@/utils/nicelog'
-import blc from 'broken-link-checker'
-
-const IGNORED_URLS = ['https://twitter.com/tldraw', 'https://tldraw.com']
+import { check } from 'linkinator'
 
 export async function checkBrokenLinks() {
-	nicelog('Checking broken links...')
-	const checked = new Set<string>()
-	const checker = new blc.SiteChecker(
-		{
-			filterLevel: 1,
-		},
-		{
-			link(result) {
-				if (IGNORED_URLS.includes(result.url.original)) return
-				if (checked.has(result.url.resolved)) return
-				// nicelog('Checking', result.url.resolved.replace('http://localhost:3001', ''))
-				if (result.broken) {
-					nicelog(`BROKEN: ${result.url.resolved} on page ${result.base.resolved}`)
-				}
-				checked.add(result.url.resolved)
-			},
-			end() {
-				nicelog('done')
-			},
-		}
+	const results = await check({
+		path: 'http://localhost:3001',
+		recurse: true,
+	})
+
+	// All good
+	if (results.passed) return
+
+	// There seems to be a porblem
+	nicelog(
+		`𐄂 Broken links detected!\n\n` +
+			results.links
+				.filter((result) => result.state !== 'OK')
+				.map(
+					(result, i) =>
+						`${i + 1}.\t${result.url}\n\tFrom: ${result.parent}\n\tStatus: ${result.status}`
+				)
+				.join('\n\n') +
+			'\n\n'
 	)
-	checker.enqueue('http://localhost:3001/docs/assets', null)
 }

apps/docs/scripts/functions/createApiMarkdown.ts

@@ -13,6 +13,7 @@ export async function createApiMarkdown() {
 		description: "Reference for the tldraw package's APIs (generated).",
 		categories: [],
 		sidebar_behavior: 'reference',
+		hero: null,
 	}
 
 	const addedCategories = new Set<string>()
@@ -55,6 +56,7 @@ export async function createApiMarkdown() {
 						id: title,
 						path: null,
 					})),
+					hero: null,
 				})
 				addedCategories.add(categoryName)
 			}

apps/docs/scripts/functions/generateExamplesContent.ts

@@ -8,13 +8,14 @@ const section: InputSection = {
 	title: 'Examples',
 	description: 'Code recipes for bending tldraw to your will.',
 	categories: [
-		{ id: 'basic', title: 'Getting Started', description: '', groups: [] },
-		{ id: 'ui', title: 'UI & Theming', description: '', groups: [] },
-		{ id: 'shapes/tools', title: 'Shapes & Tools', description: '', groups: [] },
-		{ id: 'data/assets', title: 'Data & Assets', description: '', groups: [] },
-		{ id: 'editor-api', title: 'Editor API', description: '', groups: [] },
-		{ id: 'collaboration', title: 'Collaboration', description: '', groups: [] },
+		{ id: 'basic', title: 'Getting Started', description: '', groups: [], hero: null },
+		{ id: 'ui', title: 'UI & Theming', description: '', groups: [], hero: null },
+		{ id: 'shapes/tools', title: 'Shapes & Tools', description: '', groups: [], hero: null },
+		{ id: 'data/assets', title: 'Data & Assets', description: '', groups: [], hero: null },
+		{ id: 'editor-api', title: 'Editor API', description: '', groups: [], hero: null },
+		{ id: 'collaboration', title: 'Collaboration', description: '', groups: [], hero: null },
 	],
+	hero: null,
 	sidebar_behavior: 'show-links',
 }
 

apps/docs/scripts/functions/generateSection.ts

@@ -166,6 +166,7 @@ export function generateSection(section: InputSection, articles: Articles, index
 			groups: [],
 			path: `/${section.id}/ucg`,
 			content: null,
+			hero: null,
 		},
 	]
 
@@ -188,6 +189,7 @@ export function generateSection(section: InputSection, articles: Articles, index
 				index: i + 1,
 				path: `/${section.id}/${inputCategory.id}`,
 				content: null,
+				hero: null,
 				groups: inputCategory.groups.map(({ id }, i) => ({
 					id,
 					title: id,
@@ -210,6 +212,7 @@ export function generateSection(section: InputSection, articles: Articles, index
 		index,
 		categories,
 		content: '',
+		hero: section.hero ?? null,
 		path: `/${section.id}`,
 	}
 }

apps/docs/scripts/functions/getApiMarkdown.ts

@@ -217,7 +217,7 @@ async function addDocComment(result: Result, member: ApiItem) {
 
 		if (exampleBlocks.length) {
 			result.markdown += `\n\n`
-			result.markdown += `##### Example\n\n`
+			result.markdown += `<ApiHeading>Example</ApiHeading>\n\n`
 			for (const example of exampleBlocks) {
 				result.markdown += await MarkdownWriter.docNodeToMarkdown(member, example.content)
 			}
@@ -393,7 +393,7 @@ function addTags(result: Result, member: ApiItem) {
 		tags.push('readonly')
 	}
 	tags.push(member.kind.toLowerCase())
-	result.markdown += `<Small>${tags.join(' ')}</Small>\n\n`
+	result.markdown += `<Small>${tags.filter((t) => t.toLowerCase() !== 'none').join(' ')}</Small>\n\n`
 }
 
 function addReferences(result: Result, member: ApiItem) {