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()orfetchSidebar()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=production2. ❌ 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.tsxor 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.jspoint 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 intailwind.config.js. - Ensure the
darkclass 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/rehypeplugins, 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, orrehype-*are installed and inpackage.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
/publicfolder. - Use absolute paths like
/logo.svg, not./logo.svg.
Still Stuck?
- 🧪 Try restarting your dev server:
npm run dev - 🧼 Clear
.nextcache: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?
It was helpful
It was not helpful
I have a feedback