04 Formatting links - harvardinformatics/informatics-website GitHub Wiki

For clarity and consistency, I have started formatting external and download links with icons. External links now also open in new tabs. Here is a summary of how to format these links.

External links are those to any page outside of our informatics.fas.harvard.edu domain. They are now indicated with an icon .

The MkDocs shortcut string (see Images and Icons) for this icon is :octicons-link-external-24:.

To get a MkDocs link to open in a new tab, add the following after it:

{:target="_blank"}

To put this all together, external links should always be formatted as follows:

[link text to appear on the page :octicons-link-external-24:](url){:target="_blank"}

Recall that some of our pages (e.g. the homepage, the Resources page) use HTML templates and are processed with Python when the site is built. Python understands anything in curly brackets in a string template as something that needs to be formatted. As such, including {:target="_blank"} will make the script break and the site unable to be built.

Instead, you must escape the curly brackets with an extra pair of curly brackets: {{:target="_blank"}}

So, when editing templates and including an external link, it should be formatted as:

[link text to appear on the page :octicons-link-external-24:](url){{:target="_blank"}}

In some instances (e.g. the Software page), lines are enclosed in HTML. In this case, the icon shortcut and Markdown syntax won't work. Instead, I have added a custom CSS class for the icon. To use this, links should be formatted as follows:

<a href="<url>" target="_blank">link text to appear on the page <span class="icon-external"></span></a>

Similarly, links that download content (e.g. workshop data) should be indicated with an icon

The MkDocs shortcut string (see Images and Icons) for this icon is :octicons-download-24:, and links should be written as:

[link text to appear on the page :octicons-download-24:](url)

{:target="_blank"} for a new tab should not be necessary for downloading data files, but may be necessary for pdfs or slides.

I have not implemented a custom CSS class for the download icon, but can whenever it is needed.

I have also occasionally used an icon for links that are internal but open in a new tab, and an icon for internal links on buttons, but these are mostly done as needed.