Install Zensical Studio¶

Install Zensical Studio in Visual Studio Code and use the editor you already know for writing, validating, and navigating your documentation. We'll add support for other editors in the near future.

Install the extension¶

Open the Extensions viewOpen the Extensions viewOpen ExtensionsOpen the Plugins settingsCtrl+Shift+XmacOSCmd+Shift+XWindowsCtrl+Shift+XLinuxCtrl+Shift+X, search for Zensical Studio, and click Install.

You can also install from the command line:

code --install-extension zensical.zensical-studio

Zensical Studio automatically activates when a zensical.toml or mkdocs.yml file exists in the project. It automatically validates Python Markdown files in your project's docs_dir and other configured input directories.

Manual activation

If you want to use Zensical Studio for Markdown files even in projects that do not (yet) have a documentation project set up, you can manually associate it with Markdown files in .vscode/settings.json:

{
  "files.associations": {
    "*.md": "python-markdown"
  }
}

The reverse works too: if you manually switch a file's language mode away from Python Markdown, Zensical Studio leaves your choice alone instead of reasserting itself.

Open the Extensions viewOpen the Extensions viewOpen ExtensionsOpen the Plugins settingsCtrl+Shift+XmacOSCmd+Shift+XWindowsCtrl+Shift+XLinuxCtrl+Shift+X, search for Zensical Studio, and click Install.

Cursor maintains its own extension registry. If Zensical Studio does not appear in search results, check that the Extensions view is showing all available sources.

Open Zed → Extensions from the application menu, or run zed: extensions from the command palette Ctrl+Shift+PmacOSCmd+Shift+PWindowsCtrl+Shift+PLinuxCtrl+Shift+P. Search for Zensical Studio and click Install.

Zed extensions are installed globally and activate automatically for any project that contains a supported Zensical configuration.

Confirm it is active¶

After opening a Zensical project, check that:

The Python Markdown language is active when you open a Markdown file. You can see this in the status bar in the bottom right of the screen. If you do not see a status bar, you can turn it on in View → Appearance → Status Bar.
Markdown files show project-aware highlighting and diagnostics.

If the Python Markdown language is not activated or in case of any other problems, see troubleshooting.

What gets installed¶

The editor extension connects Visual Studio CodeCursorZedJetBrains IDEs to the Zensical Studio server that provides the project-aware editing support features. It is independent of the editor being used. It reads the project configuration and builds a workspace model. Based on this, it then provides Markdown syntax highlighting, formatting, diagnostics, completions, and code actions.

Instead of working with separate extensions that may or may not work well together, you get consistent feedback and authoring support. See Better by design for how this compares to a stack of individual Markdown extensions.

KaTeX and Mermaid are bundled into Zensical Studio instead of downloaded from a CDN, so they work offline too.

Workspace settings¶

Zensical Studio activates for a workspace containing either zensical.toml or mkdocs.yml. A workspace may contain more than one configured project; each keeps its own documentation roots and link or snippet resolution scope. This includes a project whose configuration file or documentation root lives inside a directory your .gitignore excludes. Studio still discovers and indexes it.

It reads:

Setting	Why Zensical Studio reads it
`docs_dir`	Identifies the documentation root and page namespace, and can point outside the configuration file's own folder, even at the workspace root, as long as it still resolves inside the workspace.
`pymdownx.snippets` base paths	Identifies reusable-content roots and provides snippet completion and resolution. The project root is the default.
`pymdownx.tabbed` slug settings	Computes tab anchors consistently with Python Markdown.
`pymdownx.emoji` and custom icon directories	Builds the emoji and icon catalog for completion and preview.
`exclude_docs`	Uses gitignore-style patterns to remove matching pages from the project entirely, keeping them out of diagnostics, completion, navigation, and link targets.

Many other configuration values only affect the final site build: theme behavior, templates, plugins, navigation presentation, deployment, and custom runtime JavaScript. Those remain the responsibility of Zensical or MkDocs; Zensical Studio uses its project model for editing tasks such as navigation, completion, validation, renaming, formatting, and preview instead.