Skip to content

Quickstart

Open a project

Zensical Studio automatically activates inside a project that has a zensical.toml or mkdocs.yml file at its root, so open the folder that contains your configuration file.

You can create one with Zensical's create your site instructions, or download and unpack acme-example-project.zip, then return here.

Opening a project

Open the root folder in your editor, the one that contains the configuration file (zensical.toml or mkdocs.yml). This is often the Git repository that contains your documentation source, site configuration, and assets. In repositories that combine code and documentation, the project root may be a subdirectory such as docs.

Choose File → Open Folder... and select the project root, or pass it as an argument when starting Visual Studio CodeCursorZedJetBrains IDEs from the command line: code /path/to/repository.

When you open the project root folder, Zensical Studio reads your configuration and starts validating Markdown files.

Make your first edits

Create a new Markdown file in your project and try the examples below. You can copy the Markdown in the code blocks, but for some of them it's worth typing them in by hand to feel the editing support as it happens.

shows basic syntax highlighting, support for blocks that require indentation, using code completion to create a link to a heading, renaming the heading

# Zensical Studio notes

!!! tip "Links"

    Zensical Studio

    1. provides link target completions
    1. helps keep existing links **valid**

    For more information, see the [links section](#links).

## Links

Zensical Studio provides explicit support for creating links and for keeping them valid:

  1. helps you create links with link target completions,
  2. lets you turn inline links into link references, just press Ctrl+.macOSCmd+.WindowsCtrl+.LinuxCtrl+. while on a link,
  3. and even updates links automatically when headings are edited.

The result is that you can edit your content without ever breaking a link again.

When you create Markdown block elements that require indentation, such as admonitions as in the video, or content tabs, Zensical Studio automatically applies the correct amount of indentation. It also applies syntax highlighting correctly within nested Markdown.

Zensical Studio's link intelligence does not stop there. You can follow links to their definitions as well as to their targets. What is more, Zensical Studio shows you how often a link target is referenced and allows you to reveal these references:

# Zensical Studio notes

!!! tip "Links"

    Zensical Studio

    1. provides link target completions
    2. helps keep existing links **valid**

    For more information, see the [links section].

 ## Link intelligence

[links section]: #link-intelligence

## Summary

[Link intelligence](#link-intelligence) is one of the highlight features!

Note how the folded admonition block gets expanded again in the reference preview so that the link is visible. The video also shows the Extract to reference definition action again, which creates a second link definition. The auto-formatter is then invoked with Shift+Alt+FmacOSShift+Option+FWindowsShift+Alt+FLinuxCtrl+Shift+I and you can see that it collects all link definitions at the bottom of the file.

All of this works the same way across files too, so you never need to remember which page holds a definition, especially useful once reusable content supplies it through a snippet.

Where to go next

We also suggest one of our demonstrations of concrete authoring tasks before exploring the rest of the documentation: