docs: add links from reference docs back to build docs

cypress.config.ts

@@ -17,5 +17,6 @@ export default defineConfig({
         },
       })
     },
+    experimentalMemoryManagement: true,
   },
 })

cypress/e2e/broken-links.cy.ts

@@ -31,6 +31,14 @@ const IGNORED_URLS = [
   'https://portal.azure.com',
 ]
 
+const rootBaseUrl = Cypress.config('baseUrl')
+
+const isInternalUrl = (url: string) => {
+  // check against the base url
+  // and check if the url does not contain a file extension
+  return url.startsWith(rootBaseUrl) && !url.includes('.')
+}
+
 const isExternalUrl = (url: string) => {
   return !url.includes('localhost')
 }
@@ -67,14 +75,11 @@ describe('Broken links test suite', () => {
 
       links
         .filter((_i, link) => {
+          const href = link.getAttribute('href')
+          const src = link.getAttribute('src')
+
           return !IGNORED_URLS.some(
-            (l) =>
-              //@ts-ignore
-              (link.getAttribute('href') &&
-                link.getAttribute('href')?.includes(l)) ||
-              //@ts-ignore
-              (link.getAttribute('src') &&
-                link.getAttribute('src').includes(l)),
+            (l) => href?.includes(l) || src?.includes(l),
           )
         })
         .each((link) => {
@@ -87,6 +92,25 @@ describe('Broken links test suite', () => {
             cy.log(`link already checked`)
             expect(VISITED_SUCCESSFUL_LINKS[url]).to.be.true
           } else {
+            // if the link is internal then check the link against the pages fixture (sitemap)
+            if (isInternalUrl(url)) {
+              // clean the url by removing the base url and query params
+              const rootBaseUrlRegex = new RegExp(`^${rootBaseUrl}`)
+              let cleanUrl = url.replace(rootBaseUrlRegex, '')
+              const queryIndex = cleanUrl.indexOf('?')
+              cleanUrl =
+                queryIndex !== -1 ? cleanUrl.slice(0, queryIndex) : cleanUrl
+
+              cy.log(`checking internal link: ${cleanUrl}`)
+              if (!pages.includes(cleanUrl)) {
+                assert.fail(`${cleanUrl} is not part of the pages fixture`)
+              } else {
+                VISITED_SUCCESSFUL_LINKS[url] = true
+              }
+
+              return
+            }
+
             cy.wait(25)
 
             req(url).then((res: Cypress.Response<any>) => {

docs/reference/dart/api/api-all.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a single handler fo
 
 # Dart - api.all()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on a route.
 
 <Note>

docs/reference/dart/api/api-delete.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register an API route and se
 
 # Dart - api.delete()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register an API route and set a specific HTTP DELETE handler on that route.
 
 <Note>

docs/reference/dart/api/api-get.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register an API route and se
 
 # Dart - api.get()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register an API route and set a specific HTTP GET handler on that route.
 
 <Note>

docs/reference/dart/api/api-patch.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register an API route and se
 
 # Dart - api.patch()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register an API route and set a specific HTTP PATCH handler on that route.
 
 <Note>

docs/reference/dart/api/api-post.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register an API route and se
 
 # Dart - api.post()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register an API route and set a specific HTTP POST handler on that route.
 
 <Note>

docs/reference/dart/api/api-put.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register an API route and se
 
 # Dart - api.put()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register an API route and set a specific HTTP PUT handler on that route.
 
 <Note>

docs/reference/dart/api/api-route-all.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a single handler fo
 
 # Dart - api.route.all()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on the route.
 
 ```dart

docs/reference/dart/api/api-route-delete.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a handler for HTTP
 
 # Dart - api.route.delete()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a handler for HTTP DELETE requests to the route.
 
 ```dart

docs/reference/dart/api/api-route-get.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a handler for HTTP
 
 # Dart - api.route.get()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a handler for HTTP GET requests to the route.
 
 ```dart

docs/reference/dart/api/api-route-patch.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a handler for HTTP
 
 # Dart - api.route.patch()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a handler for HTTP PATCH requests to the route.
 
 ```dart

docs/reference/dart/api/api-route-post.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a handler for HTTP
 
 # Dart - api.route.post()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a handler for HTTP POST requests to the route.
 
 ```dart

docs/reference/dart/api/api-route-put.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a handler for HTTP
 
 # Dart - api.route.put()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Register a handler for HTTP PUT requests to the route.
 
 ```dart

docs/reference/dart/api/api-route.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Creates a new route (path) w
 
 # Dart - api.route()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Creates a new route (path) within an API.
 
 ```dart

docs/reference/dart/api/api.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Create APIs with the Nitric
 
 # Dart - api()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about APIs
+  in Nitric start with the [API docs](/apis).
+</Note>
+
 Creates a new HTTP API.
 
 ```dart

docs/reference/dart/batch/job-handler.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Register a job handler to wi
 
 # Dart - job.handler()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about Batch
+  Services in Nitric start with the [Batch docs](/batch).
+</Note>
+
 Job handlers are the code that is run when a job request is submitted. These handlers should be written in a separate file to your services.
 
 ```dart

docs/reference/dart/batch/job-submit.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Submit a batch job request w
 
 # Dart - job.submit()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about Batch
+  Services in Nitric start with the [Batch docs](/batch).
+</Note>
+
 Jobs may be submitted from Nitric `services` or other `batches` using the `submit` method on the job reference. When submitting a job you can provide a payload that will be passed to the job handler function.
 
 ```dart

docs/reference/dart/batch/job.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Create Batch Jobs with the N
 
 # Dart - job()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about Batch
+  Services in Nitric start with the [Batch docs](/batch).
+</Note>
+
 Creates a new Batch Job.
 
 ```dart

docs/reference/dart/index.mdx

@@ -8,6 +8,12 @@ This SDK reference provides documentation for the services and methods in Nitric
 
 The library provides the ability to define and interact with cloud resources, as well as build application services.
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. If you're just
+  learning Nitric, we recommend starting with the
+  [Quickstart](/get-started/quickstart) guide.
+</Note>
+
 ## Installation
 
 If you used a Nitric starter template for Dart to scaffold your project, then `nitric_sdk` will already be included in the dependencies in your `pubspec.yaml` file. Using starter templates is the recommended installation option since it ensures the other files and configuration needed are also set up.

docs/reference/dart/keyvalue/keyvalue-delete.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Delete key from a key value
 
 # Dart - kv.delete()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about
+  Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue).
+</Note>
+
 Delete key from a key value store.
 
 ```dart

docs/reference/dart/keyvalue/keyvalue-get.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Get a value from a key value
 
 # Dart - kv.get()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about
+  Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue).
+</Note>
+
 Get a value from a key value store.
 
 ```dart

docs/reference/dart/keyvalue/keyvalue-keys.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Retrieve all or some of the
 
 # Dart - kv.keys()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about
+  Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue).
+</Note>
+
 Return an async iterable of keys in the store.
 
 ```dart

docs/reference/dart/keyvalue/keyvalue-set.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Store a key value pair in a
 
 # Dart - kv.set()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about
+  Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue).
+</Note>
+
 Store a key value pair in a key value store.
 
 ```dart

docs/reference/dart/keyvalue/keyvalue.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Creates a new key value stor
 
 # Dart - kv()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about
+  Key/Value Stores in Nitric start with the [Key/Value Store docs](/keyvalue).
+</Note>
+
 Creates a new key value store to get, set, and delete key value pairs.
 
 ```dart

docs/reference/dart/queues/queue-dequeue.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Dequeue messages."
 
 # Dart - queue.dequeue()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about Queues
+  in Nitric start with the [Async Messaging docs](/messaging#queues).
+</Note>
+
 Dequeue messages.
 
 ```dart

docs/reference/dart/queues/queue-enqueue.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Send messages to a queue."
 
 # Dart - queue.enqueue()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about Queues
+  in Nitric start with the [Async Messaging docs](/messaging#queues).
+</Note>
+
 Send messages to a queue.
 
 ```dart

docs/reference/dart/queues/queue.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Creates a new Queue to proce
 
 # Dart - queue()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about Queues
+  in Nitric start with the [Async Messaging docs](/messaging#queues).
+</Note>
+
 Creates a new Queue to process asynchronous messages.
 
 ```dart

docs/reference/dart/schedule/schedule-cron.mdx

@@ -4,6 +4,11 @@ description: "Reference for Nitric's Dart library - Sets the cron expression and
 
 # Dart - schedule.cron()
 
+<Note>
+  This is reference documentation for the Nitric Dart SDK. To learn about
+  Schedules in Nitric start with the [Schedule docs](/schedules).
+</Note>
+
 Sets the cron expressions that determines when the schedule triggers and a callback to be triggered.
 
 ```dart