Troubleshooting¶

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.

If the output view is not visible, use Open the Command PaletteOpen the Command PaletteOpen the command paletteOpen Find ActionCtrl+Shift+PmacOSCmd+Shift+PWindowsCtrl+Shift+PLinuxCtrl+Shift+P, run View: Toggle Output, then choose Zensical Studio from the output channel dropdown.

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 the Make anchor explicit action 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 a beta 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.

See beta phase feedback for what kind of feedback helps most.