Tips for linking to other Markdown files
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.)
There are two ways to add links: relative links and root links.
Relative 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”.
Reference links
Instead of using standard inline links, some writers like using reference links. Reference links use a second set of square brackets, inside which you place a label of your choosing to identify the link. Example:
I like using [Google] [1], [Yahoo] [2], and [Bing] [3] for searching.
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: https://www.bing.com/ "Microsoft Bing"
../this/that.md) as reference links; they will not resolve correctly. Use inline links for relative or root links.Root links
[Activity mapping](/docs/authoring-guide/using/activities/mapping.md)
-
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.
-
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.
-
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.
](help/)). Remember to start the root link with ](/docs/authoring-guide/ (or whatever the name of the first directory is in your repo).\) instead of forward slashes (/). Use forward slashes in your path.Deep links deep-links
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](audiences.md#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](audiences.md#creating-audience-pocs)
Open in new tab 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.
Example:
[See What's new](https://experienceleague.adobe.com/docs/authoring-guide/using/whats-new.html?lang=en){target="_blank"}
Rendered:
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.
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.
Converting URLs to hyperlinks
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:
https://www.adobe.com
<https://www.adobe.com>
Rendered:
https://www.adobe.com
Creating links using the Markdown Shortcuts extension for Visual Studio Code
Ensure that you have the Markdown Shortcuts extension installed. This extension makes creating fool-proof links in Visual Studio Code relatively easy.
- Select the content that you want to be the text for your link (for example, Release Notes).
- Press Cmd+p (or CTRL+p), then search for the destination file you want to link to.
- Open the destination file.
- Right-click the destination filename in the left navigation menu, then click Copy Relative Path.
- Close the destination file to return focus to the original file (your link text remains selected).
- Right-click the selected text, then click Toggle Hyperlink to display a search field at the top of your window.
- 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.
Checking for broken external links
See viewing broken external links.
Excluding URLs from being checked
See excluding URLs from being checked.