Skip to content

Keep links valid while editing

Documentation becomes difficult to change when one small edit has consequences somewhere else: a heading has incoming links, a reference is reused across pages, or a shared snippet supplies content to several documents. This guide shows how Zensical Studio keeps those connections visible and keeps them consistent for you.

Example project

This workflow uses the project in acme-example-project.zip; it takes about five minutes to follow along. You can also use your own project to make similar changes.

The following video shows all the steps in one continuous shot:

a continuous shot video of the changes outlined on this page

In workspace-settings.md, the "Next steps" section links to a heading in another page:

Hold Cmd/Ctrl and click the link, or place the cursor on it and use Go to DefinitionF12. Zensical Studio opens automations.md at the heading that owns #route-conversations-automatically.

Navigate via links

This is the first useful habit: follow a connection instead of searching for the file and then searching again for the target. It also works when the target is a reference definition, footnote, tab, explicit ID, or a selected section of reusable content.

Rename the definition

Rename the heading by just editing it or by using Rename SymbolRename SymbolRenameRenameF2. Zensical Studio shows you that the heading has been edited and the file needs to be saved. Once you do this, Zensical Studio changes the definition and updates the incoming links in files across your project.

The link in workspace-settings.md now follows the new generated anchor. Instead of having to manually edit links, you can simply rename the thing that owns the anchor. Zensical Studio recomputes the anchor and updates incoming links when you save the file.

Make a long-lived anchor explicit

Generated anchors are convenient, but some sections may need more stable public URLs. Open the code actioncode actioncode actioncontext action menu on the heading and choose Make anchor explicit:

The current generated slug becomes an authored ID.

The anchor is a normal workspace symbol. Before it was computed from the heading, now it is explicitly defined. Either way, links complete against it, navigation finds it, and Rename SymbolRename SymbolRenameRename or a saved edit updates the incoming links. Concise anchors are useful for headings that are linked from release notes, blog posts, or external documentation.

Move the page

Move automations.md into a new directory advanced/ using the ExplorerExplorerProject panelProject tool window.

The link from workspace-settings.md is updated to the new relative path.

Links and snippet paths inside the moved file are rebased too, so they continue to point at the same targets from their new location: automations.md's own "roles and permissions" link, originally workspace-settings.md, becomes ../workspace-settings.md automatically.

Use normal editor functions

This is intentionally a file-explorer workflow. Use the file operation you would normally use, then let Zensical Studio update the Markdown relationships rather than repairing them afterwards.

Where to go next