fix: docs layout + troubleshoot section (#2670)

Kitenite · Kitenite · commit 52263ed28735 · 2025-08-14T09:15:48.000-07:00
* update docs layout

* update docs styling

* add troubleshoot section
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,9 @@
 # Contributing
 
 To keep all docs in one place, we've moved the contributing guide here:
-https://docs.onlook.com/contributing/developers
+https://docs.onlook.com/developers
 
 ### Running locally
 
 To get set up and run Onlook locally, see here:
-https://docs.onlook.com/contributing/developers/running-locally
+https://docs.onlook.com/developers/running-locally
diff --git a/README.md b/README.md
@@ -100,7 +100,7 @@ builders.
 ## Getting Started
 
 Available soon with a [hosted app](https://onlook.com) or
-[run locally](https://docs.onlook.com/contributing/developers/running-locally).
+[run locally](https://docs.onlook.com/developers/running-locally).
 
 ### Usage
 
@@ -138,8 +138,7 @@ objects, and experiment with layouts.
 For full documentation, visit [docs.onlook.com](https://docs.onlook.com)
 
 To see how to Contribute, visit
-[Contributing to Onlook](https://docs.onlook.com/contributing/developers) in our
-docs.
+[Contributing to Onlook](https://docs.onlook.com/developers) in our docs.
 
 ## How it works
 
@@ -158,7 +157,7 @@ displays DOM elements declaratively (e.g. jsx/tsx/html). We are focused on
 making it work well with Next.js and TailwindCSS for now.
 
 For a full walkthrough, check out our
-[Architecture Docs](https://docs.onlook.com/contributing/developers/architecture).
+[Architecture Docs](https://docs.onlook.com/developers/architecture).
 
 ### Our Tech Stack
 
diff --git a/docs/content/docs/developers/appendix.mdx b/docs/content/docs/developers/appendix.mdx
diff --git a/docs/content/docs/developers/architecture.mdx b/docs/content/docs/developers/architecture.mdx
diff --git a/docs/content/docs/developers/index.mdx b/docs/content/docs/developers/index.mdx
@@ -21,7 +21,7 @@ When contributing to this repository, please first discuss the change you wish t
 Please note we have a [code of conduct](https://github.com/onlook-dev/onlook/blob/main/CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
 
 ### Running the project locally
-You can build the project from source using instructions [here](/contributing/developers/running-locally).
+You can build the project from source using instructions [here](/developers/running-locally).
 
 ### Pull Request Process
 
diff --git a/docs/content/docs/developers/meta.json b/docs/content/docs/developers/meta.json
diff --git a/docs/content/docs/developers/running-locally.mdx b/docs/content/docs/developers/running-locally.mdx
@@ -73,7 +73,7 @@ Run the interactive environment setup script:
 bun run setup:env
 ```
 
-Note: If you'd prefer manually setting up the environment variables, see the [appendix](/contributing/developers/appendix) for instructions.
+Note: If you'd prefer manually setting up the environment variables, see the [appendix](/developers/appendix) for instructions.
 
 ### 6. Initialize the database
 
@@ -125,6 +125,6 @@ node --version
 Now that you have Onlook running locally, explore these resources to make your first contribution or learn more about the architecture. Understanding how Onlook works will help you contribute more effectively to this visual editor for React and TailwindCSS.
 
 <Cards>
-  <Card title="Learn about Architecture" href="/contributing/developers/architecture" />
-  <Card title="How to Contribute" href="/contributing/developers" />
+  <Card title="Learn about Architecture" href="/developers/architecture" />
+  <Card title="How to Contribute" href="/developers" />
 </Cards>
diff --git a/docs/content/docs/developers/troubleshooting.mdx b/docs/content/docs/developers/troubleshooting.mdx
@@ -0,0 +1,36 @@
+---
+title: Troubleshooting
+description: Troubleshooting common issues
+---
+
+# Common Issues
+
+### Codesandbox Preview
+
+Codesandbox may ask you to confirm to proceed. You can click the button by switching to Preview mode in onlook, and click the "Yes, proceed to preview" link and switch back. The UI should render properly inside the iframe after that.
+
+![Codesandbox confirmation mode](/images/csb-proceed-to-preview.png)
+
+![Switch to Preview mode](/images/visual-switch-to-preview.png)
+
+### Authentication Issues
+
+If you encounter issues with reloading pages and being unauthenticated then check your node version, install a more recent version, re-install dependencies and restart the project.
+Minimum version `v20.16.0` or latest is recommended.
+
+Avoid version `v20.11.0` of Node as it has shown this issue in the past.
+
+```bash
+node --version
+```
+
+You may have to delete cookies to clear the authentication state.
+
+![Delete cookies](/images/delete-cookies.png)
+
+### "Column not found" error
+
+If you encounter issues such as "Column not found" error, your database may be out of sync with the schema. There are 2 things to try to get it back in sync:
+
+1. Run `bun db:push` to push the schema to the database. If there are conflicts, you can try step 2.
+2. Run `bun db:reset` to fully reset the database and re-run the migrations. WARNING: This will delete all data in the database.
diff --git a/docs/content/docs/faq.mdx b/docs/content/docs/faq.mdx
@@ -123,4 +123,4 @@ You can report bugs or request features on our [GitHub Issues page](https://gith
 
 ### How can I contribute to Onlook?
 
-Check out our [Contributing Guide](/contributing/developers) for information on how to contribute to Onlook.
+Check out our [Contributing Guide](/developers) for information on how to contribute to Onlook.
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
@@ -47,9 +47,9 @@ Ready to dive in? Here's how to get started with Onlook:
 Want to contribute to Onlook? Check out our developer documentation:
 
 <Cards>
-  <Card title="How to Contribute" href="/contributing/developers" />
-  <Card title="Run Onlook Locally" href="/contributing/developers/running-locally" />
-  <Card title="Onlook Architecture" href="/contributing/developers/architecture" />
+  <Card title="How to Contribute" href="/developers" />
+  <Card title="Run Onlook Locally" href="/developers/running-locally" />
+  <Card title="Onlook Architecture" href="/developers/architecture" />
 </Cards>
 
 ## Need Help?
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
@@ -1,9 +1,9 @@
 {
-  "pages": [
-    "index",
-    "getting-started",
-    "tutorials",
-    "contributing",
-    "faq"
-  ]
-}
+    "pages": [
+        "index",
+        "getting-started",
+        "tutorials",
+        "developers",
+        "faq"
+    ]
+}
diff --git a/docs/public/images/delete-cookies.png b/docs/public/images/delete-cookies.png
diff --git a/docs/public/sitemap-0.xml b/docs/public/sitemap-0.xml
@@ -1,16 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
-<url><loc>https://docs.onlook.dev/robots.txt</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/contributing/developers</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/contributing/developers/appendix</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/contributing/developers/architecture</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/contributing/developers/running-locally</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/faq</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/getting-started/core-features</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/getting-started/first-project</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/getting-started/ui-overview</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/migrations/electron-to-web-migration</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/tutorials/figma-to-onlook</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://docs.onlook.dev/tutorials/importing-templates</loc><lastmod>2025-08-08T18:32:33.879Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/robots.txt</loc><lastmod>2025-08-13T18:21:43.820Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/developers</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/developers/appendix</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/developers/architecture</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/developers/running-locally</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/faq</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/getting-started/core-features</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/getting-started/first-project</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/getting-started/ui-overview</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/migrations/electron-to-web-migration</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/tutorials/figma-to-onlook</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://docs.onlook.dev/tutorials/importing-templates</loc><lastmod>2025-08-13T18:21:43.823Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
 </urlset>
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
@@ -2,11 +2,18 @@
 @import 'fumadocs-ui/css/black.css';
 @import 'fumadocs-ui/css/preset.css';
 
+:root {
+  --color-fd-background: linear-gradient(135deg, #ffffff 0%, #ffffff 60%, #ffecec 100%);
+}
+.dark {
+  --color-fd-background: linear-gradient(135deg, #1a0000 0%, #000000 60%, #1a0000 100%);
+}
+
 html,
 body {
   overscroll-behavior: none;
   font-weight: 350;
-  background: linear-gradient(135deg, #141414 0%, #000000 50%, #000000 100%);
+  background: var(--color-fd-background);
   min-height: 100vh;
 }
 
@@ -27,11 +34,6 @@ h6:hover [data-hash-link] {
   cursor: pointer;
 }
 
-/* Hide subnav in production */
-#nd-subnav {
-    display: none;
-}
-
 /* Make prose headers not bold */
 .prose h1,
 .prose h2,
@@ -40,4 +42,4 @@ h6:hover [data-hash-link] {
 .prose h5,
 .prose h6 {
     font-weight: 500;
-}
+}
diff --git a/docs/src/app/layout.tsx b/docs/src/app/layout.tsx
@@ -1,5 +1,3 @@
-// Global styles
-import '@onlook/ui/globals.css';
 import './global.css';
 
 import { baseOptions } from '@/app/layout.config';
diff --git a/package.json b/package.json
@@ -24,9 +24,10 @@
         "docs": "bun --filter @onlook/docs dev",
         "backend:start": "bun --filter @onlook/backend start",
         "db:gen": "bun --filter @onlook/db db:gen",
-        "db:push": "bun --filter @onlook/db db:push",
-        "db:seed": "bun --filter @onlook/db db:seed",
-        "db:migrate": "bun --filter @onlook/db db:migrate",
+        "db:push": "cd packages/db && bun db:push",
+        "db:seed": "cd packages/db && bun db:seed",
+        "db:migrate": "cd packages/db && bun db:migrate",
+        "db:reset": "cd apps/backend && bun run reset",
         "format": "bun --filter '*' format",
         "lint": "bun --filter @onlook/web-client lint",
         "typecheck": "bun --elide-lines 0 --filter '*' typecheck",

Original file line number	Diff line number	Diff line change
`@@ -123,4 +123,4 @@ You can report bugs or request features on our [GitHub Issues page](https://gith`
`123`	`123`
`124`	`124`	`### How can I contribute to Onlook?`
`125`	`125`
`126`		`-Check out our [Contributing Guide](/contributing/developers) for information on how to contribute to Onlook.`
	`126`	`+Check out our [Contributing Guide](/developers) for information on how to contribute to Onlook.`