MkDocs plugin to open outgoing links and PDFs in new tab.
Project description
MkDocs - Open in a new tab plugin
This plugin adds JS code to open outgoing links and PDFs in a new tab.
The automatic opening of links in a new tab is a common feature of modern websites. It is also a good practice for accessibility. However, it is not a default behavior of Markdown. This plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab.
Look at the demo.
Installation
Install the plugin using pip from PyPI:
pip install mkdocs-open-in-new-tab
Usage
Add the plugin to your mkdocs.yml:
plugins:
- search
- open-in-new-tab
Configuration
The plugin supports the following configuration option:
add_icon:(default: false)- If set to true, the plugin will add an icon next to external links.
Testing
Link to Google and GitHub. Both should links should open in a new tab.
Relative link to Relative link should open in the same tab.
Sample PDF link to PDF should open in a new tab (pdf from here).
How does it work?
The plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab. Injection of the code is done using the on_page_context hook. The code is injected into the <head> section of the page as a <script> dependency of the open_in_new_tab.js file. The code is automatically added to all pages of your website.
The function external_new_window checks if the link is external using the hostname property of the a element. If the link is external, the target attribute is set to _blank and the rel attribute is set to noopener. The noopener attribute is used to prevent the new tab from accessing the window.opener property and ensures that the original page will not be able to access the new tab.
The same way is used to open PDF links in a new tab.
Show source code
Look at this source open_in_new_tab.js:
// Description: Open external links in a new tab and PDF links in a new tab
// Based on: https://jekyllcodex.org/without-plugin/new-window-fix/
// Open external links in a new window
function external_new_window() {
for(let c = document.getElementsByTagName("a"), a = 0; a < c.length; a++) {
let b = c[a];
if(b.getAttribute("href") && b.host !== location.host) {
b.target = "_blank";
b.rel = "noopener";
}
}
}
// Open PDF links in a new window
function pdf_new_window() {
if (!document.getElementsByTagName) {
return false;
}
const extensions = ['.pdf', '.doc', '.docx', '.json', '.xls', '.xlsx', '.ppt', '.pptx', '.zip', '.rar', '.tar', '.gz', '.7z', '.bz2', '.xz', '.tgz', '.tar.gz'];
let links = document.getElementsByTagName("a");
for (let eleLink = 0; eleLink < links.length; eleLink++) {
let href = links[eleLink].href.toLowerCase(); // Convert href to lowercase for case-insensitive matching
if (extensions.some(ext => href.endsWith(ext))) {
links[eleLink].onclick = function() {
window.open(this.href);
return false;
}
}
}
}
function apply_rules() {
external_new_window();
pdf_new_window();
}
if (typeof document$ !== "undefined") {
// Compatibility with mkdocs-material's instant loading feature
document$.subscribe(function() {
apply_rules();
});
} else {
// For browsers without mkdocs-material's instant loading feature
document.addEventListener("DOMContentLoaded", function() {
apply_rules();
});
}
open_in_new_tab.css (added when add_icon: true)
/*
* Materialize links that open in a new window with a right-up arrow icon
* Author: @ebouchut (https://github.com/ebouchut)
* https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/4
*/
a[target="_blank"]::after {
content: "↗";
display: inline-block;
margin-left: 0.2em;
width: 1em;
height: 1em;
}
License
This project is licensed under the terms of the MIT license.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mkdocs_open_in_new_tab-1.0.7.tar.gz.
File metadata
- Download URL: mkdocs_open_in_new_tab-1.0.7.tar.gz
- Upload date:
- Size: 5.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 8c8bb0bd058d7bfd3ac885802940cf5944de3101492ba765a370cdd2baa754b2 |
|
| MD5 | 23c7f2d8e8880556f5a54bf9ff5106dc |
|
| BLAKE2b-256 | 82e4268866f36a86f28d71939f1ae352eb623145f3befa7c52f0ddf0c4777a40 |
File details
Details for the file mkdocs_open_in_new_tab-1.0.7-py3-none-any.whl.
File metadata
- Download URL: mkdocs_open_in_new_tab-1.0.7-py3-none-any.whl
- Upload date:
- Size: 7.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | b0271be1aea3f0f33cb558a43692e38400725b147ec74da8410e18c990bbf305 |
|
| MD5 | 37bd9657dbec5f4977a718c4d8bb495b |
|
| BLAKE2b-256 | f6382abdc52a3bb220cecb2232fcf81eca7de0b1147a18db76fbd29e0481442b |
