FAQ & Troubleshooting

Common questions and solutions to known issues.

Frequently Asked Questions

Can I use WPDocs without the plugin?

The theme loads but shows a message asking you to install WPDocs Core. The plugin is required for all documentation functionality — without it, there’s no custom post type or settings.

Does the Block Editor work?

Yes. WPDocs supports both the Classic Editor and Gutenberg. Content is rendered through Tailwind Typography (prose) for consistent, beautiful output regardless of which editor you use.

How many doc pages can I create?

Unlimited in both free and premium. The only free limitation is the sidebar section count (maximum 3 sections).

Can I use WPDocs on a Multisite network?

Yes. Network-activate the plugin and activate the theme per-site. Each sub-site gets its own independent documentation, sections, settings, and optional license.

Does dark mode work in the free version?

No. The dark mode toggle is premium-only. Free sites always use the light theme.

Where is my data stored?

Doc pages are standard WordPress posts (CPT: wpdocs_doc). Sections are taxonomy terms. Settings are in wp_options. All standard WordPress backup, migration, and export tools work normally.

Troubleshooting

Styles not loading / broken layout

Make sure the dist/ folder exists and contains compiled assets. Run npm run build before deploying. The file dist/.vite/manifest.json must exist for WordPress to find the CSS/JS files.

404 errors on documentation pages

Go to Settings → Permalinks and click Save Changes. This flushes WordPress rewrite rules. The /docs/ slug requires this after the plugin is first activated.

License activation fails

Common causes:

  • Server blocks outgoing HTTPS — check with your host
  • Wrong key format — must be WPDOCS-XXXX-XXXX-XXXX-XXXX
  • Domain limit reached — deactivate another site first
  • API server unreachable — try again in a few minutes

Search not showing results

Check that no caching plugin is caching admin-ajax.php responses. Also make sure the AJAX nonce is being generated (it’s added via wp_localize_script in the plugin).

Sidebar shows “max 3 sections” warning

You’re on the free version. Upgrade to premium for unlimited sidebar sections, plus dark mode, icons, versioning, and more.