MkDocs Open In New Tab Plugin

1.0.8 · active · verified Thu Apr 16

mkdocs-open-in-new-tab is an MkDocs plugin designed to automatically open outgoing links and PDF files in a new browser tab. As of version 1.0.8, it provides stable functionality for enhancing user navigation in MkDocs-generated documentation sites. Releases are infrequent but stable, addressing key compatibility and feature needs.

Common errors

```
Plugin 'open-in-new-tab' not found.
```
cause The plugin is not installed, or there is a typo in the `mkdocs.yml` configuration.

fix Ensure the plugin is installed (`pip install mkdocs-open-in-new-tab`) and that the `plugins` section in `mkdocs.yml` correctly lists `open-in-new-tab`.
```
YAMLError: while scanning a simple key
```
cause The `mkdocs.yml` configuration file contains invalid YAML syntax (e.g., incorrect indentation, missing colons).

fix Carefully check the indentation and syntax of your `mkdocs.yml` file, especially around the `plugins` section. YAML is sensitive to whitespace.
```
ModuleNotFoundError: No module named 'mkdocs_open_in_new_tab'
```
cause Attempting to import the plugin directly in Python code. MkDocs plugins are not meant to be imported this way.

fix MkDocs plugins are configured in `mkdocs.yml`. Remove any Python `import` statements for `mkdocs_open_in_new_tab` and ensure it's correctly listed under the `plugins` section in your `mkdocs.yml`.

Warnings

gotcha Ensure MkDocs is installed and accessible in your environment. As a plugin, it relies on MkDocs to run and generate documentation.
Fix: Install MkDocs: `pip install mkdocs`
gotcha Versions prior to 1.0.3 had a known issue where they could interfere with MkDocs' instant loading feature, causing navigation problems.
Fix: Upgrade to version 1.0.3 or newer: `pip install --upgrade mkdocs-open-in-new-tab`
gotcha Incorrectly configuring `external_only` or `pdf_only` can lead to unexpected link behavior. For instance, setting `external_only: false` will make *all* links (internal and external) open in new tabs, which might not be desired.
Fix: Review the plugin's configuration options in `mkdocs.yml`. Set `external_only: true` to target only external links, and `pdf_only: true` (or `false`) based on your specific needs for PDF links.

Install

pip install mkdocs-open-in-new-tab Install plugin

Imports

open-in-new-tab
wrong:
```
plugins:
  - mkdocs_open_in_new_tab
```
correct:
```
plugins:
  - open-in-new-tab
```
MkDocs plugins are enabled in mkdocs.yml using their registered plugin name ('open-in-new-tab'), not the PyPI package name ('mkdocs-open-in-new-tab') or a Python import.

Quickstart

To enable the plugin, add 'open-in-new-tab' to the 'plugins' section of your `mkdocs.yml` configuration file. You can optionally configure 'external_only' and 'pdf_only' to control its behavior.

site_name: My Docs

plugins:
  - open-in-new-tab:
      external_only: true  # Only open external links in new tabs
      pdf_only: false      # Do not open PDF links in new tabs

view raw JSON →