docs: minor cleanup to getting started guide

Author: runspired

docs-viewer/src/site-utils.ts

@@ -1,6 +1,7 @@
 import path from 'path';
 // @ts-expect-error missing from Bun types
 import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { write } from 'node:console';
 
 const DefaultOpenGroups: string[] = [];
 const AlwaysOpenGroups: string[] = ['configuration.setup'];
@@ -138,7 +139,16 @@ export async function getGuidesStructure(withRewrites = false) {
   const result = deepConvert(groups);
   // console.log(JSON.stringify(result, null, 2));
   // console.log(JSON.stringify(rewritten, null, 2));
-
+  const structure = { paths: result, rewritten };
+
+  writeFileSync(
+    path.join(__dirname, '../docs.warp-drive.io/guides/nav.json'),
+    JSON.stringify(structure, null, 2),
+    'utf-8'
+  );
+  await import(path.join(__dirname, '../docs.warp-drive.io/guides/nav.json'), {
+    with: { type: 'json' },
+  });
   return { paths: result, rewritten };
 }
 
@@ -158,7 +168,7 @@ function deepConvert(obj: Record<string, any>) {
   });
 }
 
-type SidebarItem = { text: string; items?: SidebarItem[] };
+type SidebarItem = { text: string; items?: SidebarItem[]; link?: string; collapsed?: boolean };
 
 const OLD_PACKAGES = [
   '@ember-data/adapter',
@@ -256,24 +266,40 @@ outline:
   level: [2, 3]
 ---
 `;
+const ApiDocumentation = `# API Docs\n\n`;
 
 export async function postProcessApiDocs() {
   const dir = path.join(__dirname, '../tmp/api');
   const outDir = path.join(__dirname, '../docs.warp-drive.io/api');
   mkdirSync(outDir, { recursive: true });
-  console.log('Ensured API Docs Directory Exists:', outDir);
 
   // cleanup and prepare the sidebar items
   const sidebarPath = path.join(outDir, 'typedoc-sidebar.json');
   const navStructure = JSON.parse(readFileSync(path.join(dir, 'typedoc-sidebar.json'), 'utf-8')) as SidebarItem[];
   const sidebar = splitApiDocsSidebar(cleanSidebarItems(navStructure));
   writeFileSync(sidebarPath, JSON.stringify(sidebar, null, 2), 'utf-8');
 
-  console.log(`Processed API Docs Sidebar: ${sidebarPath}`);
+  // get the package list
+  const NewPackages: string[] = [];
+  const OldPackages: string[] = [];
+  for (const item of sidebar.newPackages) {
+    NewPackages.push(`- [${item.text}](${item.link!})`);
+  }
+  for (const item of sidebar.oldPackages) {
+    OldPackages.push(`- [${item.text}](${item.link!})`);
+  }
+
+  // generate the API documentation
+  const apiDocumentation = `${ApiDocumentation}\n\n## Main Packages\n\n${NewPackages.join('\n')}\n\n## Legacy Packages\n\n${OldPackages.join('\n')}\n\n`;
 
   // copy the rest of the files
   const files = globSync('**/*.md', { cwd: dir, nodir: true });
   for (const file of files) {
+    if (file === 'index.md') {
+      // Generate a custom index.md file
+      writeFileSync(path.join(outDir, 'index.md'), apiDocumentation, 'utf-8');
+      continue;
+    }
     const content = readFileSync(path.join(dir, file), 'utf-8');
     const outFile = path.join(outDir, file);
     mkdirSync(path.dirname(outFile), { recursive: true });

guides/1-configuration/1-overview.md

@@ -2,9 +2,7 @@
 title: Overview
 ---
 
-::: tip EmberData/WarpDrive Packages Have Been [Simplified](https://rfcs.emberjs.com/id/1075-warp-drive-package-unification/)!
-
-Looking for the [Old Package Setup Guide?](./4-old-package-setup/1-overview.md)
+::: warning 💡 Looking for the [Legacy Package Configuration Guide?](./4-legacy-package-setup/1-overview)
 :::
 
 # Configuration

guides/1-configuration/2-setup/1-universal.md

@@ -3,14 +3,13 @@ outline:
   level: 2,3
 ---
 
-::: tip EmberData/WarpDrive Packages Have Been [Simplified](https://rfcs.emberjs.com/id/1075-warp-drive-package-unification/)
-
-Looking for the [Old Package Setup Guide?](../4-old-package-setup/1-overview.md)
+::: warning 💡 Looking for the [Legacy Package Setup Guide?](../4-legacy-package-setup/2-setup/1-universal)
 :::
 
 # Setup
 
-All frameworks should follow this configuration first.
+All frameworks should follow this configuration before continuing on to their framework
+specific setup guide.
 
 ## Configure the Build Plugin
 
@@ -85,19 +84,13 @@ module.exports = async function (defaults) {
 
 ## Configure the Store
 
-To get up and running we need to configure a `Store` to understand how we want
-to handle requests, what our data looks like, how to cache it, and what sort of
-reactive objects to create for that data.
+The `Store` is the central piece of the ***Warp*Drive** experience, linking
+together how we handle requests, the schemas for what our data looks like,
+how to cache it, and what sort of reactive objects to create for that data.
 
 Here's an example final configuration. Below we'll show each bit in parts and
 discuss what each does.
 
-::: tip 💡 Guide
-Looking for Legacy Adapter/Serializer Support?
-
-→ After finishing this page read the guide for [Ember.js](./2-ember.md)
-:::
-
 ::: code-group
 
 ```ts [Universal]