193 lines
8.7 KiB
Markdown
193 lines
8.7 KiB
Markdown
# [][project]
|
|
|
|
[][project] [][issues] [](LICENSE "License")
|
|
|
|
> 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](https://github.com/hibbitts-design/grav-plugin-external-links) is the new master repository for this plugin (see [getgrav/grav#2711](https://github.com/getgrav/grav/issues/2711)). Thanks to [@Sommerregen](https://github.com/Sommerregen) for originally developing this Plugin!
|
|
|
|
##### Table of Contents:
|
|
|
|
* [About](#about)
|
|
* [Installation and Updates](#installation-and-updates)
|
|
* [Usage](#usage)
|
|
* [Example](#example)
|
|
* [CSS Stylesheet Override](#css-stylesheet-override)
|
|
* [Twig Filter](#twig-filter)
|
|
* [Contributing](#contributing)
|
|
* [License](#license)
|
|
|
|
## About
|
|
|
|
`External Links` is a high-quality plugin for [GetGrav.org](http://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](https://www.wikipedia.org/) 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](https://github.com/sommerregen/grav-plugin-external-links) and extracting all plugin files to
|
|
|
|
/your/site/grav/user/plugins/external_links
|
|
|
|
For more informations, please check the [Installation and update guide](docs/INSTALL.md).
|
|
|
|
## Usage
|
|
|
|
The `External Links` plugin comes with some sensible default configuration, that are pretty self explanatory:
|
|
|
|
### Config Defaults
|
|
|
|
```yaml
|
|
# 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](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.
|
|
|
|
```yaml
|
|
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
|
|
|
|
```markdown
|
|
[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
|
|
|
|
```markdown
|
|
[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:
|
|
|
|
```markdown
|
|
[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:
|
|
|
|
```markdown
|
|
[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](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](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](docs/CONTRIBUTING.md).
|
|
|
|
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][issues]. 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](docs/CONTRIBUTING.md) and that you keep track of adding unit tests for any new or changed functionality.
|
|
|
|
## License
|
|
|
|
Copyright (c) 2017+ [Benjamin Regler][github]. See also the list of [contributors] who participated in this project.
|
|
|
|
[Dual-licensed](LICENSE) for use under the terms of the [MIT][mit-license] or [GPLv3][gpl-license] licenses.
|
|
|
|
![GNU license - Some rights reserved][gnu]
|
|
|
|
[github]: https://github.com/sommerregen/ "GitHub account from Benjamin Regler"
|
|
[gpl-license]: http://opensource.org/licenses/GPL-3.0 "GPLv3 license"
|
|
[mit-license]: http://www.opensource.org/licenses/mit-license.php "MIT license"
|
|
[gnu]: https://upload.wikimedia.org/wikipedia/commons/thumb/3/33/License_icon-gpl-88x31.svg/88px-License_icon-gpl-88x31.svg.png "GNU license - Some rights reserved"
|
|
|
|
[project]: https://github.com/sommerregen/grav-plugin-external-links
|
|
[issues]: https://github.com/sommerregen/grav-plugin-external-links/issues "GitHub Issues for Grav External Links Plugin"
|
|
[contributors]: https://github.com/sommerregen/grav-plugin-external-links/graphs/contributors "List of contributors of the project"
|