chore(docs): examples home page

scripts/generate-examples-derivatives/generate-docs.ts

@@ -19,7 +19,10 @@ export const generateDocs = async (examples: Example[]) => {
    */
 
   // Delete all existing to handle case of renaming or deleting examples.
-  await deleteFiles({ pattern: `./website/content/examples/*.md` })
+  await deleteFiles({
+    pattern: `./website/content/examples/*.md`,
+    options: { ignore: [`./website/content/examples/welcome.md`] },
+  })
 
   await Promise.all(examplesTransformed.map(async (example) => {
     await FS.writeFile(`./website/content/examples/${example.fileName.canonical}.md`, example.file.content)

website/.vitepress/config.ts

@@ -60,10 +60,13 @@ export default defineConfig({
     aside: 'left',
     nav: [
       { text: 'Guides', link: '/guides/overview/introduction' },
-      { text: 'Examples', link: '/examples/raw-raw' },
+      { text: 'Examples', link: '/examples' },
     ],
     sidebar: {
-      '/examples/': sidebarExamples,
+      '/examples/': [
+        { text: 'Welcome', link: 'examples/index' },
+        ...sidebarExamples,
+      ],
       '/guides/': [
         {
           text: 'Overview',

website/content/examples/index.md

@@ -0,0 +1,37 @@
+---
+aside: false
+---
+
+# Welcome To Graffle Examples
+
+Welcome to Graffle's collection of examples. Here you will find an assortment of runnable code showing how various features of Graffle work. Here are a few points of interest that may help you better use and understand the examples:
+
+1. The output (`stdout` and `stderr`) that the examples produced when run are captured below each example. Each log in the example receives its own code block in the outputs section. The first log is the first output codeblock, working down.
+
+2. [Twoslash](https://twoslash.netlify.app) is used so take advantage! Hover over code parts to see their types. This also gives you access to JSDoc which Graffle uses. You will find useful details in it, at a resolution that is not covered in the website docs.
+
+3. The source code for all examples can be found in the Graffle repository [here](https://github.com/jasonkuhrt/graffle/tree/main/examples). You can try any example out locally instantly by simply running:
+
+   ```sh
+   npx graffle try <example-slug>
+   ```
+
+   This will scaffold a local NodeJS project and run it immediately once. From there, do whatever you want!
+
+4. Most examples make requests to a "Pokemon" GraphQL Schema over over HTTP. For those, you can assume they began with:
+
+   ```sh
+   pnpm graphql-try pokemon
+   ```
+
+   Of these examples, some use a generated client while others the static. For generated client examples, you can assume all of them began with:
+
+   ```sh
+   pnpm graffle generate --schema http://localhost:4000/graphql --output ./pokemon
+   ```
+
+5. The Pokemon GraphQL schema source can be found [here](https://github.com/jasonkuhrt/graphql-try/tree/main/schemas/pokemon). As seen above, you can run it locally with just:
+
+   ```sh
+   npx graphql-try pokemon
+   ```

website/content/index.md

@@ -11,7 +11,7 @@ hero:
       link: /guides/overview/introduction
     - theme: alt
       text: Examples
-      link: /examples/raw-raw
+      link: /examples
   image:
     src: /_assets/logo-dark.png
     alt: Graffle