Troubleshooting

Docs pages return a 404

Go to Settings > Permalinks and click Save Changes — no actual changes are needed, just saving flushes the rewrite rules. This is the most common cause of broken /docs/ URLs after activating the theme or plugin.

Doku Core will not install or activate

The installer lives at Appearance > Install Plugins, and the required-plugin notice links straight to it.

WordPress asks for FTP or SSH credentials. This is a filesystem-permissions issue on your host, not a theme problem — WordPress cannot write to wp-content/plugins/ directly. Ask your host to correct ownership of the WordPress directories, or add your credentials to wp-config.php. The same prompt would appear installing any plugin.
The notice will not go away. While Doku Core is missing, inactive or out of date, the notice cannot be dismissed for good, because the theme displays no documentation at all without it: its × hides it only until the next page. Once Doku Core is active and current, the notice only recommends One Click Demo Import, and then it carries a Dismiss this notice link that hides it permanently.
“Installed But Not Activated”. The plugin files are present but inactive — use the Activate link in that row, or activate Doku Core from the normal Plugins screen.
Already have an older Doku Core? If its version is below the one the theme requires, the installer offers an update instead of an install. Updating is safe: your documentation lives in the database, not in the plugin folder.

Sidebar or navigation is missing

Confirm Doku Core is active under Plugins. Without it the doc post type is not registered and the sidebar has nothing to display.
Confirm the doc is published and has a category. The automatic tree lists published docs only, and once any category exists, a doc without one is left out.
If a Docs Sidebar menu is assigned under Appearance > Menus, the sidebar shows that menu instead of the automatic tree, so a doc missing from the menu is missing from the sidebar. Add it to the menu, or unassign the menu to go back to the automatic tree.
On a post or a blog listing, the left column is the blog’s category list, not the documentation tree; on a page it holds the Page Left Column widgets, and only while that area has widgets and Show the left column on pages is on. See Pages, Posts, and the Front Page.

Header links are missing. Those come from a separate menu location — assign one to Primary Navigation. If they are missing only on a phone or tablet, open the ☰ drawer: the header menu is hidden below 1101px and repeated there.

A dropdown submenu does not appear. Three levels are rendered; anything nested deeper is dropped. Check the item’s indentation in Appearance > Menus. If a parent shows no chevron, the theme has decided it has nothing to open — it is either at the deepest level, or its children are nested past it. A column heading inside a mega panel carries no chevron either, and that one is deliberate: a column is open for as long as the panel is. The same goes for a section heading in the Docs Sidebar menu — its group never collapses.

Every section in the ☰ drawer is expanded and will not collapse. The drawer deliberately renders everything expanded when its JavaScript cannot run, so no link is ever unreachable. If that happens with JavaScript working, a caching or optimization plugin is almost certainly deferring, moving or stripping the small inline script in the page <head>. Exclude the theme’s inline scripts from JS deferral and “combine/move scripts to footer” options — the same script sets your color scheme before the page paints, so you may also notice a flash of the wrong theme on load.

Search returns no results

First check what the search panel is actually saying — each message means something different:

Message	Meaning
“Loading search index…”	The index is still downloading. Not an error; it clears on its own.
“Still indexing… 2 of 5”	A large site loading in chunks. Results already shown are real, but more are coming.
“Some results may be missing…”	A chunk failed to download. Reload the page; if it persists, check the console and your server’s error log.
“Search is unavailable right now.”	The index could not be fetched at all — see the steps below.
“No results for …”	The index loaded completely and genuinely contains no match.

If you are getting a genuine “No results” for content you know exists:

Re-save any doc post. The index cache is cleared immediately on save, delete, and category/version/product term changes.
Open the browser console (F12 → Console) and check for JavaScript errors — a caching or optimization plugin may be deferring or concatenating the FlexSearch script. Exclude flexsearch from JS deferral in your caching plugin settings.
Verify the Doku Core plugin is active; the REST endpoint that builds the index is registered there.
Confirm the post is published. Drafts, private and scheduled posts are never indexed.
If a security plugin or firewall blocks unauthenticated REST requests, allow doku/v1/search-index. It only ever returns already-public content.

Search results are missing on a large site

If the search field works but only ever finds docs from part of your documentation, the index is likely being truncated in transit. Doku fetches it in chunks and relies on the X-WP-TotalPages response header to know how many to request; some aggressive reverse proxies and CDNs strip custom headers, which makes a multi-chunk index look like a single-chunk one.

Confirm it in F12 → Network: request /wp-json/doku/v1/search-index directly and check the response headers. If X-WP-TotalPages is absent, allow it through at the proxy or CDN.

Markdown import issues

If an import produces unexpected output — missing blocks, garbled text, or a blank post — check the source file before re-importing. A couple of tools that can help:

A Markdown linter — catches structural errors such as unclosed fenced code blocks, table rows with mismatched column counts, and list indentation inconsistencies. For example: markdownlint (web) or markdownlint-cli (command line). Exception: if you split files At each H1 heading on import, ignore the “Multiple top-level headings in the same document” warning — a file with multiple H1s is intentional in that workflow.
A Markdown preview tool — renders the source so you can spot syntax the importer is likely to struggle with. For example: Babelmark 3 compares the same snippet across many parsers side by side, which is useful for pinpointing whether an issue is ambiguous syntax or a quirk of Doku’s custom parser.

One additional cause: if a tag in your source has disappeared from the imported post, wp_kses_post likely stripped it on import. Tags outside the WordPress post-content allowlist — <script>, <iframe>, inline event handlers like onclick, and similar — are removed for safety. Wrap them in a Custom HTML block in the editor after import if you need them.

Blocks show a “Block contains unexpected or invalid content” error

This usually means Doku Core was deactivated after the blocks were created, or the block markup was hand-edited and is now invalid.

Verify Doku Core is active.
If the error persists, use the block’s Attempt Block Recovery option — note that recovery may discard content it cannot parse.

Syntax highlighting not applied after import

The importer runs Shiki highlighting as a background REST request after the results table appears. If you closed the page before the “Done” status message appeared, highlighting was not saved.

To recover: open the affected post in the block editor and re-save it. Alternatively, re-import the file (use Overwrite existing post to avoid creating a duplicate) and wait for the “Done” message before closing the page.

Heading anchor links don’t copy

Browsers only expose the clipboard API on secure origins. On a site served over plain http://, Doku falls back to an older copy method, which some browsers block unless the click is treated as a direct user action.

If copying does nothing, serve the site over HTTPS. The anchor stays a normal link either way, so readers can always right-click it and choose Copy link address.

Sidebar sections collapse when I move to another page

This is deliberate. Each page opens the section it belongs to and collapses the others, so the sidebar always shows the reader where they are rather than a trail of everywhere they have been. Sections opened by hand stay open until the reader navigates away.

Section headings — the top-level # items described under Sidebar Navigation — are the exception: their groups are always visible and never collapse.

If the section holding the current page is not opening, the page is probably not in the menu: only items in the assigned Docs Sidebar menu can be marked. In the automatic category tree, check that the page and its parent doc share a category — a doc whose parent sits in another category is listed at the top of its own group instead. See Sidebar Navigation.