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 TOC.md structure plays no part in linking.)

TIP

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

[Activity mapping](activities/mapping.md)

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](file.md) 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/mapping.md)

  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.

NOTE

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).

NOTE

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.

To link to a heading within an article, the target heading must have an explicit heading ID (also called an “anchor ID”). Example:

## Creating audience segments {#creating-audience-segments}

To link to this heading within the same page, use the heading ID as the link:

See [Creating audience segments](#creating-audience-segments)

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

See [Audiences: Creating audience segments](audiences.md#creating-audience-segments)

Linking to other solutions

Use absolute links (https://experienceleague.adobe.com...) 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. After cutover, adding multiple relative links to the same file in TOC files will cause validation to fail.

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.

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.

On this page