doc/dev/plugins/external_links

This plugin adds small icons to external and mailto links, informing users the link will take them to a new site or open their email client.

Note: hibbitts-design/grav-plugin-external-links is the new master repository for this plugin (see getgrav/grav#2711). Thanks to @Sommerregen for originally developing this Plugin!

Table of Contents:

• About
• Installation and Updates
• Usage
  • Example
  • CSS Stylesheet Override
  • Twig Filter
• Contributing
• License

About

External Links is a high-quality plugin for GetGrav.org used to differentiate between internal and external links. It also includes the ability of adding rel="nofollow" to links and determines how external links shall be opened via the target attribute. Wikipedia is a well-known example.

Furthermore it enables you to specify multiple domains, each of them on a new line to prevent them from being seen as external sites.

If you are interested in seeing this plugin in action, here is a screenshot:

Installation and Updates

Installing or updating the External Links plugin can be done in one of two ways. Using the GPM (Grav Package Manager) installation update method (i.e. bin/gpm install external_links) or manual install by downloading this plugin and extracting all plugin files to

/your/site/grav/user/plugins/external_links

For more informations, please check the Installation and update guide.

Usage

The External Links plugin comes with some sensible default configuration, that are pretty self explanatory:

Config Defaults

# Global plugin configurations

enabled: true                 # Set to false to disable this plugin completely
built_in_css: true            # Use built-in CSS of the plugin
weight: 0                     # Set the weight (order of execution)

# Default options for External Links configuration

exclude:
  classes: [exclude]          # Exclude all links with this class
  domains:                    # A list of domains to be excluded e.g
  # - localhost/*             # (any RegExp can be used)
  # - img.domain.com/*

links:
  www: false                  # Autom. link any hostname that starts with "www."
  redirects: false            # Also mark links as external, that link to pages that redirect to an external URL

  schemes:                    # Allowed schemes
    - 'http'
    - 'https'
    - 'ftp'
    - 'irc'
    - 'mailto'
    - 'news'
    - 'nntp'
    - 'rtsp'
    - 'sftp'
    - 'ssh'
    - 'tel'
    - 'telnet'
    - 'webcal'

# Global and page specific configurations

process: true                 # Filter external links

title: false                  # Sets default title for external links
no_follow: true               # Add rel="nofollow" to all external links
target: "_blank"              # Set target attribute of link

mode: "active"                # active = process and parse all links;
                              # passive = parse links, but don't set CSS classes

If you need to change any value, then the best process is to copy the external_links.yaml file into your users/config/plugins/ folder (create it if it doesn't exist), and then modify there. This will override the default settings.

If you want to alter the settings for one or a few pages only, you can do so by adding page specific configurations into your page headers, e.g.

external_links: false

to switch off External Links plugin just for this page.

Example

By default External Links adds a small icon to external or mailto links and opens by default links in a new tab. Any links in your Markdown file i.e. of the form

[External Link text](http://domain.com)

or

[External Link text](https://domain.com)

will then be recognized as an external link (an icon on the right is showing up), whereas

[My arcticle](my-article)

will not. You can exclude specific domains not to be seen as external either by adding them to the exlcude.domains option or by adding a class (default: exclude) to the desired links as in the following:

[Domain without external link icon](http://my-specific-domain.com) {.exclude}

Please note that Markdown Extra should be enabled in your user/config/systems.yaml via pages.markdown.extra: true in order to add classes to these links.

Sometimes you maybe wish to explicitly set a link to be "external". Although this should happen in really rare cases, since External links plugin will automatically detect external links, it is possible. Provided that Markdown Extra is enabled, adding the class external to the link will do the trick:

[Always show external link icon](my-external-article) {.external}

CSS Stylesheet Override

Something you might want to do is to override the look and feel of the external links, and with Grav it is super easy.

Copy the stylesheet assets/css/external_links.css into the css folder of your custom theme, and add it to the list of CSS files.

user/themes/custom-theme/css/external_links.css

After that set the built_in_css option of the External Links plugin to false. That's it.

You can now edit, override and tweak it however you prefer. However, this plugin adds extra classes for styling to every link, you might wanna know:

• external, external-link -- Used to identify external links.
• mailto -- Used to identify mailto links.
• no-image -- Set if a link does not contain any image tags.
• icon-- Set if a link contains an image (with size <= 32px).
• image -- Set if a link contains an image (with size > 32px).
• images -- Set if a link contains more than one image.

Twig Filter

External Links provides a Twig filter to process external links inside contents. To do that, place the following line of code in the theme file you wish to add the External Links plugin for:

{{ page.content|external_links }}

You can pass arguments to the plugin filter, namely the same arguments as available in the external_links.yaml file. For example

{{ page.content|external_links({'mode': 'passive'}) }}

will change the mode of the External Links filter to parse links, but don't set CSS classes.

Contributing

You can contribute at any time! Before opening any issue, please search for existing issues and review the guidelines for contributing.

After that please note:

• If you find a bug, would like to make a feature request or suggest an improvement, please open a new issue. If you have any interesting ideas for additions to the syntax please do suggest them as well!
• Feature requests are more likely to get attention if you include a clearly described use case.
• If you wish to submit a pull request, please make again sure that your request match the guidelines for contributing and that you keep track of adding unit tests for any new or changed functionality.

License

Copyright (c) 2017+ Benjamin Regler. See also the list of contributors who participated in this project.

Dual-licensed for use under the terms of the MIT or GPLv3 licenses.