Troubleshooting¶

Study the logs¶

Start with the Zensical Studio output view in Visual Studio CodeCursorZedJetBrains IDEs. On startup, it reports the project configuration Zensical Studio found, its documentation roots, and the initial indexing result, including how many files it found, a quick way to tell if it picked up everything you expected. It also shows the Zensical Studio version you're running, useful when reporting an issue.

Open the Command PaletteOpen the Command PaletteOpen the command paletteOpen Find ActionCtrl+Shift+PmacOSCmd+Shift+PWindowsCtrl+Shift+PLinuxCtrl+Shift+P and run "Zensical Studio: Show LogsShow logsShow logsShow logs" to jump straight to the output view. You can also get there by running View: Toggle Output and choosing Zensical Studio from the output channel dropdown.

Restart the server¶

If the output of Zensical Studio seems wrong or if it seems to be stuck, you might want to try to restart the server. Open the Command PaletteOpen the Command PaletteOpen the command paletteOpen Find ActionCtrl+Shift+PmacOSCmd+Shift+PWindowsCtrl+Shift+PLinuxCtrl+Shift+P and run "Zensical Studio: Restart ServerRestart the serverRestart the serverRestart the server".

Zensical Studio is not active for a Markdown file¶

Check that the workspace contains zensical.toml or mkdocs.yml, then check that the file is below the configured documentation or snippet roots. Files outside those roots intentionally keep normal Markdown support.

To edit a standalone file with Zensical Studio, select Python Markdown from Visual Studio CodeCursorZedJetBrains IDEs's language mode picker. For project-wide behavior, verify docs_dir and the configured snippet base paths. See Workspace settings.

A link or anchor does not resolve¶

Confirm that the destination is part of the same configured project and that the target is an addressable Markdown construct. Zensical Studio recognizes generated heading slugs, explicit IDs, raw HTML IDs, content tabs, and footnotes.

For a generated heading anchor, edit the heading and save, or use Run the code actionRun the code actionToggle Code ActionsShow Context ActionsCtrl+.macOSCmd+.WindowsCtrl+.LinuxCtrl+. on it and choose Add link target when the URL should stay stable independently of future wording changes.

A snippet cannot resolve¶

Check the configured snippet base paths, the authored relative path, and the section or line selector. Diagnostics point to the directive that needs correction. Cmd/Ctrl-click an include to check the source and selected region Zensical Studio resolved.

Remember that a reusable file can be included from more than one page. Relative links inside it are authored relative to that file, not rewritten for every including page.

Emoji or icons do not complete¶

Check that pymdownx.emoji is configured and that Zensical Studio can find the Python environment used by the project. Unknown shortcodes remain literal text rather than being treated as valid emoji or icons.

Preview differs from the built site¶

Preview is project-aware, but it does not reproduce arbitrary custom theme JavaScript, every plugin, or every runtime behavior. Use it for fast editing feedback, then run the normal site build when you need to verify custom runtime behavior or the final theme presentation.

Reporting an issue¶

Report it through the issue tracker for the Zensical Studio repository. Share the smallest useful reproduction: the relevant project configuration, the Markdown files involved, the editor action, expected behavior, actual behavior, and your Zensical Studio version. If the issue is that a reference does not connect correctly (for example, go to definition fails, a link target does not resolve, or a snippet include cannot find its source), include both where you used it and the definition or snippet path it should connect to. This is more useful than a screenshot alone.