Links

Links serve as pathways through resources referenced in AsyncAPI's content, and their design directly impacts how users navigate and engage with it.

Text Links

Here are some ways to effectively design links when referencing sources in a tutorial, blog post, or making an update to AsyncAPI's documentation:

Be clear and concise: Make sure the link text accurately describes the destination or action, so users know what to expect when clicking.
Be descriptive: Using common phrases like "Click Here" or "Read More" makes it harder for users, especially those who use screen readers to navigate the web, to understand what will happen.
Be relevant: It's best to ensure that the link's text describes the source in a way that connects to the content's topic. This helps users gain a better understanding of the material they are reading.
Be unique: Avoid using the same text for sources' links. This helps screen reader users distinguish between different navigation options and prevent confusion for all readers.

Consider using the following tips to format links for files, images, and other forms of multimedia in AsyncAPI's content:

Use relative paths: This will make it easier for readers to quickly access the image or source embedded in the repository.
Use recent version files: Check that the assets used in the content are up-to-date. This ensures that readers get the correct information.
Use meaningful names for files: Make sure the file names for assets correspond to what they describe. This makes the tutorial, blog post, or documentation-related update more accessible, especially for users who use screen readers to navigate the site.

When referencing sources that will take users outside AsyncAPI, refer to the following tips:

Use absolute URLs: Always include the full URL, starting with https://, for external resources. This helps users understand where they are going and prevents confusion.
Let users know when a link goes to another website: Tell readers if clicking a link will take them away from the AsyncAPI site. This helps them know what to expect before they click.
Use link text that fits the sentence: Place links within sentences so the link text clearly tells users where the link goes. This helps readers understand what to expect and makes the content easier to follow.

When it comes to referring to other sections within the content being created for AsyncAPI, consider using the following methods:

Use relative URLs: When linking to other pages in the documentation, use easy-to-read paths that work no matter where the docs are moved or viewed. This makes it easier for users to navigate the content and ensures that the links remain functional.
Keep it consistent: Use the same style for links within the documentation so readers can easily find and navigate the content and know what to expect.
Consider using anchor links: For lengthy pages, use anchor links (links that point to specific headings or sections within the same page) to direct users to specific sections rather than forcing them to scroll through content.

For more information, visit the [AsyncAPI website](https://www.asyncapi.com).

![AsyncAPI Logo](../assets/asyncapi-logo.png)

Read the [AsyncAPI Specification](../specifications/latest).

For more details, visit the [AsyncAPI Blog](https://www.asyncapi.com/blog){:target="_blank" rel="noopener"}.

For more tips on creating effective links, consider consulting the following sources: