Skip to main content

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.

Metadata

Release files for mkdocs-open-in-new-tab 1.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-open-in-new-tab 1.0.8
File Size Uploaded Provenance Actions
mkdocs_open_in_new_tab-1.0.8.tar.gz 5.8 kB Without provenance Details for mkdocs_open_in_new_tab-1.0.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-open-in-new-tab 1.0.8
File Interpreter ABI Platform Actions
mkdocs_open_in_new_tab-1.0.8-py3-none-any.whl Python 3 none any Details for mkdocs_open_in_new_tab-1.0.8-py3-none-any.whl

Total release size: 13.5 kB

Release files / mkdocs_open_in_new_tab-1.0.8.tar.gz

Download URL mkdocs_open_in_new_tab-1.0.8.tar.gz
Size 5.8 kB
Tags Source
SHA-256 checksum
How to use checksums
3e0dad08cc9938b0b13097be8e0aa435919de1eeb2d1a648e66b5dee8d57e048
BLAKE2b-256 checksum
How to use checksums
0a0ef72a506a21bdb27b807124e00c688226848a388d1fd3980b80ae3cc27203
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.1.1 CPython/3.12.7

Release files / mkdocs_open_in_new_tab-1.0.8-py3-none-any.whl

Download URL mkdocs_open_in_new_tab-1.0.8-py3-none-any.whl
Size 7.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
051d767a4467b12d89827e1fea0ec660b05b027c726317fe4fceee5456e36ad2
BLAKE2b-256 checksum
How to use checksums
219444f3c868495481c868d08eea065c82803f1affd8553d3383b782f497613c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.1.1 CPython/3.12.7

Security for mkdocs-open-in-new-tab 1.0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page