Insert Markdown Links into a Manuscript and Verify Their Targets

A useful Markdown hyperlink has three parts that must agree: the words a reader sees, the relative path stored in the manuscript, and the file that opens. If a novel is split into chapter files, calculate the path from the chapter that contains the link—not from the project folder and not from the target file.

Start at the chapter file

Suppose a manuscript is arranged like this:

manuscript/
├── chapters/
│   ├── C01.md
│   └── C02.md
└── refs/
    └── source-note.md

Both chapter files are one folder below manuscript. From either chapter, the route to the note is ../refs/source-note.md: go up once, enter refs, then open the file. A chapter at chapters/part1/C01.md would need ../../refs/source-note.md instead. That difference is why copying a link from one chapter to another can fail when the chapters are stored at different depths.

The Markdown form is [label](relative-path). A descriptive label such as “interview chronology” is more useful than “click here,” especially when several research notes appear in one paragraph.

A link inventory you can read at a glance

The small run behind this article inserted all three new links into chapters/C01.md. The C02 row below is a path-calculation example for a chapter at the same depth; it was not part of that run.

Do not treat “three good links exist” as proof that the manuscript is clean. Search the good path and the stale path separately. In this example, acceptance means three occurrences of ../refs/source-note.md and zero occurrences of ../refs/missing.md after the old link has been repaired.

Open, reopen, and then search

After inserting a link, save the chapter and reopen it. Check that the brackets and parentheses survived, then open the link and confirm the filename and content. Finally, search the project for the old path. This order catches two different mistakes: malformed Markdown in the edited chapter and a valid-looking path that points to the wrong file.

If the target is a web address, add a separate browser check. A local file test says nothing about an HTTP response, redirects, or a page that has disappeared.

What the Rune Studio run established

Rune Studio’s current Mac feature description says it can work with Markdown image and link references in txt, text, md, and markdown files, and rewrite relative references after files or folders are moved or renamed. In the bounded run used here, three labels were linked to ../refs/source-note.md. Reading the saved chapter back found three new paths and one deliberately stale ../refs/missing.md path.

That result covers the local chapter file only. It does not establish external URL availability, cloud synchronization, collaborative editing, or tracking outside the workspace. Because different move commands can have different scopes, try a move on a copy of the project before relying on it for a finished manuscript.

Finish with a destination check

The reliable rule is simple: write the label, calculate the path from the source chapter, open the destination, and search for stale paths. This makes a broken link a specific file problem instead of a vague manuscript problem.

For details about organizing Markdown manuscripts and reference files in the current Mac app, visit the Rune Studio website.