docs: update documentation structure, navigation, and content for consistency and clarity

jumski · jumski · commit d2968de15732 · 2025-05-08T06:13:12.000+02:00
- Renamed FAQ from edge-worker to general FAQ for broader scope
- Adjusted sidebar order for better navigation hierarchy
- Added banners indicating queue-only version for relevant docs
- Updated links and import paths for deployment and installation guides
- Corrected formatting and spacing in various MDX files for readability
- Clarified instructions and fixed typos in configuration and setup guides
- Improved consistency in feature descriptions and feature list presentation
- Minor content updates to reflect current process and best practices
diff --git a/pkgs/website/astro.config.mjs b/pkgs/website/astro.config.mjs
@@ -37,7 +37,12 @@ export default defineConfig({
   },
   redirects: {
     '/edge-worker/how-to/run-on-hosted-supabase':
-      '/edge-worker/how-to/deploy-to-supabasecom/',
+      '/how-to/deploy-to-supabasecom/',
+    '/edge-worker/faq/': '/faq/',
+    '/edge-worker/how-to/': '/faq/',
+    '/edge-worker/how-to/deploy-to-supabasecom/':
+      '/how-to/deploy-to-supabasecom/',
+    '/edge-worker/how-to/prepare-db-string/': '/how-to/prepare-db-string/',
   },
   integrations: [
     react(),
@@ -81,6 +86,10 @@ export default defineConfig({
                 label: 'START HERE',
                 autogenerate: { directory: 'getting-started/' },
               },
+              {
+                label: 'FAQ - Common Questions',
+                link: '/faq/',
+              },
               {
                 label: 'How To',
                 autogenerate: { directory: 'how-to/' },
@@ -103,12 +112,17 @@ export default defineConfig({
                 autogenerate: { directory: 'edge-worker/getting-started/' },
               },
               {
-                label: 'How to?',
-                autogenerate: { directory: 'edge-worker/how-to/' },
-              },
-              {
-                label: 'FAQ - Common Questions',
-                link: '/edge-worker/faq/',
+                label: 'How To',
+                items: [
+                  {
+                    label: 'Deploy to Supabase.com',
+                    link: '/how-to/deploy-to-supabasecom/',
+                  },
+                  {
+                    label: 'Prepare DB Connection String',
+                    link: '/how-to/prepare-db-string/',
+                  },
+                ],
               },
             ],
           },
diff --git a/pkgs/website/src/content/docs/edge-worker/getting-started/configuration.mdx b/pkgs/website/src/content/docs/edge-worker/getting-started/configuration.mdx
@@ -3,6 +3,9 @@ title: Configuration
 description: Learn how to configure EdgeWorker with options for configuring Supabase Queues, message processing, polling behavior, and retries. Includes defaults and best practices.
 sidebar:
   order: 3
+banner:
+  content: |
+    This guide is for the queue-only version of Edge Worker. Main docs are <a href="/getting-started/">here</a>
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
@@ -138,7 +141,7 @@ EdgeWorker.start(handler, {
 Amount of seconds to wait for a message to be available in the queue.
 
 :::caution[Polling and Worker Health]
-Keep `maxPollSeconds` at 5 seconds or lower. 
+Keep `maxPollSeconds` at 5 seconds or lower.
   <details>
   <summary>
   Here's why:
@@ -164,7 +167,7 @@ The interval (in milliseconds) between database polling attempts by `pgmq.read_w
 The default value is suitable for most use cases.
 
 <Aside type="caution" title="Polling Intervals">
-Keep `pollIntervalMs` lower than `maxPollSeconds * 1000`. 
+Keep `pollIntervalMs` lower than `maxPollSeconds * 1000`.
   <details>
   <summary>
   Here's why:
diff --git a/pkgs/website/src/content/docs/edge-worker/getting-started/create-first-worker.mdx b/pkgs/website/src/content/docs/edge-worker/getting-started/create-first-worker.mdx
@@ -3,6 +3,9 @@ title: Create your first worker
 description: Build a web scraping worker with EdgeWorker in minutes. Step-by-step tutorial to process queues on top of Supabase Background Tasks in a reliable way
 sidebar:
   order: 2
+banner:
+  content: |
+    This guide is for the queue-only version of Edge Worker. Main docs are <a href="/getting-started/">here</a>
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/edge-worker/getting-started/install-edge-worker.mdx b/pkgs/website/src/content/docs/edge-worker/getting-started/install-edge-worker.mdx
@@ -3,6 +3,9 @@ title: Install Edge Worker
 description: Quick setup guide for EdgeWorker on Supabase Background Tasks. Configure connection pooling, migrations, and environment in 5 simple steps.
 sidebar:
   order: 1
+banner:
+  content: |
+    This guide is for the queue-only version of Edge Worker. Main docs are <a href="/getting-started/">here</a>
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
@@ -27,7 +30,7 @@ If you haven't installed the CLI yet or need to upgrade, see Supabase's [install
 1. ### Install Edge Worker
 
     You can install Edge Worker using the pgflow installer (recommended) or [manually](/how-to/manual-installation/) if you want more control over the process.
-    
+
     Run the pgflow installer with npx:
 
     ```bash frame="none"
diff --git a/pkgs/website/src/content/docs/edge-worker/getting-started/observability.mdx b/pkgs/website/src/content/docs/edge-worker/getting-started/observability.mdx
@@ -3,6 +3,9 @@ title: Observability
 description: Learn how to monitor Edge Worker with logging and heartbeat tracking. Configure log levels and track worker status using built-in SQL views.
 sidebar:
   order: 4
+banner:
+  content: |
+    This guide is for the queue-only version of Edge Worker. Main docs are <a href="/getting-started/">here</a>
 ---
 
 ## Logging
@@ -33,7 +36,7 @@ Edge Worker sends heartbeats every 5 seconds and updates `last_heartbeat_at` col
 In order to get a list of active workers, we need to fetch those that have pinged in the last 6 seconds (+1s to account for delays):
 
 ```sql frame="none"
-SELECT * 
-FROM edge_worker.workers 
+SELECT *
+FROM edge_worker.workers
 WHERE last_heartbeat_at > now() - make_interval(secs => 6)
 ```
diff --git a/pkgs/website/src/content/docs/edge-worker/how-it-works.mdx b/pkgs/website/src/content/docs/edge-worker/how-it-works.mdx
@@ -1,6 +1,9 @@
 ---
 title: How it works?
 description: Discover how Edge Worker enhances Supabase Background Tasks with retries, concurrency control, and automatic scaling while ensuring zero message loss.
+banner:
+  content: |
+    This guide is for the queue-only version of Edge Worker. Main docs are <a href="/getting-started/">here</a>
 ---
 
 import { Aside } from "@astrojs/starlight/components";
@@ -9,7 +12,7 @@ import { Aside } from "@astrojs/starlight/components";
 
 [![](https://mermaid.ink/img/pako:eNplkcFugzAMhl8lyrl9AQ47VLBxqdSqlZAGHEziASokyEkmTaXvvoR0o1VziGL_n_9Y9pULLZEnvFItwdSxc1op5o9xTUxU_OQmaMAgy2SL7N0pYXutTMUjGU5WlItYaLog1VFAJSv14paCXdweyw8f-2MZLnZ06LBelXxXRk_DztAM-Gp9KA-kpRP-W7bdvs3Ga4aNaAy0OC_WdzD4B4IQVsLMvvkIZMUiA4mu_8ZHYjW5MxNp4dUnKC9zUHJA-h9R_VQTG-sQyDYINlTs-IaPSCP00q_gGvCK2w5HP53EPyXQJczp5jlwVp9-lOCJJYcbTtq13V_gJgkW0x78lEeefMFgfHYC9an1GqPsraZ9XPiy99svlAqmtA?type=png)](https://mermaid.live/edit#pako:eNplkcFugzAMhl8lyrl9AQ47VLBxqdSqlZAGHEziASokyEkmTaXvvoR0o1VziGL_n_9Y9pULLZEnvFItwdSxc1op5o9xTUxU_OQmaMAgy2SL7N0pYXutTMUjGU5WlItYaLog1VFAJSv14paCXdweyw8f-2MZLnZ06LBelXxXRk_DztAM-Gp9KA-kpRP-W7bdvs3Ga4aNaAy0OC_WdzD4B4IQVsLMvvkIZMUiA4mu_8ZHYjW5MxNp4dUnKC9zUHJA-h9R_VQTG-sQyDYINlTs-IaPSCP00q_gGvCK2w5HP53EPyXQJczp5jlwVp9-lOCJJYcbTtq13V_gJgkW0x78lEeefMFgfHYC9an1GqPsraZ9XPiy99svlAqmtA)
 
-### Features 
+### Features
 
 Under the hood, it wraps [Supabase Background Tasks](https://supabase.com/docs/guides/functions/background-tasks) and adds a lot of useful features:
 
diff --git a/pkgs/website/src/content/docs/faq.mdx b/pkgs/website/src/content/docs/faq.mdx
@@ -1,7 +1,6 @@
 ---
 title: FAQ - Common Questions
 description: Common questions about Edge Worker functionality, usage, and billing.
-topic: edge-worker
 ---
 
 ## Will running Edge Worker 24/7 affect my billing?
diff --git a/pkgs/website/src/content/docs/getting-started/compile-to-sql.mdx b/pkgs/website/src/content/docs/getting-started/compile-to-sql.mdx
@@ -2,7 +2,7 @@
 title: Compile flow to SQL
 description: Learn how to compile your flow definition to SQL and apply it to your database
 sidebar:
-  order: 3
+  order: 30
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/getting-started/create-first-flow.mdx b/pkgs/website/src/content/docs/getting-started/create-first-flow.mdx
@@ -2,7 +2,7 @@
 title: Create your first flow
 description: Learn how to define a workflow using pgflow's TypeScript DSL
 sidebar:
-  order: 2
+  order: 20
 ---
 
 import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/getting-started/install-pgflow.mdx b/pkgs/website/src/content/docs/getting-started/install-pgflow.mdx
@@ -2,7 +2,7 @@
 title: Install pgflow
 description: Quick setup guide for pgflow on Supabase. Set up the workflow engine in your project with a simple npx command.
 sidebar:
-  order: 1
+  order: 10
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/getting-started/run-flow.mdx b/pkgs/website/src/content/docs/getting-started/run-flow.mdx
@@ -2,7 +2,7 @@
 title: Run your Flow
 description: Learn how to start a pgflow worker, trigger your workflow, and monitor execution progress
 sidebar:
-  order: 3
+  order: 30
 ---
 
 import { Aside, Steps, Tabs, CardGrid, LinkCard, FileTree } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/how-to/create-reusable-tasks.mdx b/pkgs/website/src/content/docs/how-to/create-reusable-tasks.mdx
@@ -2,7 +2,7 @@
 title: Create Reusable Tasks
 description: Learn how to design and implement reusable task functions for pgflow workflows
 sidebar:
-  order: 3
+  order: 30
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/how-to/deploy-to-supabasecom.mdx b/pkgs/website/src/content/docs/how-to/deploy-to-supabasecom.mdx
@@ -2,11 +2,11 @@
 title: Deploy to Supabase.com
 description: Learn how to deploy, manage and monitor Edge Worker on Supabase Background Tasks. Step-by-step guide for deployment, starting, and maintaining workers.
 sidebar:
-  order: 1
+  order: 110
 ---
 
 import { Aside, Steps } from "@astrojs/starlight/components";
-import NotProductionReady from '../../../../components/NotProductionReady.astro';
+import NotProductionReady from '../../../components/NotProductionReady.astro';
 
 This guide explains the current process for deploying and maintaining workers in hosted environment.
 
diff --git a/pkgs/website/src/content/docs/how-to/manual-installation.mdx b/pkgs/website/src/content/docs/how-to/manual-installation.mdx
@@ -69,7 +69,7 @@ EDGE_WORKER_LOG_LEVEL="info"
 ```
 
 :::caution[Special Characters in Passwords]
-If your database password contains special characters (`@`, `&`, `:`, etc.), you must URL-encode them to avoid authentication errors. See our [DB Connection URLs](/edge-worker/how-to/prepare-db-string/) guide for detailed instructions.
+If your database password contains special characters (`@`, `&`, `:`, etc.), you must URL-encode them to avoid authentication errors. See our [DB Connection URLs](/how-to/prepare-db-string/) guide for detailed instructions.
 :::
 
 ### 3. Setup Connection Pool
diff --git a/pkgs/website/src/content/docs/how-to/monitor-flow-execution.mdx b/pkgs/website/src/content/docs/how-to/monitor-flow-execution.mdx
@@ -2,7 +2,7 @@
 title: Monitor flow execution
 description: Learn how to monitor and observe pgflow workflow execution using SQL queries
 sidebar:
-  order: 1
+  order: 10
 ---
 
 import { Aside, Steps, Tabs, CardGrid, LinkCard, FileTree } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/how-to/organize-flows-code.mdx b/pkgs/website/src/content/docs/how-to/organize-flows-code.mdx
@@ -2,7 +2,7 @@
 title: Organize Flows code
 description: Learn how to structure your pgflow codebase for maintainability and reusability
 sidebar:
-  order: 2
+  order: 20
 ---
 
 import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/how-to/prepare-db-string.mdx b/pkgs/website/src/content/docs/how-to/prepare-db-string.mdx
@@ -1,6 +1,8 @@
 ---
 title: Prepare DB Connection URL
 description: How to handle special characters in passwords for Edge Worker connection strings
+sidebar:
+  order: 120
 ---
 
 import { Aside } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/how-to/update-flow-options.mdx b/pkgs/website/src/content/docs/how-to/update-flow-options.mdx
@@ -2,7 +2,7 @@
 title: Update Flow Options
 description: Learn how to safely update configuration options for existing flows
 sidebar:
-  order: 4
+  order: 40
 ---
 
 import { Aside } from "@astrojs/starlight/components";
diff --git a/pkgs/website/src/content/docs/how-to/version-your-flows.mdx b/pkgs/website/src/content/docs/how-to/version-your-flows.mdx
@@ -2,7 +2,7 @@
 title: Version your flows
 description: Learn how to safely update your flows without breaking existing runs
 sidebar:
-  order: 5
+  order: 50
 ---
 
 ## Current Compilation Limitations
