Menu

Troubleshooting

Ran into an issue? Don’t worry—this section outlines common problems you might encounter while using Docsta and how to resolve them quickly. Whether it's build errors, blank pages, or missing content, we've got you covered.

1. ❌ Sidebar or Pages Not Showing

Symptom: The sidebar is empty or documentation pages don’t render content.

Fix:

  • Make sure your Sanity project has published documents with valid slugs.
  • Check that your fetchDocs() or fetchSidebar() functions are correctly querying content.
  • Verify that your environment variables (NEXT_PUBLIC_SANITY_PROJECT_ID, etc.) are set.
# .env.local
NEXT_PUBLIC_SANITY_PROJECT_ID=your_id
NEXT_PUBLIC_SANITY_DATASET=production
2. ❌ undefined or null Content in Docs

Symptom: Page loads but content area is blank or throws an error.

Fix:

  • Check if the slug passed into the fetch function matches your Sanity slug field.
  • Confirm that you're publishing content in Sanity Studio (not just saving as drafts).
  • Add fallback logic in your page.tsx or component:
if (!doc) return <div>Documentation not found.</div>
3. ❌ Tailwind Classes Not Working

Symptom: Your styles aren’t applying as expected.

Fix:

  • Make sure all paths in tailwind.config.js point to the correct files:
content: [
'./app/**/*.{js,ts,jsx,tsx}',
'./pages/**/*.{js,ts,jsx,tsx}',
'./components/**/*.{js,ts,jsx,tsx}',
]
  • Restart your dev server after updating the config.

4. ❌ Dark Mode Not Toggling

Symptom: Theme toggle button doesn’t switch modes.

Fix:

  • Confirm that darkMode: 'class' is set in tailwind.config.js.
  • Ensure the dark class is being toggled on the <html> element.
  • Check if you're persisting the theme preference in localStorage.

5. ❌ MDX/Markdown Not Rendering Properly

Symptom: Content appears unstyled or JSX inside MDX is broken.

Fix:

  • Verify that your MDX loader (e.g., next-mdx-remote, mdx-bundler) is correctly configured.
  • If using remark/rehype plugins, check that they’re not throwing parsing errors.
  • Wrap content in a styled container like prose:
<div className="prose dark:prose-invert">
<MDXRemote {...mdxSource} />
</div>
6. ❌ Build Fails on Deployment (e.g., Vercel/Netlify)

Symptom: Everything works locally, but the site fails on deploy.

Fix:

  • Ensure all environment variables are added in your deployment dashboard (e.g., Vercel Settings).
  • Double-check that dependencies like shiki, sanity, or rehype-* are installed and in package.json.
  • If using Sanity, make sure CORS settings allow access from your deployment domain.

7. ❌ Fonts or Images Not Loading

Symptom: Fonts aren’t rendering, or images return 404 errors.

Fix:

  • Check that external fonts are correctly imported (via CSS or Next.js fonts).
  • Ensure static assets are inside the /public folder.
  • Use absolute paths like /logo.svg, not ./logo.svg.

Still Stuck?

  • 🧪 Try restarting your dev server: npm run dev
  • 🧼 Clear .next cache: rm -rf .next
  • 🔍 Open DevTools → Console & Network tab for hidden errors
  • 🙋‍♂️ Ask for help on GitHub Discussions or Issues (if using an open-source version)

Troubles don’t last—good docs do. With the right tools and these fixes, you’ll be back to building clean documentation in no time.

👉 Next Up: Customize your content structure or integrate search for a better UX.

What did you think of this content?

like-icon

It was helpful

dislike-icon

It was not helpful

feedback-icon

I have a feedback