Skip to content

Catch and repair problems

Before you ship a page, you want to know it does not have a broken link, a footnote missing its definition, a definition that is no longer used, or a snippet that no longer resolves. Zensical Studio flags all of this the moment it happens, not just when you go looking for it.

Example project

This workflow uses the project in zensical-example-project.zip; the same diagnostics apply in any project.

Suppose the link in getting-started.md's "Next steps" section was broken. If you remove a character from the workspace-settings.md filename, Zensical Studio will show the now broken link both inline by highlighting the link and in the Problems panelProblems panelDiagnostics panelProblems tool window. The file will also be flagged as containing a problem in the ExplorerExplorerProject panelProject tool window.

Run the code actionRun the code actionToggle Code ActionsShow Context ActionsCtrl+.macOSCmd+.WindowsCtrl+.LinuxCtrl+. on the link to fix the problem immediately, without needing to look at the ExplorerExplorerProject panelProject tool window.

Bulk repairs

Say you pull changes from your project's Git repository and find that a colleague has moved files into a new subdirectory. They did so without using Zensical Studio, so the links did not get updated. If the number of files and of links to them is non-trivial, this could be a lot of manual work.

Fortunately, Zensical Studio allows you to fix problems automatically in more than one place:

Try it yourself

Because Zensical Studio will automatically change links when you move files, you will need to turn it off before doing this, then turn it back on. One option is to quit Visual Studio CodeCursorZedJetBrains IDEs, move the files, then start it again.

If you change a character in the link reference so that it does not fit the label in the definition, you see that two errors are logged in the Problems panelProblems panelDiagnostics panelProblems tool window, one for the link that does not have a definition anymore and one for the now orphaned definition. Another kind of error is to have two link definitions with the same label. Zensical Studio warns about this as well.

Run the code actionRun the code actionToggle Code ActionsShow Context ActionsCtrl+.macOSCmd+.WindowsCtrl+.LinuxCtrl+. on the orphaned definition and choose Remove unused reference definition to delete it, without leaving a stray blank line behind.

Duplicate anchors

A heading's generated anchor, an explicit ID from Add link target, and a content tab's anchor all share one namespace, so two of them can collide even when they come from different kinds of block. Say two headings on the page happen to produce the same slug, or you type an explicit ID by hand that collides with one already used elsewhere on the page.

Zensical Studio flags the second one as a duplicate, both inline and in the Problems panelProblems panelDiagnostics panelProblems tool window, and treats the first, by position in the file, as the one links actually reach. Only that first anchor gets a CodeLens, appears in navigation, and updates its incoming links when you rename it. The duplicate does none of this. Editing it changes nothing for whoever already linked to the name it collided with.

Broken footnotes

Say we introduce a typo in a footnote, so that the footnote and its definition no longer match. Zensical Studio underlines both the footnote and its now-orphaned definition. You can also see the errors in the Problems panel. Open the Problems panelOpen the Problems panelOpen the Diagnostics panelOpen the Problems tool windowCtrl+Shift+MmacOSCmd+Shift+MWindowsCtrl+Shift+MLinuxCtrl+Shift+M if it is not already open.

Run the code actionRun the code actionToggle Code ActionsShow Context ActionsCtrl+.macOSCmd+.WindowsCtrl+.LinuxCtrl+. on the orphaned definition and choose Remove unused footnote definition to delete it, without leaving a stray blank line behind.

Use the Problems panel to tidy up

Open the Problems panelOpen the Problems panelOpen the Diagnostics panelOpen the Problems tool windowCtrl+Shift+MmacOSCmd+Shift+MWindowsCtrl+Shift+MLinuxCtrl+Shift+M to see every diagnostic across a whole project. You can use filtering to narrow the view to just the problems in the page open in the active editor. Using this view makes it easier to go through any problems in your project than doing so manually, looking for underlined links.

This allows you to systematically fix all the problems in a project so that it builds without warnings and passes any CI checks you may have deployed.

Where to go next