Skip to main content

Links

This page describes how to format links in documentation.

Grammatical structure​

When adding a link in a sentence, follow these best practices:

  • Write brief description to introduce the link.
  • Use the title or a description of the page rather than a generic phrase like "here" or "link."
  • Try to end the sentence with the link so that the reader understands the significance of the link. You can do this by starting the sentence with a phrase like "For more information" or "For details"

There are primarily two types of links that you can add to documentation: Markdown and Javadoc.

Markdown​

To create a link in Markdown, enclose the link text in square brackets, followed by the URL in parentheses.

important

Make sure that you include ./ at the beginning of a relative link to a page that exists in the same folder.

Examples​

  • Link to a page on the same site: [ScalarDB Overview](./overview.mdx)
  • Link to a page on an external site: [Contact us](https://www.scalar-labs.com/contact-us)
note

To create an anchor link, which is a link to a heading on the same page, you can add a number sign (#) followed with the heading ID. Any spaces in the heading must be replaced with hyphens (-).

For example:

  • Anchor to a heading on the same page: [Number of pods and Kubernetes worker nodes](#number-of-pods-and-kubernetes-worker-nodes)
  • Anchor to a heading on a different page on the same site: [Data-type mapping between ScalarDB and other databases](./schema-loader.mdx#data-type-mapping-between-scalardb-and-other-databases)
  • Anchor to a heading on a page on an external site: [Key types](https://developer.hashicorp.com/vault/docs/secrets/transit#key-types)

You can link to headings with custom IDs in the file by creating a standard link with a number sign (#) followed by the custom heading ID. These are commonly referred to as anchor links.

Javadoc​

In Docusaurus, links to Javadoc pages are dynamically generated by using a custom component. By dynamically creating versioned Javadoc links, we can:

  • Provide specific Java API package and class names directly, saving readers time from browsing the Javadoc site for the right link.
  • Avoid updating Javadoc links manually when a new patch version is released.
info

The latest patch version for each set of versioned documentation is based on the docs.lastVersion.versions.MAJOR_VERSION.MINOR_VERSION.className option in the Docusaurus configuration file (docusaurus.config.js).

To take advantage of the component for dynamically creating links to the latest patch version of the Javadoc page for the version of docs, do the following:

  1. Add the following import below the title:

    import JavadocLink from '/src/theme/JavadocLink.js';

  2. Add the following where you want to add the link to the Javadoc, replacing the contents in the angle brackets as described:

    <JavadocLink packageName="<PACKAGE_NAME>" path="<PATH>" className="<CLASS_NAME>" />

The following is a breakdown of the syntax elements in the Javadoc link template above:

  • PACKAGE_NAME: The name of the package for which you want to link to the Javadoc page.
  • PATH: The path to the specific class or file within the package.
  • CLASS_NAME: The name of the Java class for which you want to generate a link.
note

For reference, the following is the standard Javadoc URL syntax:

https://javadoc.io/static/com.scalar-labs/<PACKAGE_NAME>/MAJOR.MINOR.PATCH/<PATH>/<CLASS_NAME>.html

Example​

To make a link to https://javadoc.io/static/com.scalar-labs/scalardl-common/3.10.0/com/scalar/dl/ledger/config/LedgerConfig.html, the Javadoc link in the document should look as follows:

<JavadocLink packageName="scalardl-common" path="com/scalar/dl/ledger/config" className="LedgerConfig" />