@dgarcia360 a bit of reference, please.
how do I mark an external link?
will this automatically mark all links which are outside of our domain or do I need to do something?

Sphinx allows defining different types of links using directives:

• External links: Link sources outside the docs project. These kinds of links can be defined for example as`anchor text <url>`__. Sphinx tags external links with the CSS class .external, making it possible to add a custom icon after them. Note that this solution does not detect the domain name used, so if you opt to add an internal link as external like in `anchor text <https://docs.scylladb.com/some-doc>`__, Sphinx will treat the link as external showing the icon.

• Internal links: Link to other sections within the same page :ref:`anchor text<reference>` or other project pages :doc:`anchor text<path>`. We are not showing icons next to them.

• Download links: Link to files that can be downloaded. These kinds of links are defined as:download:`anchor text<path>`. Sphinx tags download links with the CSS class .download, making it possible to add a custom icon after them. I have also added some custom style to make them look like regular links.

The solution automatically adds the icons based on the directive used, there is no need to do anything extra.

@dgarcia360 best practice is adding an example to the source/examples/index.rst page as part of the PR for example:

The following

Examples
========

Link Format Examples
--------------------

* This is an example of an `External Link <https://docs.scylladb.com/some-doc>`_ - please review
* This is an example of an `Internal Link  <./index>`_  - please review
* This is an example of an :doc:`Internal Doc<./index>` - please review
* This is an example of an :download:`download <./index.rst>`  - please review

generate

I try to push this to the PR, but I guess I do not have permission to push into your fork.

one more thing I want to add
on external links can they please open in a new tab? this will prevent users from getting derailed and lost from our docs site.

@tzach Added the example with some modifications to source/examples/index.rst.

@lauranovich

Good idea 👍 Now external links are opened in new tabs. bcd896f