LinkORB Engineering

Standards for links in [#technical-documentation]

This guide explains how to embed internal and external hyperlinks (commonly called links) and provides linking best practices.

Most technical documentation at LinkORB is written in Markdown. Markdown’s standard format for writing links is:

  • [link text](URL)

The link text is displayed in the output, while the URL is the URL that the link targets. For example:

  • [Google](https://www.google.com/)

Two types of links can be implemented while writing in Markdown: internal and external links.

Internal links point to other files within the same repository. These links should be “relative” links that begin with a slash. For example:

  • [Example Guide](/topics/example-guide)

In the case of some repositories like astro-engineering, a relative link targets a file relative to the root of the src/pages folder and excludes src/pages and the .md file extension from the link. This means if the src folder looks like the following:

/
├── src/                                      # Astro site source (code + content)
│   └── pages/
│       └── about/
│       └── blog/
│           └── file-in-same-folder.md        # Contains a link to example-blog.md
│           └── example-blog.md               # File targetted by both links
│       └── topics/
│           └── file-in-different-folder.md   # Contains a link to example-blog.md

The relative link to example-guide.md is written as [Example Guide](/blog/example-guide) no matter where the file that contains the link is located within the src/pages folder. For example, within the folder structure shown previously, links within file-in-same-folder.md and file-in-different-folder.md use the same URL to target example-blog.md.

Many of LinkORB’s repositories, mainly if they are open-source, do not have a src/pages folder. Instead, long-form documentation is stored off the project root in a docs folder. In this case, a URL should point to a target file relative to the file containing the link.

An external link targets a website outside the repository and starts with https://. For example:

  • [GitHub](https://github.com/)

Format links inside alerts using the standard Markdown syntax for links. For example:

```
:::info
Ask any senior software development team member for access to the [GitHub repository](https://github.com/).
:::
```

Page section links

Link URLs to different sections in the same document are written starting with a hash # followed by the id of the heading you wish to ‘link to.’ For example, if you inspect the HTML in the browser, you will see each heading has a unique id:

  • <h1 id=“heading-1”>
  • <h2 id=“heading-2”>

The following example links to a section called Formatting Markdown links that has an id of formatting-markdown-links:

  • [Formatting Markdown links](#formatting-markdown-links)

The code above displays on the page as:

Try clicking it! 😀

To copy the heading id, click the link to the heading in the table of contents at the top of the file and copy the updated URL containing the hash value from your browser’s address bar.

Best practices

Avoid non-descriptive link text

Rather than write non-descriptive link text like:

For more information on vocabularies, read more here.

Or, a provide link whose URL is also the link text:

For more information, read the following guide: https://vale.sh/.

Instead, provide descriptive link text like:

For more information on vocabularies, see the Vale Vocabularies guide.

It’s crucial that you do not link to sensitive information. For example, avoid linking to private repositories or internal hosting/sharing platforms. Instead, name the repositories or platforms without linking to them.

About Technical Documentation
  • Name: Technical Documentation (#technical-documentation)