Made in DeveloperHub
Linking to pages (cross-referencing) is very powerful. It ensures that the pages hierarchy is always correct by automatically updated references as your documentation scales and changes. Linking to pages applies between pages in one version.
You can link to a page or to an API reference - everything written here applies for both.
Why to Link Pages?
When a page is linked inside a version:
The link will follow the page regardless of changes in documentation or page name.
On cloning versions, the link will follow the page in the new version.
You will be notified if a link breaks because a page was deleted.
How to Link Pages?
To create a link between pages, type @ to open the pages selector.
A list of all pages under the version will be listed for you to choose from. Search through the list by typing down the page name or slug. To select a page, click on its name in the list. If you are selecting an API Reference, then you'll find the title of the API Reference.
Alternatively, you can also link to an internal page by highlighting text and clicking on the link icon.
External links in the editor show with a top-right pointing arrow so you can tell them apart from page links. The arrow will not show in live mode.
Changing Link Title/Specifying Heading
After selecting the page, you will be prompted to optionally link to a specific heading if you selected a page, or link to a specific operation if you selected an API reference.
If you want to jump to a certain heading in a page, you can specify it. Start typing to find a heading in the page you selected, or click on the arrow to view all. Leaving Heading empty will default to jumping to the title of the page. The same goes for API references, where you can select a specific operation to jump to.
Once you select a heading/operation, its URL fragment will appear. A fragment is the part of the link that is after the hash sign # . For example, the link https://pied-piper.developerhub.io/v1.0/middle-compression/intro#how-to-use has the fragment how-to-use.
Fragment can only contain alphanumeric characters and hyphens.
We do not monitor changes to the headings/operations. If a heading/operation is changed, then you should create the link again.
To open a link's target while editing, click the link to bring up its toolbar, then use the open control or hit ⇧ while clicking on it. A modifier-click (such as ⌘ / ⌃ or ⇧) opens it in a new tab.
Analyse Links
Analysing links helps you understand the links that are:
Broken because the linked page/reference was deleted.
Leading to an unpublished page/reference from a published page.
Have an internal DeveloperHub link, instead of a link to your published docs.
Listing Broken Links
If a page contains links with issues, a badge will appear next to the page actions in the navigation bar. Link analysis runs automatically every time a page loads.
Links with issues are also underlined in the editor:
Orange underline indicates a warning or lower-severity issue.
Red underline indicates a higher-severity issue (for example, a broken or unreachable link).
Analyse Links for Entire Version
You can analyse all links in a version at once by:
Open Manage Versions (version menu → settings cog).
Select the version.
In the Lifecycle card, click Check broken links.
View Broken Links in a Page
To view all the links analysis in a page, either click on the notification under the page title or:
From the right sidebar, open Page Info .
Open the Links tab and review the broken links and issues under Link issues.
Every broken link will show you the title and the heading (if any) that it had before breaking. The list also shows the current text of the link so you are able to find it and fix it.
Under Link issues, click an issue to view the link it refers to.
Broken page links lead to 404 Page.
Only internal links created by using Page Linking are examined for breaking. The monitoring tool will not examine or alert about external links leading to 404.
Broken Links Email
A bi-weekly email is sent to admins and publishers that lists all the broken links in the docs. An email is sent per project and a maximum of 3 emails is sent per user. The email subscription status can be changed from Account Settings.
Listing Linked Pages (Backlinks)
If you are planning to delete a page, or modify the page heavily, then you might want to know what other pages are depending on this page. To list all pages linking to the current page you are on:
From the right sidebar, open Page Info .
Open the Links tab. Linked pages load automatically.
Any linked pages are listed under Pages linked.
Page Permalinks
Permalinks are links that never change providing a reliable reference to a page.
To get a page permalink:
From the right sidebar, open Page Info .
Click the permalink button in the panel header.
The link will be copied to your clipboard.
Our permalinks have the following structure: https://<domain>/_permalink/<id>.
Permalinks are dependant on the custom domain used. If the custom domain changes, the permalink will not be valid anymore.