Linking tips

Linking to other Markdown files can be tricky in Markdown. When you add links to other Markdown files, remember to use the Git structure. (The structure plays no part in linking.)


There are two ways to add links: relative links and root links.

[Activity mapping](activities/

When you add a relative link, you need to account for the locations of both the source file and the target file.

In this example, we’re backing up two directories to get to the “activities” directory.

Relative links are great for linking to files on the same level. Just use the [link]( format.

If a link is in a different location, relative links can be tricky. Instead of figuring out how many levels to jump back to, an easier way is to add a “root link”.

[Activity mapping](/docs/authoring-guide-exl/using/activities/

  1. In Visual Studio Code, open the repo at the root level (such as analytics.en, not “admin”).

    If you open a subdirectory, copying the relative path doesn’t always work properly.

  2. Open the target file, and right-click the target file in the left explorer pane or in the file tab, and then choose Copy Relative Path.

    copy relative path

  3. When creating the link, type a forward slash ( / ), and then paste the pathname.

The opening slash takes you back to the root level (your repo). The rest of the link is determined by the directory structure. It’s usually in the format /help/<directory>/<subdirectory><filename>.md.


A common mistake is to omit the opening slash / in the root link (such as ](help/)). Remember to start the root link with ](/docs/authoring-guide-exl/ (or whatever the name of the first directory is in your repo).


When you copy the relative path in Windows, the pathname might include backslashes (\) instead of forward slashes (/). Use forward slashes in your path.

(Windows) Here’s a useful VSC copy relative path add-on.

We used to require all headings used for deep links to have explicit anchor IDs. However, explicit anchor IDs are no longer required. If a heading ID is not specified, you can derive the heading ID for the deep link by making the heading lowercase and hyphenated.

Example 1 - Heading anchor ID specified

## Creating audience POCs {#audience-pocs}

To link to this heading within the same page, use the specified heading ID (audience-pocs) as the link:

See [Creating audience POCs](#audience-pocs)

To link to this heading from a different article in the repo, add the specified heading ID suffix to the end of the link:

See [Audiences: Creating audience POCs](

Example 2 - Heading anchor ID not specified

## Creating audience POCs

To link to a heading that does not have an explicit anchor ID, derive the “slugified” heading ID value by making the heading lowercase and hyphenated: creating-audience-pocs.

See [Audiences: Creating audience POCs](

Open in new tab

If you want a link to open a new tab, such as when you jump to a different guide, use the {target="_blank"} property in the link.


[See What's new](/docs/authoring-guide-exl/using/whats-new.html?lang=en){target="_blank"}


See What’s new

Linking to other solutions

Use absolute links ( when linking to any article that is outside the current repo.

When a user clicks an absolute link, the article opens in a new tab.

Linking to the same file multiple times in a TOC

Do not add the same file as a relative link multiple times in a TOC or multiple TOCs. Doing so causes display and search problems.

If you want an article to appear in multiple TOCs, add a relative link to the TOC in the primary location, and add absolute (https://) links in the other TOCs.

If you add a URL directly to text, it is not converted to a link automatically. If you want a URL to appear as a link, add < > syntax. Examples:



Ensure that you have the Markdown Shortcuts extension installed. This extension makes creating fool-proof links in Visual Studio Code relatively easy.

  1. Select the content that you want to be the text for your link (for example, Release Notes).
  2. Press Cmd+p (or CTRL+p), then search for the destination file you want to link to.
  3. Open the destination file.
  4. Right-click the destination filename in the left navigation menu, then click Copy Relative Path.
  5. Close the destination file to return focus to the original file (your link text remains selected).
  6. Right-click the selected text, then click Toggle Hyperlink to display a search field at the top of your window.
  7. Type a forward slash to make the link a root link (described above), paste the relative link, then press Enter.

It is always good practice to press Cmd+click (or Ctrl+click) with your cursor on the link to see if it resolves.

This procedure also works for images if you select Toggle Image in Step 6.

See viewing broken external links.

Excluding URLs from being checked

See excluding URLs from being checked.

On this page