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.

Install the server manually¶

The extension normally downloads the Zensical Studio server for you. If your organization restricts where executables can run, download it here and extract it into an approved directory.

Loading downloads...

Choose the archive for your operating system and processor. The SHA-256 values verify the downloaded archives, not the extracted executables. You can check an archive with shasum -a 256 <archive> on macOS, sha256sum <archive> on Linux, or Get-FileHash <archive> -Algorithm SHA256 in Windows PowerShell.

In Visual Studio Code or Cursor, set zensical.studio.path to the extracted executable's full path (zensical-studio.exe on Windows, zensical-studio on macOS and Linux), then run Zensical Studio: Restart Server.

For example, in your editor's settings JSON:

{
  "zensical.studio.path": "C:\\Tools\\Zensical\\zensical-studio.exe"
}

With a custom path, you install server updates manually. During the beta, Studio still needs an internet connection to obtain or renew its access token; an already cached, valid token allows up to seven days of offline use.

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 unless you exclude the project as described below.

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.

Limit indexed projects¶

If your workspace contains several sites, you can choose which ones Studio indexes. In Visual Studio Code or Cursor, add project-root patterns to .vscode/settings.json:

{
  "zensical.studio.projects.include": ["site-*"],
  "zensical.studio.projects.exclude": ["site-legacy"]
}

Studio matches these patterns against the directory containing each zensical.toml or mkdocs.yml, relative to the workspace folder, not against docs_dir. An empty include list selects all projects; exclude takes precedence when both match. You can omit include if you only want to skip specific sites.

Excluded sites remain in the file explorer, but Studio does not index their pages or report diagnostics for them. Changes to these settings take effect without restarting Studio. To exclude individual pages from an indexed site instead, use exclude_docs in that site's configuration.